From 772c3e7732b644bb8b485d0a7b4cbab6d5404274 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 10 Nov 2026 13:25:56 +0000 Subject: [PATCH 01/75] Hold the unit suite to a list of Python-route inputs .github/ci-python-inputs.yml lists the repository paths that can change the outcome of the hosted Python job: devcapsule-src, the console, the workflows, and the few files legacy tests still read from the repository, each with its reader named. tests/conftest.py enforces the list on the suite. An audit hook on the interpreter's open, os.listdir and os.scandir events fails a test that opens or lists a repository path outside it, at the access, and the session fails when a breach was recorded. A test does not count when the hosted job does not run it or passes whatever it does: a heavier suite's marker, or an expected-to-fail mark with no condition and no strict. The workflow still routes by .github/ci-paths.yml in this commit. The next one makes it read this list, once the guard has run on the hosted runner, where the tests marked expected to fail inside a capsule run for real. For the bug "Markdown-only changes run the whole Python unit suite". Co-Authored-By: Claude --- .github/ci-python-inputs.yml | 24 ++ devcapsule-src/tests/conftest.py | 198 ++++++++++++++++- .../tests/unit/tests/test_conftest.py | 208 +++++++++++++++++- 3 files changed, 426 insertions(+), 4 deletions(-) create mode 100644 .github/ci-python-inputs.yml diff --git a/.github/ci-python-inputs.yml b/.github/ci-python-inputs.yml new file mode 100644 index 00000000..a7aaccf6 --- /dev/null +++ b/.github/ci-python-inputs.yml @@ -0,0 +1,24 @@ +# The inputs of the hosted Python job: a pull request that changes none of +# these paths skips it. dorny/paths-filter v3 reads this file with its +# default quantifier, so one changed file under one entry selects the route. +# +# An entry is a file path or DIRECTORY/**, nothing else: tests/conftest.py +# reads this same list and fails any unit test that opens or lists a +# repository path outside it, so a path left out here is one no counted test +# can depend on. A new directory needs no entry until a test reads it, and +# then the failing test says so. See RepositoryInputGuard in that file. +python: + - 'devcapsule-src/**' + # The console is a second distribution with its own local gate; its changes + # conservatively run the hosted Python suite, as before this file existed. + - 'devcapsule-webconsole/**' + # The workflows and these filters: tests read them, and a change to how the + # job runs is verified by running it. + - '.github/**' + # Read by unit tests that predate Unit Tests rule 2 of WORKFLOW-LOCAL.md. + # Each entry leaves when its reader builds its own input. + - '.devcapsule/**' # tests/test_base_contract.py, tests/test_repository_manifest_compatibility.py + - 'component-status/**' # tests/test_component_status.py + - 'docs/**' # the [docs] case of tests/unit/devcapsule/legacy_refactoring/test_home.py walks all of docs/; + # tests/test_release_docs.py reads docs/versions.yaml + - 'engineering-docs/releases/v0.2.14/notes.md' # tests/test_release_docs.py diff --git a/devcapsule-src/tests/conftest.py b/devcapsule-src/tests/conftest.py index 1350f921..32b168b2 100644 --- a/devcapsule-src/tests/conftest.py +++ b/devcapsule-src/tests/conftest.py @@ -1,38 +1,77 @@ from __future__ import annotations +from collections.abc import Iterable, Iterator import os from pathlib import Path import shutil import sys import tempfile +from typing import Any, Protocol import pytest +import yaml + +REPOSITORY_ROOT = Path(__file__).resolve().parents[2] +PYTHON_ROUTE_INPUTS = REPOSITORY_ROOT / ".github" / "ci-python-inputs.yml" +"""The list the hosted workflow routes the Python job by, and the list the suite is held to.""" def pytest_configure(config: pytest.Config) -> None: - """Give a macOS run a short temporary root. + """Start the repository-input guard, and give a macOS run a short temporary root. + + The guard fails a test that opens or lists a repository path the hosted + Python job is not routed by; see ``RepositoryInputGuard``. macOS limits a Unix socket path to 104 bytes, and its per-user temporary directory under /var/folders leaves too little of that for the sockets the tests bind beneath tmp_path. An explicit --basetemp still wins. """ + # A copy of this file run outside the repository, as tests/test_isolation.py runs one, guards nothing. + if PYTHON_ROUTE_INPUTS.parent.is_dir(): + guard = RepositoryInputGuard(REPOSITORY_ROOT, load_python_route_inputs(PYTHON_ROUTE_INPUTS)) + config.stash[_INPUT_GUARD] = install_repository_input_guard(guard) if sys.platform == "darwin" and not config.option.basetemp: config.option.basetemp = tempfile.mkdtemp(prefix="dcpt-", dir="/tmp") config.stash[_SHORT_BASETEMP] = Path(config.option.basetemp) _SHORT_BASETEMP = pytest.StashKey[Path]() +_INPUT_GUARD = pytest.StashKey["RepositoryInputGuard"]() + + +@pytest.hookimpl(hookwrapper=True) +def pytest_runtest_protocol(item: pytest.Item) -> Iterator[None]: + """Tell the repository-input guard which test reads, and whether its outcome counts.""" + + guard = item.config.stash.get(_INPUT_GUARD, None) + if guard is not None: + guard.attend(item.nodeid, counted=outcome_counts(item, HEAVIER_SUITE_MARKERS)) + yield + if guard is not None: + guard.leave() def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None: - """Remove the short temporary root this session created, once every test passed. + """Fail a session with repository-input breaches, and remove the short temporary root of a passed one. + + A breach fails its test where it happens. This is the second hold: a + breach recorded although no test failed, because something caught the + failure, still ends the session with a failing status. pytest prunes its own default roots, but not one it was given, so a root per session would otherwise outlive every run and fill the disk; a failed session keeps its root, and its path, for inspection. """ + guard = session.config.stash.get(_INPUT_GUARD, None) + breaches = guard.breaches if guard is not None else [] + if breaches: + print("\nRepository paths read outside the hosted Python job's inputs, .github/ci-python-inputs.yml:") + for reader, path in sorted(set(breaches)): + print(f" {path} read by {reader}") + if exitstatus == pytest.ExitCode.OK: + session.exitstatus = exitstatus = pytest.ExitCode.TESTS_FAILED created = session.config.stash.get(_SHORT_BASETEMP, None) if created is not None and exitstatus == 0: shutil.rmtree(created, ignore_errors=True) @@ -84,6 +123,10 @@ def amd64_linux_host_by_default(request: pytest.FixtureRequest, monkeypatch: pyt """The markers of tests that need the Docker daemon: the end-to-end suites and the integration tests marked ``docker``. They keep the real host and the inherited directories, so builds reuse the real artifact cache.""" +HEAVIER_SUITE_MARKERS = ("integration", *DOCKER_MARKERS) +"""The markers of the suites the hosted Python job does not run. Their tests exercise the real repository +and the real tools, so the repository-input guard leaves them alone.""" + def inherited_cache_home() -> Path: """The cache home the process was started with: ``XDG_CACHE_HOME``, else ``~/.cache``.""" @@ -142,3 +185,154 @@ def built_pex() -> Path: f"Built PEX does not exist: {path}; run the corresponding Nox session" ) return path + + +# The repository-input guard. +# +# .github/ci-python-inputs.yml lists the repository paths whose change runs +# the hosted Python job; a pull request that changes none of them skips it. +# That is sound only while no test whose outcome counts reads a repository +# path outside the list. The guard fails the test that does, in the pull +# request that introduces the read: such a change is a change to a test or to +# the package, and those always run the suite. +# +# What the guard cannot see: a file read by a program a test starts, and a +# path whose existence alone is tested. Every push to main runs the whole +# suite whatever changed, which is the backstop for both. + +OUTSIDE_ANY_TEST = "" +"""The reader named while no test runs: modules are being imported, or the session starts or ends.""" + +_WATCHED_EVENTS = frozenset({"open", "os.listdir", "os.scandir"}) +_GLOB_CHARACTERS = frozenset("*?[]{}()!") +_TREE_SUFFIX = "/**" + + +def load_python_route_inputs(path: Path) -> tuple[str, ...]: + """The Python route's inputs as the filter file lists them. + + An entry is a repository-relative file path, or ``DIRECTORY/**`` for a + directory and everything beneath it. Any other pattern is refused: the + hosted filter and the guard must agree on what an entry matches, and + these two forms are the ones both read the same way. + """ + document = yaml.safe_load(path.read_text(encoding="utf-8")) + entries = document.get("python") if isinstance(document, dict) else None + if not isinstance(entries, list) or not entries: + raise ValueError(f"{path}: expected a non-empty list under 'python'") + for entry in entries: + literal = entry[: -len(_TREE_SUFFIX)] if isinstance(entry, str) and entry.endswith(_TREE_SUFFIX) else entry + if not isinstance(literal, str) or not literal or literal.startswith("/") or _GLOB_CHARACTERS & set(literal): + raise ValueError(f"{path}: {entry!r} is neither a file path nor DIRECTORY/**") + return tuple(entries) + + +class _Marked(Protocol): + def get_closest_marker(self, name: str) -> Any: ... + + +def outcome_counts(item: _Marked, heavier_suite_markers: Iterable[str]) -> bool: + """Whether a test's outcome decides the hosted Python job. + + It does not for a test of a heavier suite, which that job does not run, + nor for a test marked expected to fail without a condition and without + ``strict``: the job passes whatever such a test does. A mark with a + condition holds on some machines only, so its test counts. Removing a + mark makes the outcome count, in a change that runs the suite. + """ + if any(item.get_closest_marker(marker) for marker in heavier_suite_markers): + return False + expected_failure = item.get_closest_marker("xfail") + if expected_failure is None: + return True + return bool(expected_failure.args) or bool(expected_failure.kwargs.get("strict", False)) + + +class RepositoryInputGuard: + """The rule for one repository: a counted reader opens and lists only the Python route's inputs.""" + + def __init__(self, root: Path, inputs: tuple[str, ...]) -> None: + self._root = os.path.abspath(root) + self._trees = tuple(entry[: -len(_TREE_SUFFIX)] for entry in inputs if entry.endswith(_TREE_SUFFIX)) + self._files = frozenset(entry for entry in inputs if not entry.endswith(_TREE_SUFFIX)) + self._reader = OUTSIDE_ANY_TEST + self._counted = True + self.breaches: list[tuple[str, str]] = [] + """Every unlisted access by a counted reader, as ``(reader, repository-relative path)``.""" + + def attend(self, reader: str, *, counted: bool) -> None: + """Name who reads from now on, a test's node id, and whether its outcome counts.""" + self._reader, self._counted = reader, counted + + def leave(self) -> None: + """No test reads from now on; what is read outside any test counts.""" + self._reader, self._counted = OUTSIDE_ANY_TEST, True + + def unlisted(self, path: object) -> str | None: + """The repository-relative form of ``path`` when it lies in the repository outside the inputs. + + ``None`` for a path outside the repository, inside an input, inside + ``.git``, or not a path at all, such as a file descriptor. A relative + path is taken from the current directory, as the read itself takes + it; ``None`` as a path is the current directory, as a listing takes it. + """ + if path is None: + path = "." + if not isinstance(path, (str, bytes, os.PathLike)): + return None + try: + absolute = os.path.abspath(os.fsdecode(path)) + except OSError: # The current directory is gone; the read fails on its own. + return None + if absolute == self._root: + return "." + if not absolute.startswith(self._root + os.sep): + return None + relative = absolute[len(self._root) + 1:].replace(os.sep, "/") + if relative in self._files or relative == ".git" or relative.startswith(".git/"): + return None + if any(relative == tree or relative.startswith(tree + "/") for tree in self._trees): + return None + return relative + + def breach(self, path: object) -> str | None: + """Record the current reader's access to ``path``; the failure message, or ``None`` when it is allowed.""" + relative = self.unlisted(path) + if relative is None or not self._counted: + return None + self.breaches.append((self._reader, relative)) + return ( + f"{self._reader} opens or lists {relative}, which is not an input of the hosted Python job: " + "a change to that path would not run this test. Build the input in the test " + "(Unit Tests, rule 2, in WORKFLOW-LOCAL.md), or list the path in " + ".github/ci-python-inputs.yml with its reader named." + ) + + def audit(self, event: str, arguments: tuple[Any, ...]) -> None: + """The interpreter's audit hook: fail the access to a path that is a breach. + + Opening a file and listing a directory are the watched events; every + other event passes. The failure is ``pytest.fail``'s, an exception no + ``except Exception`` in the code under test can swallow. + """ + if event not in _WATCHED_EVENTS or not arguments: + return + message = self.breach(arguments[0]) + if message is not None: + pytest.fail(message) + + +_installed_guard: RepositoryInputGuard | None = None + + +def install_repository_input_guard(guard: RepositoryInputGuard) -> RepositoryInputGuard: + """Watch this process's file access with ``guard`` and return the guard in force. + + An audit hook cannot be removed, so the first guard installed stays in + force for the life of the process and later calls return it unchanged. + """ + global _installed_guard + if _installed_guard is None: + _installed_guard = guard + sys.addaudithook(guard.audit) + return _installed_guard diff --git a/devcapsule-src/tests/unit/tests/test_conftest.py b/devcapsule-src/tests/unit/tests/test_conftest.py index 37740ce7..f8e9d217 100644 --- a/devcapsule-src/tests/unit/tests/test_conftest.py +++ b/devcapsule-src/tests/unit/tests/test_conftest.py @@ -1,10 +1,22 @@ -"""Unit tests of ``tests/conftest.py``: the shared fixtures and the marker sets they key on.""" +"""Unit tests of ``tests/conftest.py``: the shared fixtures, the marker sets they key on, and the repository-input guard.""" from __future__ import annotations import tomllib from pathlib import Path +from types import SimpleNamespace +from typing import Any -from tests.conftest import DOCKER_MARKERS +import pytest + +from tests import conftest +from tests.conftest import ( + DOCKER_MARKERS, + OUTSIDE_ANY_TEST, + RepositoryInputGuard, + install_repository_input_guard, + load_python_route_inputs, + outcome_counts, +) _PYPROJECT = Path(__file__).resolve().parents[3] / "pyproject.toml" @@ -20,3 +32,195 @@ def test_every_registered_marker_is_a_docker_marker_unless_it_is_a_known_non_doc without the isolation fixture learning that it keeps the developer's homes.""" registered = {entry.split(":", 1)[0] for entry in tomllib.loads(_PYPROJECT.read_text())["tool"]["pytest"]["ini_options"]["markers"]} assert set(DOCKER_MARKERS) == registered - NON_DOCKER_MARKERS + + +def _inputs_file(directory: Path, text: str) -> Path: + """A filter file with the given text, in the test's own directory.""" + path = directory / "ci-python-inputs.yml" + path.write_text(text, encoding="utf-8") + return path + + +def test_the_route_inputs_are_the_listed_entries_in_order(tmp_path: Path) -> None: + """Precondition: a filter file listing a directory tree and a file under ``python``. + Action: load it. Postcondition: both entries, in the order written.""" + listed = _inputs_file(tmp_path, "python:\n - 'package/**' # the package\n - 'docs/versions.yaml'\n") + assert load_python_route_inputs(listed) == ("package/**", "docs/versions.yaml") + + +@pytest.mark.parametrize("text", [ + "python: []\n", + "docs:\n - 'package/**'\n", + "- 'package/**'\n", + "python:\n - 'package/*.py'\n", + "python:\n - 'docs/**/*.md'\n", + "python:\n - '!package/**'\n", + "python:\n - '/package/**'\n", + "python:\n - '**'\n", + "python:\n - 7\n", +]) +def test_a_list_the_guard_cannot_read_as_the_filter_does_is_refused(tmp_path: Path, text: str) -> None: + """Precondition: a filter file with no ``python`` list, or with an entry that is neither a + file path nor ``DIRECTORY/**``. Action: load it. Postcondition: ``ValueError``, so the guard + never matches a pattern differently from the hosted filter.""" + with pytest.raises(ValueError): + load_python_route_inputs(_inputs_file(tmp_path, text)) + + +def _guard(root: Path) -> RepositoryInputGuard: + """A guard over ``root`` whose inputs are one directory tree and one file.""" + return RepositoryInputGuard(root, ("package/**", "docs/versions.yaml")) + + +@pytest.mark.parametrize(("path", "expected"), [ + ("package/module.py", None), + ("package/assets/definition/WORKFLOW.md", None), + ("package", None), + ("docs/versions.yaml", None), + (".git/HEAD", None), + (".git", None), + ("docs/guide.md", "docs/guide.md"), + ("docs", "docs"), + ("package-notes/idea.md", "package-notes/idea.md"), + ("engineering-docs/bugs/a.md", "engineering-docs/bugs/a.md"), + (".github/workflows/tests.yml", ".github/workflows/tests.yml"), + ("", "."), +]) +def test_a_repository_path_is_unlisted_exactly_when_no_entry_covers_it(tmp_path: Path, path: str, expected: str | None) -> None: + """Precondition: a repository root and the two inputs of ``_guard``. Action: ask about an + absolute path under the root. Postcondition: ``None`` under an input or under ``.git``; + otherwise the repository-relative path, with ``.`` for the root itself. A directory whose + name merely begins like an input's is not covered by it.""" + assert _guard(tmp_path).unlisted(tmp_path / path) == expected + + +@pytest.mark.parametrize("path", [7, None, b"elsewhere"]) +def test_what_is_not_a_repository_path_is_never_unlisted(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, path: Any) -> None: + """Precondition: a repository root, and the current directory outside it. Action: ask about a + file descriptor, a missing path that stands for the current directory, and a bytes path + relative to that directory. Postcondition: ``None`` each time.""" + outside = tmp_path / "outside" + outside.mkdir() + monkeypatch.chdir(outside) + assert _guard(tmp_path / "repository").unlisted(path) is None + + +def test_a_relative_path_is_taken_from_the_current_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Precondition: the current directory is ``docs`` inside the repository. Action: ask about + the relative path ``guide.md``, as bytes. Postcondition: ``docs/guide.md``, where the read + itself would look.""" + (tmp_path / "docs").mkdir() + monkeypatch.chdir(tmp_path / "docs") + assert _guard(tmp_path).unlisted(b"guide.md") == "docs/guide.md" + + +def test_a_counted_readers_unlisted_access_is_a_recorded_breach(tmp_path: Path) -> None: + """Precondition: a guard attending a test whose outcome counts. Action: report its access to + an unlisted path. Postcondition: a message naming the test, the path and the filter file, + and the breach on record.""" + guard = _guard(tmp_path) + guard.attend("tests/test_a.py::test_reads_docs", counted=True) + message = guard.breach(tmp_path / "docs" / "guide.md") + assert message is not None + assert "tests/test_a.py::test_reads_docs" in message and "docs/guide.md" in message + assert ".github/ci-python-inputs.yml" in message + assert guard.breaches == [("tests/test_a.py::test_reads_docs", "docs/guide.md")] + + +@pytest.mark.parametrize(("path", "counted"), [("docs/guide.md", False), ("package/module.py", True)]) +def test_an_uncounted_reader_and_a_listed_path_are_no_breach(tmp_path: Path, path: str, counted: bool) -> None: + """Precondition: a guard attending a test. Action: report an unlisted path read by a test + whose outcome does not count, and a listed path read by one whose outcome does. + Postcondition: no message and nothing on record.""" + guard = _guard(tmp_path) + guard.attend("tests/test_a.py::test_one", counted=counted) + assert guard.breach(tmp_path / path) is None + assert guard.breaches == [] + + +def test_what_is_read_outside_any_test_counts(tmp_path: Path) -> None: + """Precondition: a guard that attended an uncounted test and left it. Action: report an + unlisted path. Postcondition: a breach, read by ``OUTSIDE_ANY_TEST``: a module that reads + the repository while it is imported is held to the rule.""" + guard = _guard(tmp_path) + guard.attend("tests/test_a.py::test_expected_to_fail", counted=False) + guard.leave() + assert guard.breach(tmp_path / "README.md") is not None + assert guard.breaches == [(OUTSIDE_ANY_TEST, "README.md")] + + +@pytest.mark.parametrize(("event", "arguments"), [ + ("open", ("docs/guide.md", "r", 0)), + ("os.listdir", ("docs",)), + ("os.scandir", ("docs",)), + ("os.listdir", (None,)), +]) +def test_opening_or_listing_an_unlisted_path_fails_where_it_happens( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, event: str, arguments: tuple[Any, ...], +) -> None: + """Precondition: the current directory is the repository root, which is not an input. + Action: deliver the audit event of an open, of a listing, and of a listing of the current + directory. Postcondition: ``pytest.fail``'s exception, which ``except Exception`` does not + catch, and one breach on record.""" + monkeypatch.chdir(tmp_path) + guard = _guard(tmp_path) + with pytest.raises(pytest.fail.Exception) as failure: + guard.audit(event, arguments) + assert not isinstance(failure.value, Exception) + assert len(guard.breaches) == 1 + + +@pytest.mark.parametrize(("event", "arguments"), [ + ("open", ("package/module.py", "r", 0)), + ("os.remove", ("docs/guide.md", -1)), + ("import", ("docs", None, None, None, None)), + ("open", ()), +]) +def test_other_events_and_listed_paths_pass_the_audit( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, event: str, arguments: tuple[Any, ...], +) -> None: + """Precondition: the current directory is the repository root. Action: deliver an open of a + listed path, two events the guard does not watch, and an event without arguments. + Postcondition: nothing is raised and nothing is recorded.""" + monkeypatch.chdir(tmp_path) + guard = _guard(tmp_path) + guard.audit(event, arguments) + assert guard.breaches == [] + + +def _item(**markers: Any) -> Any: + """A stand-in for a test item carrying the given markers by name.""" + return SimpleNamespace(get_closest_marker=markers.get) + + +def _mark(*args: Any, **kwargs: Any) -> Any: + """A stand-in for a marker with the given arguments.""" + return SimpleNamespace(args=args, kwargs=kwargs) + + +@pytest.mark.parametrize(("item", "counts"), [ + (_item(), True), + (_item(legacy=_mark()), True), + (_item(integration=_mark()), False), + (_item(docker=_mark()), False), + (_item(xfail=_mark(reason="known")), False), + (_item(xfail=_mark(reason="known", strict=False)), False), + (_item(xfail=_mark(reason="known", strict=True)), True), + (_item(xfail=_mark(True, reason="only in a capsule")), True), +]) +def test_an_outcome_counts_unless_the_job_skips_the_test_or_passes_whatever_it_does(item: Any, counts: bool) -> None: + """Precondition: a test item with no marker, a marker of a heavier suite, or an + expected-to-fail mark in each of its forms. Action: ask whether its outcome counts, with + ``integration`` and ``docker`` as the heavier suites. Postcondition: it does not for a + heavier suite or an unconditional, non-strict expected failure; it does otherwise, + because a strict mark can fail the job and a conditional one holds on some machines only.""" + assert outcome_counts(item, ("integration", "docker")) is counts + + +def test_the_first_guard_installed_stays_in_force(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Precondition: a process in which a guard is already installed, set here by the test. + Action: install another. Postcondition: the first is returned and the second is not kept, + since an audit hook cannot be removed.""" + first, second = _guard(tmp_path / "first"), _guard(tmp_path / "second") + monkeypatch.setattr(conftest, "_installed_guard", first) + assert install_repository_input_guard(second) is first From 3bd6cc2717e1033bcbb928df6618b73aebc48c18 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 10 Nov 2026 13:31:09 +0000 Subject: [PATCH 02/75] Route the hosted Python job by its list of inputs The workflow reads .github/ci-python-inputs.yml with its own filter step and the default quantifier: one changed file under one entry runs the unit suite, and any other change skips it, a new directory included. .github/ci-paths.yml keeps the docs route alone. The guard of the previous commit makes the skip sound: no counted test can read a repository path the list leaves out. tests/test_ci_reporting.py was a legacy file and its filter test encoded the old default, so it is refurbished whole under Unit Tests rule 5: ci_gate.py and diff_coverage_annotations.py get their mirrors under tests/unit/scripts and declare their public surface; the route script, both filter files and the real diff-cover run become integration tests in tests/integration/test_ci_workflow.py. docs/** stays an input: one legacy scan reads all of docs/ and counts on the hosted runner, where the old filter skipped it. It leaves the list when that scan is retired. Records: the bug is re-rated major by the owner, targeted at 0.3.1 and in fixing; the blocking record gains the finding that one expected-to-fail unit test downloads 1.5 GB of vendor artifacts inside the owner's capsule on every run. Co-Authored-By: Claude --- .github/ci-paths.yml | 43 +-- .github/workflows/tests.yml | 12 +- devcapsule-src/scripts/ci_gate.py | 2 + .../scripts/diff_coverage_annotations.py | 2 + .../tests/integration/test_ci_workflow.py | 229 ++++++++++++++++ devcapsule-src/tests/test_ci_reporting.py | 258 ------------------ .../tests/unit/scripts/test_ci_gate.py | 78 ++++++ .../scripts/test_diff_coverage_annotations.py | 127 +++++++++ ...-only-changes-run-the-python-unit-suite.md | 71 ++++- ...-the-capsules-mounted-launcher-settings.md | 36 +++ engineering-docs/development/unit-tests.md | 54 +++- engineering-docs/releases/v0.3.1/bugs.md | 3 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 30 +- 13 files changed, 627 insertions(+), 318 deletions(-) create mode 100644 devcapsule-src/tests/integration/test_ci_workflow.py delete mode 100644 devcapsule-src/tests/test_ci_reporting.py create mode 100644 devcapsule-src/tests/unit/scripts/test_ci_gate.py create mode 100644 devcapsule-src/tests/unit/scripts/test_diff_coverage_annotations.py diff --git a/.github/ci-paths.yml b/.github/ci-paths.yml index 6b7be840..86bd1c7c 100644 --- a/.github/ci-paths.yml +++ b/.github/ci-paths.yml @@ -1,35 +1,12 @@ -# dorny/paths-filter v3 with predicate-quantifier: every and picomatch's -# dot: true. Every pattern is a negation, so a changed file selects a route -# unless one of the route's listed non-inputs covers it. A new or unclassified -# path therefore runs the job: nothing escapes verification silently. Under -# picomatch, `a/**` also matches `a` itself, which covers the website gitlink. -python: - # docs/versions.yaml is not excluded: tests/test_release_docs.py reads the - # real manifest, so it is a runtime input. - - '!docs/**/*.md' - - '!README.md' - - '!website/**' - - '!scripts/website.sh' - # engineering-docs is listed by subtree. releases/ stays a runtime input: - # tests/test_release_docs.py reads a published notes file. A new subtree - # runs the suite until it is proven a non-input and listed here. - - '!engineering-docs/README.md' - - '!engineering-docs/archive/**' - - '!engineering-docs/blog/**' - - '!engineering-docs/bugs/**' - - '!engineering-docs/completed-tasks/**' - - '!engineering-docs/decisions/**' - - '!engineering-docs/design-notes/**' - - '!engineering-docs/development/**' - - '!engineering-docs/implementation-notes/**' - - '!engineering-docs/product/**' - - '!engineering-docs/requirements/**' - - '!engineering-docs/session-records/**' - - '!engineering-docs/specifications/**' - - '!engineering-docs/wip/**' - - '!engineering-docs/work-orders/**' - - '!CURRENT-STATUS.md' - - '!index.md' +# The docs route. dorny/paths-filter v3 with predicate-quantifier: every and +# picomatch's dot: true. Every pattern is a negation, so a changed file +# selects the route unless one of its listed non-inputs covers it. A new or +# unclassified path therefore builds the website: nothing escapes that +# verification silently. Under picomatch, `a/**` also matches `a` itself, +# which covers the website gitlink. +# +# The Python route is not here. It is the list of inputs in +# .github/ci-python-inputs.yml, which the unit suite is held to. docs: - '!devcapsule-src/devcapsule/**' - '!devcapsule-src/tests/**' @@ -47,5 +24,3 @@ docs: - '!index.md' # README, docs, journal, release notes, engineering design notes, the website # gitlink, .gitmodules, pyproject version and CI definitions still build docs. -# Console changes conservatively run the existing hosted Python check; that -# check does not replace the separate local nox -s webconsole gate. diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9e4c4a39..cd360790 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -48,13 +48,21 @@ jobs: with: predicate-quantifier: every filters: .github/ci-paths.yml - # tests/test_ci_reporting.py runs this script with each kind of input. + # The Python route is a list of inputs, read with the default quantifier: + # one changed file under one entry selects it. tests/conftest.py holds + # the unit suite to the same list. + - uses: dorny/paths-filter@0e4a8c6effa4802afeda77dc8d303f8176d7dfad # v3.0.4 + if: github.event_name == 'pull_request' + id: python-inputs + with: + filters: .github/ci-python-inputs.yml + # tests/integration/test_ci_workflow.py runs this script with each kind of input. - name: Validate route or select full verification id: route env: EVENT_NAME: ${{ github.event_name }} CHANGED_FILES: ${{ github.event.pull_request.changed_files }} - PYTHON_CHANGED: ${{ steps.filter.outputs.python }} + PYTHON_CHANGED: ${{ steps.python-inputs.outputs.python }} DOCS_CHANGED: ${{ steps.filter.outputs.docs }} run: | if [[ "$EVENT_NAME" != "pull_request" ]]; then diff --git a/devcapsule-src/scripts/ci_gate.py b/devcapsule-src/scripts/ci_gate.py index c8f043dd..46582021 100644 --- a/devcapsule-src/scripts/ci_gate.py +++ b/devcapsule-src/scripts/ci_gate.py @@ -6,6 +6,8 @@ import sys from typing import Any +__all__ = ["check", "main"] + def check(needs: dict[str, Any]) -> None: changes = needs.get("changes", {}) diff --git a/devcapsule-src/scripts/diff_coverage_annotations.py b/devcapsule-src/scripts/diff_coverage_annotations.py index eda6c660..5ba76422 100644 --- a/devcapsule-src/scripts/diff_coverage_annotations.py +++ b/devcapsule-src/scripts/diff_coverage_annotations.py @@ -13,6 +13,8 @@ import sys from typing import Any +__all__ = ["build_annotations", "escape", "main", "publish"] + MAX_ANNOTATIONS = 10 # GitHub's warning annotation limit per step. MAX_SUMMARY_BYTES = 900_000 # Leave room below GitHub's 1 MiB per-step limit. diff --git a/devcapsule-src/tests/integration/test_ci_workflow.py b/devcapsule-src/tests/integration/test_ci_workflow.py new file mode 100644 index 00000000..13d20136 --- /dev/null +++ b/devcapsule-src/tests/integration/test_ci_workflow.py @@ -0,0 +1,229 @@ +"""Integration tests of the hosted workflow's routing, against the repository's own workflow and filter files. + +They read ``.github/workflows/tests.yml`` and the two filter files as they are, run the workflow's +route script under bash, and run git, coverage.py and diff-cover for the advisory report: real +files and real programs, so none of them is a unit test. +""" +from __future__ import annotations + +import fnmatch +import importlib.util +import json +import os +import subprocess +import sys +from pathlib import Path +from typing import Any + +import pytest +import yaml + +from tests.conftest import PYTHON_ROUTE_INPUTS, REPOSITORY_ROOT, RepositoryInputGuard, load_python_route_inputs + +pytestmark = pytest.mark.integration + +_WORKFLOW = REPOSITORY_ROOT / ".github" / "workflows" / "tests.yml" +_DOCS_FILTER = REPOSITORY_ROOT / ".github" / "ci-paths.yml" +_ANNOTATIONS = REPOSITORY_ROOT / "devcapsule-src" / "scripts" / "diff_coverage_annotations.py" + + +def _step(identifier: str) -> dict[str, Any]: + """The step of the workflow's ``changes`` job with the given id.""" + workflow = yaml.safe_load(_WORKFLOW.read_text(encoding="utf-8")) + return next(step for step in workflow["jobs"]["changes"]["steps"] if step.get("id") == identifier) + + +def _picomatch_like(path: str, glob: str) -> bool: + """Mirror picomatch with dot: true for the grammar ``.github/ci-paths.yml`` uses. + + Literal segments, ``*`` within one segment, and ``**`` for any number of + segments including none, so ``a/**`` matches ``a`` itself. Checked against + picomatch 2.3.1, the version paths-filter v3.0.4 bundles. + """ + def match(parts: list[str], segments: list[str]) -> bool: + if not segments: + return not parts + if segments[0] == "**": + return any(match(parts[index:], segments[1:]) for index in range(len(parts) + 1)) + return bool(parts) and fnmatch.fnmatchcase(parts[0], segments[0]) and match(parts[1:], segments[1:]) + return match(path.split("/"), glob.split("/")) + + +@pytest.mark.parametrize(("path", "python"), [ + ("devcapsule-src/tests/a.py", True), + ("devcapsule-src/pyproject.toml", True), + ("devcapsule-src/dev-requirements.txt", True), + ("devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md", True), + ("devcapsule-webconsole/devcapsule_webconsole/app.py", True), + (".github/workflows/tests.yml", True), + (".github/ci-python-inputs.yml", True), + (".devcapsule/devcapsule.toml", True), + ("component-status/policy-v1.json", True), + ("docs/versions.yaml", True), + ("docs/guide.md", True), # walked by a legacy scan; see the filter file + ("engineering-docs/releases/v0.2.14/notes.md", True), + ("engineering-docs/releases/v0.3.1/bugs.md", False), + ("engineering-docs/pile-of-ideas/an-idea.md", False), + ("engineering-docs/bugs/devcapsule/a-bug.md", False), + ("engineering-docs/wip/a/CURRENT-STATUS.md", False), + ("engineering-docs/new-subtree/note.md", False), + ("WORKFLOW.md", False), + ("WORKFLOW-humane.md", False), + ("README.md", False), + ("CURRENT-STATUS.md", False), + ("index.md", False), + (".gitmodules", False), + ("website", False), + ("scripts/website.sh", False), + ("unknown/new-input", False), +]) +def test_the_python_route_is_selected_by_its_listed_inputs_alone(path: str, python: bool) -> None: + """Precondition: the repository's list of Python-route inputs. Action: ask the guard, which + reads an entry as the hosted filter does, whether a changed path is covered. Postcondition: + the package, the console, the workflows and the named legacy inputs select the route; every + other path, known or new, does not.""" + guard = RepositoryInputGuard(REPOSITORY_ROOT, load_python_route_inputs(PYTHON_ROUTE_INPUTS)) + assert (guard.unlisted(REPOSITORY_ROOT / path) is None) is python + + +@pytest.mark.parametrize(("path", "docs"), [ + ("engineering-docs/wip/a/CURRENT-STATUS.md", False), + ("engineering-docs/work-orders/new.md", False), + ("CURRENT-STATUS.md", False), + ("README.md", True), + ("docs/guide.md", True), + ("docs/README.md", True), + ("docs/getting-started/first-session.md", True), + ("docs/versions.yaml", True), + ("engineering-docs/blog/new.md", True), + ("engineering-docs/blog/assets/demo/poster.png", True), + ("engineering-docs/README.md", True), + ("engineering-docs/releases/v0.2.14/notes.md", True), + ("engineering-docs/design-notes/devcapsule/competitive-comparison.md", True), + ("engineering-docs/new-subtree/note.md", True), + ("website", True), + ("website/README.md", True), + ("scripts/website.sh", True), + ("devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md", False), + ("devcapsule-src/tests/a.py", False), + ("devcapsule-src/pyproject.toml", True), + ("devcapsule-src/dev-requirements.txt", False), + ("devcapsule-webconsole/devcapsule_webconsole/app.py", False), + (".gitmodules", True), + (".github/workflows/tests.yml", True), + (".github/ci-paths.yml", True), + (".ast-grep/new.yml", True), + ("WORKFLOW.md", True), + ("unknown/new-input", True), +]) +def test_the_docs_route_is_selected_unless_a_listed_non_input_covers_the_path(path: str, docs: bool) -> None: + """Precondition: the repository's docs filter. Action: match a changed path against every + pattern as picomatch would. Postcondition: every pattern is a negation in the mirrored + grammar, and the route is selected exactly when no listed non-input covers the path, so an + unclassified path builds the website.""" + patterns = yaml.safe_load(_DOCS_FILTER.read_text(encoding="utf-8"))["docs"] + assert all(pattern.startswith("!") and not any(character in pattern[1:] for character in "?[]{}()!") for pattern in patterns) + assert all(not _picomatch_like(path, pattern[1:]) for pattern in patterns) is docs + + +def test_each_filter_file_is_read_with_the_quantifier_its_patterns_assume() -> None: + """Precondition: the workflow as committed. Action: read the two filter steps and the route + step. Postcondition: the docs filter requires every negation to hold; the Python filter + uses the default, any listed input; and the route step takes each route from its own + filter.""" + docs, python, route = _step("filter"), _step("python-inputs"), _step("route") + assert docs["with"] == {"predicate-quantifier": "every", "filters": ".github/ci-paths.yml"} + assert python["with"] == {"filters": ".github/ci-python-inputs.yml"} + assert route["env"]["DOCS_CHANGED"] == "${{ steps.filter.outputs.docs }}" + assert route["env"]["PYTHON_CHANGED"] == "${{ steps.python-inputs.outputs.python }}" + + +def _route(tmp_path: Path, **env: str) -> tuple[int, dict[str, str]]: + """Run the workflow's route script as GitHub's bash would, returning its status and outputs.""" + output = tmp_path / "github-output" + output.touch() + result = subprocess.run( + ["bash", "--noprofile", "--norc", "-eo", "pipefail", "-c", _step("route")["run"]], + env={"PATH": os.environ["PATH"], "GITHUB_OUTPUT": str(output), **env}, + capture_output=True, text=True, + ) + lines = output.read_text(encoding="utf-8").splitlines() + return result.returncode, dict(line.split("=", 1) for line in lines) + + +@pytest.mark.parametrize(("env", "routes"), [ + ({"EVENT_NAME": "pull_request", "PYTHON_CHANGED": "false", "CHANGED_FILES": "17", "DOCS_CHANGED": "true"}, + {"python": "false", "docs": "true"}), + ({"EVENT_NAME": "pull_request", "PYTHON_CHANGED": "false", "CHANGED_FILES": "3000", "DOCS_CHANGED": "false"}, + {"python": "false", "docs": "false"}), + # The filters never see files beyond GitHub's 3000-file listing. + ({"EVENT_NAME": "pull_request", "PYTHON_CHANGED": "false", "CHANGED_FILES": "3001", "DOCS_CHANGED": "false"}, + {"python": "true", "docs": "true"}), + ({"EVENT_NAME": "push", "PYTHON_CHANGED": "", "DOCS_CHANGED": ""}, {"python": "true", "docs": "true"}), + ({"EVENT_NAME": "merge_group", "PYTHON_CHANGED": "", "DOCS_CHANGED": ""}, {"python": "true", "docs": "true"}), + ({"EVENT_NAME": "workflow_dispatch", "PYTHON_CHANGED": "", "DOCS_CHANGED": ""}, {"python": "true", "docs": "true"}), +]) +def test_the_route_step_passes_the_filters_through_and_runs_everything_otherwise( + tmp_path: Path, env: dict[str, str], routes: dict[str, str], +) -> None: + """Precondition: the workflow's route script and one event. Action: run it under bash. + Postcondition: a pull request within GitHub's file listing gets the filters' routes; a + larger one, and every push, merge-queue check and manual run, gets both.""" + assert _route(tmp_path, **env) == (0, routes) + + +@pytest.mark.parametrize("env", [ + {"PYTHON_CHANGED": "", "DOCS_CHANGED": "true"}, + {"PYTHON_CHANGED": "true", "DOCS_CHANGED": "TRUE"}, + {"PYTHON_CHANGED": "true"}, + {"PYTHON_CHANGED": "true", "DOCS_CHANGED": "true", "CHANGED_FILES": ""}, + {"PYTHON_CHANGED": "true", "DOCS_CHANGED": "true", "CHANGED_FILES": "many"}, +]) +def test_the_route_step_fails_without_valid_filter_outputs(tmp_path: Path, env: dict[str, str]) -> None: + """Precondition: a pull request whose filter outputs or changed-file count are missing or + malformed. Action: run the route script under bash. Postcondition: status 1 and no route + written, so the gate cannot read a route that was never decided.""" + code, outputs = _route(tmp_path, **{"EVENT_NAME": "pull_request", "CHANGED_FILES": "17", **env}) + assert code == 1 + assert outputs == {} + + +def test_real_diff_cover_output_yields_an_annotation_for_the_unexecuted_changed_line(tmp_path: Path) -> None: + """Precondition: a git repository with a nested package whose second commit adds a line + that is never executed. Action: run coverage.py and diff-cover on it, then build the + annotations from their JSON. Postcondition: a warning at the repository-relative path and + line of the unexecuted statement, and a changed-line percentage that would fail a + threshold while the bridge stays advisory.""" + spec = importlib.util.spec_from_file_location(_ANNOTATIONS.stem, _ANNOTATIONS) + assert spec and spec.loader + bridge = importlib.util.module_from_spec(spec) + spec.loader.exec_module(bridge) + root = tmp_path / "repo" + package = root / "devcapsule-src" / "devcapsule" / "nested" + package.mkdir(parents=True) + env = {**os.environ, "GIT_AUTHOR_NAME": "Test", "GIT_COMMITTER_NAME": "Test", + "GIT_AUTHOR_EMAIL": "test@example.invalid", "GIT_COMMITTER_EMAIL": "test@example.invalid"} + + def run(*arguments: str, cwd: Path = root) -> subprocess.CompletedProcess[str]: + return subprocess.run(arguments, cwd=cwd, env=env, text=True, capture_output=True, check=True) + + run("git", "init", "-b", "main") + (package.parent / "__init__.py").write_text("", encoding="utf-8") + (package / "__init__.py").write_text("", encoding="utf-8") + source = package / "sample.py" + source.write_text("x = 0\n", encoding="utf-8") + run("git", "add", ".") + run("git", "commit", "-m", "base") + base = run("git", "rev-parse", "HEAD").stdout.strip() + source.write_text('x = 0\nif x:\n print("not run")\n', encoding="utf-8") + run("git", "add", ".") + run("git", "commit", "-m", "change") + working = root / "devcapsule-src" + run(sys.executable, "-m", "coverage", "run", "--branch", "--source=devcapsule", "devcapsule/nested/sample.py", cwd=working) + run(sys.executable, "-m", "coverage", "xml", cwd=working) + run(sys.executable, "-m", "diff_cover.diff_cover_tool", "coverage.xml", + f"--compare-branch={base}", "--format=json:diff-cover.json,markdown:diff-cover.md", cwd=working) + report = json.loads((working / "diff-cover.json").read_text(encoding="utf-8")) + warnings, _ = bridge.build_annotations(report) + assert any("file=devcapsule-src/devcapsule/nested/sample.py,line=3,endLine=3" in warning for warning in warnings) + assert report["total_percent_covered"] < 85 diff --git a/devcapsule-src/tests/test_ci_reporting.py b/devcapsule-src/tests/test_ci_reporting.py deleted file mode 100644 index 1f394b73..00000000 --- a/devcapsule-src/tests/test_ci_reporting.py +++ /dev/null @@ -1,258 +0,0 @@ -"""Independent failure-path and real-tool checks for hosted CI reporting.""" -from __future__ import annotations - -import fnmatch -import importlib.util -import json -import os -from pathlib import Path -import subprocess -import sys -from typing import Any - -import pytest -import yaml - -pytestmark = pytest.mark.legacy - -ROOT = Path(__file__).parents[2] - - -def script(name: str) -> Any: - spec = importlib.util.spec_from_file_location(name, ROOT / 'devcapsule-src/scripts' / f'{name}.py') - assert spec and spec.loader - module = importlib.util.module_from_spec(spec) - spec.loader.exec_module(module) - return module - - -GATE = script('ci_gate') -REPORT = script('diff_coverage_annotations') - - -def needs(python: str = 'true', docs: str = 'true') -> dict[str, Any]: - return {'changes': {'result': 'success', 'outputs': {'python': python, 'docs': docs}}, - 'pytest': {'result': 'success'}, 'docs-build': {'result': 'success'}} - - -def test_gate_accepts_success_and_only_legitimate_skips() -> None: - GATE.check(needs()) - value = needs('false', 'false') - value['pytest']['result'] = value['docs-build']['result'] = 'skipped' - GATE.check(value) - - -@pytest.mark.parametrize('job', ['changes', 'pytest', 'docs-build']) -@pytest.mark.parametrize('result', ['failure', 'cancelled', 'skipped', None]) -def test_gate_rejects_missing_or_unsuccessful_required_job(job: str, result: str | None) -> None: - value = needs() - value[job]['result'] = result - with pytest.raises(ValueError): - GATE.check(value) - - -@pytest.mark.parametrize('route', ['python', 'docs']) -@pytest.mark.parametrize('value', ['', None, True, 'TRUE', 'unknown']) -def test_gate_rejects_invalid_routing(route: str, value: Any) -> None: - jobs = needs() - jobs['changes']['outputs'][route] = value - with pytest.raises(ValueError): - GATE.check(jobs) - - -def test_routing_failure_with_skipped_children_cannot_pass() -> None: - jobs = needs('false', 'false') - jobs['changes']['result'] = 'failure' - jobs['pytest']['result'] = jobs['docs-build']['result'] = 'skipped' - with pytest.raises(ValueError): - GATE.check(jobs) - - -def picomatch_like(path: str, glob: str) -> bool: - """Mirror picomatch with dot: true for the grammar .github/ci-paths.yml uses. - - Literal segments, `*` within one segment, and `**` for any number of - segments including none, so `a/**` matches `a` itself. Checked against - picomatch 2.3.1, the version paths-filter v3.0.4 bundles. - """ - def match(parts: list[str], segments: list[str]) -> bool: - if not segments: - return not parts - if segments[0] == '**': - return any(match(parts[i:], segments[1:]) for i in range(len(parts) + 1)) - return bool(parts) and fnmatch.fnmatchcase(parts[0], segments[0]) and match(parts[1:], segments[1:]) - return match(path.split('/'), glob.split('/')) - - -@pytest.mark.parametrize(('path', 'python', 'docs'), [ - ('engineering-docs/wip/a/CURRENT-STATUS.md', False, False), - ('engineering-docs/work-orders/new.md', False, False), - ('CURRENT-STATUS.md', False, False), - ('README.md', False, True), - ('docs/guide.md', False, True), - ('docs/README.md', False, True), - ('docs/getting-started/first-session.md', False, True), - ('docs/versions.yaml', True, True), # read by tests/test_release_docs.py - ('engineering-docs/blog/new.md', False, True), - ('engineering-docs/blog/assets/demo/poster.png', False, True), - ('engineering-docs/README.md', False, True), - ('engineering-docs/releases/v0.2.14/notes.md', True, True), # read by tests/test_release_docs.py - ('engineering-docs/design-notes/devcapsule/competitive-comparison.md', False, True), - ('engineering-docs/new-subtree/note.md', True, True), - ('website', False, True), - ('website/README.md', False, True), - ('scripts/website.sh', False, True), - ('devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md', True, False), - ('devcapsule-src/tests/a.py', True, False), - ('devcapsule-src/pyproject.toml', True, True), - ('devcapsule-src/dev-requirements.txt', True, False), - ('devcapsule-webconsole/devcapsule_webconsole/app.py', True, False), - ('.gitmodules', True, True), - ('.github/workflows/tests.yml', True, True), - ('.github/ci-paths.yml', True, True), - ('.ast-grep/new.yml', True, True), - ('WORKFLOW.md', True, True), # read by tests/test_workflow_bootstrap.py - ('unknown/new-input', True, True), -]) -def test_known_exemptions_and_conservative_unknown_paths(path: str, python: bool, docs: bool) -> None: - filters = yaml.safe_load((ROOT / '.github/ci-paths.yml').read_text()) - for route, expected in [('python', python), ('docs', docs)]: - patterns = filters[route] - # Every pattern is a negation within picomatch_like's grammar. - assert all(p.startswith('!') and not any(c in p[1:] for c in '?[]{}()!') for p in patterns) - assert all(not picomatch_like(path, p[1:]) for p in patterns) is expected - workflow = yaml.safe_load((ROOT / '.github/workflows/tests.yml').read_text()) - filters_step = next(s for s in workflow['jobs']['changes']['steps'] if s.get('id') == 'filter') - assert filters_step['with']['predicate-quantifier'] == 'every' - - -def route_step(tmp_path: Path, **env: str) -> tuple[int, dict[str, str]]: - """Run the workflow's route script as GitHub's bash would, returning its outputs.""" - workflow = yaml.safe_load((ROOT / '.github/workflows/tests.yml').read_text()) - step = next(s for s in workflow['jobs']['changes']['steps'] if s.get('id') == 'route') - output = tmp_path / 'github-output' - output.touch() - result = subprocess.run(['bash', '--noprofile', '--norc', '-eo', 'pipefail', '-c', step['run']], - env={'PATH': os.environ['PATH'], 'GITHUB_OUTPUT': str(output), **env}, - capture_output=True, text=True) - lines = output.read_text().splitlines() - return result.returncode, dict(line.split('=', 1) for line in lines) - - -def test_route_step_passes_valid_filters_and_runs_everything_otherwise(tmp_path: Path) -> None: - pr = {'EVENT_NAME': 'pull_request', 'PYTHON_CHANGED': 'false'} - assert route_step(tmp_path, **pr, CHANGED_FILES='17', DOCS_CHANGED='true') == ( - 0, {'python': 'false', 'docs': 'true'}) - assert route_step(tmp_path, **pr, CHANGED_FILES='3000', DOCS_CHANGED='false') == ( - 0, {'python': 'false', 'docs': 'false'}) - # The filter never sees files beyond GitHub's 3000-file listing. - assert route_step(tmp_path, **pr, CHANGED_FILES='3001', DOCS_CHANGED='false') == ( - 0, {'python': 'true', 'docs': 'true'}) - for event in ['push', 'merge_group', 'workflow_dispatch']: - assert route_step(tmp_path, EVENT_NAME=event, PYTHON_CHANGED='', DOCS_CHANGED='') == ( - 0, {'python': 'true', 'docs': 'true'}) - - -@pytest.mark.parametrize('env', [ - {'PYTHON_CHANGED': '', 'DOCS_CHANGED': 'true'}, - {'PYTHON_CHANGED': 'true', 'DOCS_CHANGED': 'TRUE'}, - {'PYTHON_CHANGED': 'true'}, - {'PYTHON_CHANGED': 'true', 'DOCS_CHANGED': 'true', 'CHANGED_FILES': ''}, - {'PYTHON_CHANGED': 'true', 'DOCS_CHANGED': 'true', 'CHANGED_FILES': 'many'}, -]) -def test_route_step_fails_without_valid_inputs(tmp_path: Path, env: dict[str, str]) -> None: - code, outputs = route_step(tmp_path, **{'EVENT_NAME': 'pull_request', 'CHANGED_FILES': '17', **env}) - assert code == 1 - assert outputs == {} - - -def report(lines: list[int], covered: list[int] | None = None) -> dict[str, Any]: - covered = covered or [] - return {'src_stats': {'devcapsule-src/devcapsule/a.py': - {'violation_lines': lines, 'covered_lines': covered}}, - 'total_num_lines': len(lines) + len(covered), 'total_num_violations': len(lines)} - - -def test_uncovered_ranges_are_advisory_and_grouped() -> None: - warnings, measured = REPORT.build_annotations(report([5, 2, 3])) - assert measured == 3 - assert len(warnings) == 2 - assert 'line=2,endLine=3' in warnings[0] - assert 'line=5,endLine=5' in warnings[1] - assert all(w.startswith('::warning ') for w in warnings) - - -@pytest.mark.parametrize('bad', [{}, {'src_stats': {}}, report([0]), report([True]), report([2, 2])]) -def test_invalid_report_is_not_misreported_as_covered(bad: Any) -> None: - with pytest.raises(ValueError): - REPORT.build_annotations(bad) - - -def test_totals_overlap_and_unsafe_paths_are_rejected() -> None: - data = report([2], [2]) - with pytest.raises(ValueError, match='overlap'): - REPORT.build_annotations(data) - data = report([2]); data['total_num_lines'] = 10 - with pytest.raises(ValueError, match='totals'): - REPORT.build_annotations(data) - for name in ['../a.py', '/tmp/a.py', 'devcapsule/a.py', 'devcapsule-src/devcapsule/../a.py']: - data = report([2]); data['src_stats'][name] = data['src_stats'].pop('devcapsule-src/devcapsule/a.py') - with pytest.raises(ValueError, match='path'): - REPORT.build_annotations(data) - - -def test_workflow_command_properties_are_escaped() -> None: - assert REPORT.escape('a%,:\r\n.py', property_value=True) == 'a%25%2C%3A%0D%0A.py' - - -def test_warning_budget_and_full_report_preserved(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: - data = report(list(range(1, 28, 2))) - source, md, summary = (tmp_path / n for n in ['report.json', 'report.md', 'summary.md']) - source.write_text(json.dumps(data)); md.write_text('Complete table\n') - REPORT.publish(source, md, summary) - assert capsys.readouterr().out.count('::warning ') == 10 - assert '10 of 14' in summary.read_text() - assert 'Complete table' in summary.read_text() - assert json.loads(source.read_text()) == data - - -def test_not_applicable_is_explicit(tmp_path: Path) -> None: - source, md, summary = (tmp_path / n for n in ['report.json', 'report.md', 'summary.md']) - source.write_text(json.dumps(report([]))); md.write_text('No lines\n') - REPORT.publish(source, md, summary) - assert 'Not applicable' in summary.read_text() - - -def test_missing_report_fails_cli(tmp_path: Path) -> None: - result = subprocess.run([sys.executable, str(ROOT / 'devcapsule-src/scripts/diff_coverage_annotations.py')], - cwd=tmp_path, env={**os.environ, 'GITHUB_STEP_SUMMARY': str(tmp_path/'summary')}, - capture_output=True, text=True) - assert result.returncode == 1 - assert 'reporting failed' in result.stderr - - -def test_real_diff_cover_json_paths_and_advisory_exit(tmp_path: Path) -> None: - """Use actual coverage + diff-cover on an unexecuted changed line in a nested package path.""" - root = tmp_path / 'repo'; root.mkdir() - package = root / 'devcapsule-src/devcapsule/nested'; package.mkdir(parents=True) - env = {**os.environ, 'GIT_AUTHOR_NAME': 'Test', 'GIT_COMMITTER_NAME': 'Test', - 'GIT_AUTHOR_EMAIL': 'test@example.invalid', 'GIT_COMMITTER_EMAIL': 'test@example.invalid'} - def run(*args: str, cwd: Path = root) -> subprocess.CompletedProcess[str]: - return subprocess.run(args, cwd=cwd, env=env, text=True, capture_output=True, check=True) - run('git', 'init', '-b', 'main') - (package.parent / '__init__.py').write_text(''); (package / '__init__.py').write_text('') - source = package / 'sample.py'; source.write_text('x = 0\n') - run('git', 'add', '.'); run('git', 'commit', '-m', 'base') - base = run('git', 'rev-parse', 'HEAD').stdout.strip() - source.write_text('x = 0\nif x:\n print("not run")\n') - run('git', 'add', '.'); run('git', 'commit', '-m', 'change') - working = root / 'devcapsule-src' - run(sys.executable, '-m', 'coverage', 'run', '--branch', '--source=devcapsule', - 'devcapsule/nested/sample.py', cwd=working) - run(sys.executable, '-m', 'coverage', 'xml', cwd=working) - run(sys.executable, '-m', 'diff_cover.diff_cover_tool', 'coverage.xml', - f'--compare-branch={base}', '--format=json:diff-cover.json,markdown:diff-cover.md', cwd=working) - data = json.loads((working / 'diff-cover.json').read_text()) - warnings, _ = REPORT.build_annotations(data) - assert any('file=devcapsule-src/devcapsule/nested/sample.py,line=3,endLine=3' in w for w in warnings) - assert data['total_percent_covered'] < 85 diff --git a/devcapsule-src/tests/unit/scripts/test_ci_gate.py b/devcapsule-src/tests/unit/scripts/test_ci_gate.py new file mode 100644 index 00000000..ac1fa6f0 --- /dev/null +++ b/devcapsule-src/tests/unit/scripts/test_ci_gate.py @@ -0,0 +1,78 @@ +"""Unit tests of ``scripts/ci_gate.py``: the hosted gate fails closed on routing and on every selected job.""" +from __future__ import annotations + +import importlib.util +from pathlib import Path +from typing import Any + +import pytest + +_SCRIPT = Path(__file__).resolve().parents[3] / "scripts" / "ci_gate.py" + + +def _load(path: Path) -> Any: + """The script as a module.""" + spec = importlib.util.spec_from_file_location(path.stem, path) + assert spec and spec.loader + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +gate = _load(_SCRIPT) + + +def _needs(python: str = "true", docs: str = "true") -> dict[str, Any]: + """The ``needs`` context of a run in which routing and both jobs succeeded.""" + return { + "changes": {"result": "success", "outputs": {"python": python, "docs": docs}}, + "pytest": {"result": "success"}, + "docs-build": {"result": "success"}, + } + + +def test_the_gate_passes_when_every_selected_job_succeeded() -> None: + """Precondition: both routes selected, routing and both jobs successful. Action: check. + Postcondition: nothing is raised.""" + gate.check(_needs()) + + +def test_the_gate_passes_when_an_unselected_job_was_skipped() -> None: + """Precondition: neither route selected, and both jobs skipped. Action: check. + Postcondition: nothing is raised; a skip is legitimate only for a job its route left out.""" + needs = _needs("false", "false") + needs["pytest"]["result"] = needs["docs-build"]["result"] = "skipped" + gate.check(needs) + + +@pytest.mark.parametrize("job", ["changes", "pytest", "docs-build"]) +@pytest.mark.parametrize("result", ["failure", "cancelled", "skipped", None]) +def test_a_selected_job_that_did_not_succeed_fails_the_gate(job: str, result: str | None) -> None: + """Precondition: both routes selected, and one of routing or the two jobs failed, was + cancelled, was skipped, or reported nothing. Action: check. Postcondition: ``ValueError``.""" + needs = _needs() + needs[job]["result"] = result + with pytest.raises(ValueError): + gate.check(needs) + + +@pytest.mark.parametrize("route", ["python", "docs"]) +@pytest.mark.parametrize("value", ["", None, True, "TRUE", "unknown"]) +def test_a_route_that_is_not_true_or_false_fails_the_gate(route: str, value: Any) -> None: + """Precondition: every job successful, and one route output that is not the string ``true`` + or ``false``. Action: check. Postcondition: ``ValueError``.""" + needs = _needs() + needs["changes"]["outputs"][route] = value + with pytest.raises(ValueError): + gate.check(needs) + + +def test_failed_routing_fails_the_gate_although_both_jobs_were_skipped() -> None: + """Precondition: routing failed after reporting neither route selected, so both jobs were + skipped. Action: check. Postcondition: ``ValueError``; skipped children cannot pass a gate + whose routing did not succeed.""" + needs = _needs("false", "false") + needs["changes"]["result"] = "failure" + needs["pytest"]["result"] = needs["docs-build"]["result"] = "skipped" + with pytest.raises(ValueError): + gate.check(needs) diff --git a/devcapsule-src/tests/unit/scripts/test_diff_coverage_annotations.py b/devcapsule-src/tests/unit/scripts/test_diff_coverage_annotations.py new file mode 100644 index 00000000..5b06e0b9 --- /dev/null +++ b/devcapsule-src/tests/unit/scripts/test_diff_coverage_annotations.py @@ -0,0 +1,127 @@ +"""Unit tests of ``scripts/diff_coverage_annotations.py``: advisory annotations from a diff-cover report.""" +from __future__ import annotations + +import importlib.util +import json +import sys +from pathlib import Path +from typing import Any + +import pytest + +_SCRIPT = Path(__file__).resolve().parents[3] / "scripts" / "diff_coverage_annotations.py" +_SOURCE = "devcapsule-src/devcapsule/a.py" + + +def _load(path: Path) -> Any: + """The script as a module.""" + spec = importlib.util.spec_from_file_location(path.stem, path) + assert spec and spec.loader + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +bridge = _load(_SCRIPT) + + +def _report(lines: list[int], covered: list[int] | None = None, source: str = _SOURCE) -> dict[str, Any]: + """A diff-cover JSON report of one source file with the given uncovered and covered lines.""" + covered = covered or [] + return { + "src_stats": {source: {"violation_lines": lines, "covered_lines": covered}}, + "total_num_lines": len(lines) + len(covered), + "total_num_violations": len(lines), + } + + +def _files(directory: Path, report: dict[str, Any], markdown: str) -> tuple[Path, Path, Path]: + """The report, its Markdown rendering and an empty step summary, in the test's directory.""" + source, rendered, summary = (directory / name for name in ("report.json", "report.md", "summary.md")) + source.write_text(json.dumps(report), encoding="utf-8") + rendered.write_text(markdown, encoding="utf-8") + return source, rendered, summary + + +def test_uncovered_lines_become_one_warning_per_contiguous_range() -> None: + """Precondition: a report with uncovered lines 5, 2 and 3. Action: build the annotations. + Postcondition: three measured lines, and two warnings, for lines 2 to 3 and for line 5.""" + warnings, measured = bridge.build_annotations(_report([5, 2, 3])) + assert measured == 3 + assert len(warnings) == 2 + assert "line=2,endLine=3" in warnings[0] + assert "line=5,endLine=5" in warnings[1] + assert all(warning.startswith("::warning ") for warning in warnings) + + +@pytest.mark.parametrize("report", [{}, {"src_stats": {}}, _report([0]), _report([True]), _report([2, 2])]) +def test_a_malformed_report_is_refused_rather_than_read_as_covered(report: Any) -> None: + """Precondition: a report with no statistics, or with a line number that is zero, a + boolean, or repeated. Action: build the annotations. Postcondition: ``ValueError``.""" + with pytest.raises(ValueError): + bridge.build_annotations(report) + + +def test_a_line_both_covered_and_uncovered_is_refused() -> None: + """Precondition: a report naming line 2 as covered and as uncovered. Action: build the + annotations. Postcondition: ``ValueError`` naming the overlap.""" + with pytest.raises(ValueError, match="overlap"): + bridge.build_annotations(_report([2], [2])) + + +def test_totals_that_disagree_with_the_lines_are_refused() -> None: + """Precondition: a report of one line whose total says ten. Action: build the annotations. + Postcondition: ``ValueError`` naming the totals.""" + report = _report([2]) + report["total_num_lines"] = 10 + with pytest.raises(ValueError, match="totals"): + bridge.build_annotations(report) + + +@pytest.mark.parametrize("source", ["../a.py", "/tmp/a.py", "devcapsule/a.py", "devcapsule-src/devcapsule/../a.py"]) +def test_a_source_path_outside_the_package_is_refused(source: str) -> None: + """Precondition: a report whose source path climbs out, is absolute, or is not under + ``devcapsule-src/devcapsule``. Action: build the annotations. Postcondition: ``ValueError`` + naming the path.""" + with pytest.raises(ValueError, match="path"): + bridge.build_annotations(_report([2], source=source)) + + +def test_a_property_value_is_escaped_for_a_workflow_command() -> None: + """Precondition: a file name holding a percent sign, a comma, a colon and a line break. + Action: escape it as a property value. Postcondition: each is percent-encoded.""" + assert bridge.escape("a%,:\r\n.py", property_value=True) == "a%25%2C%3A%0D%0A.py" + + +def test_publishing_emits_at_most_ten_warnings_and_keeps_the_whole_report(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: + """Precondition: a report of fourteen separate uncovered lines and its Markdown table. + Action: publish. Postcondition: ten warnings on standard output, a summary that says ten + of fourteen and carries the whole table, and the report file unchanged.""" + report = _report(list(range(1, 28, 2))) + source, rendered, summary = _files(tmp_path, report, "Complete table\n") + bridge.publish(source, rendered, summary) + assert capsys.readouterr().out.count("::warning ") == 10 + assert "10 of 14" in summary.read_text(encoding="utf-8") + assert "Complete table" in summary.read_text(encoding="utf-8") + assert json.loads(source.read_text(encoding="utf-8")) == report + + +def test_a_diff_with_no_measured_line_is_published_as_not_applicable(tmp_path: Path) -> None: + """Precondition: a report with no line at all. Action: publish. Postcondition: the summary + says the report is not applicable.""" + source, rendered, summary = _files(tmp_path, _report([]), "No lines\n") + bridge.publish(source, rendered, summary) + assert "Not applicable" in summary.read_text(encoding="utf-8") + + +def test_the_program_fails_when_the_report_is_missing( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], +) -> None: + """Precondition: a current directory with no diff-cover report, no arguments, and a step + summary path. Action: run ``main``. Postcondition: status 1 and the failure on standard + error; a missing report never passes as covered.""" + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("GITHUB_STEP_SUMMARY", str(tmp_path / "summary.md")) + monkeypatch.setattr(sys, "argv", [_SCRIPT.name]) + assert bridge.main() == 1 + assert "reporting failed" in capsys.readouterr().err diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md b/engineering-docs/bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md index 4bd0830e..7a0d4162 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md @@ -1,7 +1,7 @@ --- -status: confirmed -severity: minor -target: none +status: fixing +severity: major +target: 0.3.1 owner: maintenance opened: 2026-11-10 requirements: [] @@ -75,8 +75,14 @@ Nothing else was opened: not `WORKFLOW-humane.md`, `WORKFLOW-LOCAL.md`, under `engineering-docs/` except that one notes file. A second finding from the same run: the filter lists `docs/**/*.md` as a -non-input of the Python route, yet a test reads fifty of those files. The -listing is harmless only while that test stays marked expected to fail. +non-input of the Python route, yet a test reads fifty of those files. + +Corrected the same day. That test's expected-to-fail mark carries a +condition, `IN_CAPSULE`: it holds inside a capsule only. On the hosted runner +the `[docs]` case of `test_replaced_scope_word_is_absent` runs for real and +its outcome counts, so the old filter skipped a counted test on every +docs-only pull request. The same is true of the other tests marked on +2026-11-04: on the hosted runner they are ordinary tests. Limits of the measurement: @@ -112,9 +118,58 @@ Local: `nox -s tests` and `nox -s build` take no account of what changed. run may be left out, so an agent that follows it runs the whole suite for any change. -## Fix notes - -Not started. The choices are the owner's. +## Rating + +Re-rated by the owner on 2026-11-10 from minor to major: whatever slows the +work and breaks its rhythm is major. The target is 0.3.1, the release the +fix branch is cut from; the owner did not name it and may change it. + +## Fix, on `ws-maintenance/python-route-guard` + +The owner's concern with any shorter list was that a later test, or an +expected-to-fail test that loses its mark, would come to depend on a file +the filter skips, and would silently not run. The fix makes that +impossible to merge rather than unlikely, and the owner chose its wider +form on 2026-11-10: the Python route is a short list of inputs, and +everything else is skipped. + +- `.github/ci-python-inputs.yml` lists the inputs: `devcapsule-src/`, the + console, `.github/`, and the paths legacy tests still read from the + repository, each with its reader named. `.github/ci-paths.yml` keeps the + docs route only. The workflow reads each file with its own filter step. +- `tests/conftest.py` holds the suite to the same list. An audit hook fails + a counted test that opens or lists a repository path outside it, at the + access, and the session fails if a breach was recorded. A dependency on an + unlisted file can only arrive in a change to a test or to the package, + which runs the suite, where the guard refuses it. Removing an + expected-to-fail mark is such a change. +- What the suite reads outside `devcapsule-src/`, measured again for every + kind of file with the Nox environment: `.devcapsule/` (two files), + `.github/` (four), `component-status/policy-v1.json`, + `docs/versions.yaml`, `engineering-docs/releases/v0.2.14/notes.md`, and + all of `docs/` through the scan named above. Nothing else. +- `tests/test_ci_reporting.py`, a legacy file whose filter test the change + breaks, is refurbished whole under *Unit Tests* rule 5: the gate and the + annotation bridge into `tests/unit/scripts/`, the route script, both + filter files and the real diff-cover run into + `tests/integration/test_ci_workflow.py`. + +What this does not yet give: + +- `docs/**` is an input, so a docs-only pull request now runs the suite, + where the old filter skipped it unsoundly. It leaves the list when the + `[docs]` scan no longer reads the repository, which rule 5 ties to + refurbishing `tests/test_home.py`. +- The local gate still runs everything; close criterion 2 is open. +- The routing tests no longer run in the hosted job, since they are + integration tests; they run with `nox -s integration`. +- The guard does not see a file read by a program a test starts, nor a + path whose existence alone is tested. Every push to `main` runs the whole + suite. + +## Fix notes as first written + +The choices were the owner's; kept for the record. - Hosted, the small step: list the proven non-inputs. `engineering-docs/pile-of-ideas/**` and `WORKFLOW-humane.md` are read by diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index b263e6e2..14fd3253 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -77,6 +77,38 @@ Markdown changes only, and on an extract of the tag `v0.3.1-rc2`. environment, whose installed metadata still says 0.2.15; the gate run used the environment Nox built. The 17 failures are from the gate run. +### A unit test downloads vendor artifacts + +Found on 2026-11-10 while running the suite for another change. +`test_offered_agent_still_needs_consent_and_can_be_omitted`, in +`tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py`, runs +`project run --print-command` and expects it to stop for consent to the +Claude Code channel. In the owner's capsule the mounted settings have +accepted that channel, so the launch preparation goes on to acquire the +project's artifacts from the network, into the test's own cache under its +temporary directory: + +- 1,490 MB in that one test's directory after the run, among them four + files of 326, 205, 187 and 114 MB under + `user/cache/devcapsule/artifacts/sha256/`. The largest carries the digest + `426c3381…bf61f`, the Claude Code 2.1.321 `linux-x64` build pinned for + 0.3.1. +- The test process was observed in that test for more than ten minutes, + with a download file growing and an HTTPS connection open. The whole run + took 727 s without coverage; the gate run of the same day took 733 s with + it. A run with the mounted settings hidden took 70 s, though 41 of its + tests ended early for an unrelated reason, a temporary path too long for + a Unix socket. +- The test is marked expected to fail inside a capsule, so it reports as an + expected failure after the download and nothing looks wrong. +- pytest keeps the temporary roots of its last three runs under + `/tmp/pytest-of-`. Inside a capsule `/tmp` is a 2 GB tmpfs, so the + second or third run of the suite fills it; it did on 2026-11-10, with + `No space left on device`. + +So the twelve minutes of the local unit gate, and the overflow of `/tmp` +that `WORKFLOW-LOCAL.md` warns about, come largely from this cause. + ## Cause `settings_source` in `devcapsule/configuration/storage.py` returns the @@ -116,6 +148,9 @@ The owner's rating of 2026-11-10: this is fixed before 0.3.1 ships. failures, and the release procedure's own gate cannot pass from a capsule. - It grows without anyone touching the code: each channel a developer accepts changes which tests fail. +- It makes a unit test download more than a gigabyte of vendor software on + every run, which is most of the local gate's twelve minutes and what + fills the capsule's `/tmp`. This supersedes, for this cause, the disposition in the 0.3.1 bug table that the tests expected to fail inside a capsule are not a release gate. @@ -163,6 +198,7 @@ Not in this record: same counts. 3. No expected-to-fail mark remains whose reason is the mounted settings: each such test passes unmarked or is rewritten under rule 5. + No unit test opens a network connection in that run. 4. `engineering-docs/development/unit-tests.md` describes `private_user_directories` as a private home without the exception. diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index 6dc08955..fa32de23 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -42,19 +42,31 @@ replaced on every run and the author's text around it is never touched. A pull request from a fork gets a read-only token, so its description is left alone; the job summary and the uploaded coverage reports still carry the figures. -The hosted `tests.yml` workflow selects the existing serial unit suite when -runtime, test, build or unclassified inputs change. It runs no Docker. -Planning/status-only PRs skip heavy jobs; website inputs run the website's -own tests and build. The filters live in `.github/ci-paths.yml`: each route -lists the paths proven not to be its inputs, and any other changed path runs -the job. Root README, journal entries and release notes are website inputs, -while packaged Markdown under `devcapsule-src/` remains a runtime input, and -so do `docs/versions.yaml` and the published release notes, which the unit -suite reads as fixtures. A pull request with more than 3000 changed files -runs everything, because GitHub's changed-file listing stops there. Console -changes conservatively run the hosted Python suite, but its runtime coverage -does not measure the separate console distribution; the local -`nox -s webconsole` gate still applies. +The hosted `tests.yml` workflow routes each pull request by the paths it +changes, and runs no Docker. The two routes are decided differently. + +The Python route runs the serial unit suite when a changed file is one of +its inputs, listed in `.github/ci-python-inputs.yml`: the package and its +tests under `devcapsule-src/`, the console, the workflows, and a few files +that legacy tests still read from the repository, each named with its +reader. Any other change skips the suite, a new directory included. That is +sound because the suite is held to the same list: the repository-input guard +in `tests/conftest.py` fails a test that opens or lists a repository path +outside it (see Fixtures). A dependency on an unlisted file can only arrive +in a change to a test or to the package, which runs the suite, where the +guard refuses it. An entry is a file path or `DIRECTORY/**` and nothing +else, so the filter and the guard read it the same way. + +The docs route builds the website unless every changed file is a listed +non-input in `.github/ci-paths.yml`; an unclassified path builds it. Root +README, journal entries and release notes are website inputs. + +A pull request with more than 3000 changed files runs everything, because +GitHub's changed-file listing stops there. Console changes conservatively +run the hosted Python suite, but its runtime coverage does not measure the +separate console distribution; the local `nox -s webconsole` gate still +applies. The routing itself, the route script and both filter files, is +tested by `tests/integration/test_ci_workflow.py`. Main pushes, merge-queue checks and manual runs use full applicable verification. PRs into `main` and `release-*` test the PR head SHA. The advisory diff report @@ -152,6 +164,22 @@ so prefer the existing laws and an acceptance step for what the user sees. root under `/tmp`, because a Unix socket path there is limited to 104 bytes. A session whose tests all passed removes it; a failed one keeps it and prints its path. +- The repository-input guard, `RepositoryInputGuard`, started by + `pytest_configure`: an audit hook on the interpreter's `open`, + `os.listdir` and `os.scandir` events. A test that opens or lists a + repository path outside `.github/ci-python-inputs.yml` fails at that + access, with a message naming the test, the path and the two ways out: + build the input in the test, or list the path with its reader named. + `.git` is exempt. A read while modules are imported counts. A test does + not count when the hosted job does not run it, the integration and + end-to-end suites, or passes whatever it does: an expected-to-fail mark + with no condition and no `strict`. A mark with a condition, such as the + ones that hold only inside a capsule, leaves the test counted, because + the hosted runner runs it for real. `pytest_sessionfinish` lists every + breach and fails a session that recorded one, in case something caught + the failure. The guard does not see a file read by a program a test + starts, nor a path whose existence alone is tested; every push to `main` + runs the whole suite and is the backstop. Everything else is local to its module: fakes for Docker and vendor services, temporary XDG roots, and the `tmp_path` pytest provides. diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 051874f4..5f504d71 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,8 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | confirmed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; no fix started | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | confirmed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; no fix started | +| [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled again until the next candidate. diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index be53b385..d3ded1e2 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, on `ws-maintenance/python-route-guard` Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d92bdcbb0a01 @@ -12,10 +12,36 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/pile-of-ideas` from release-0.3.1 c4bd458b, PR #23 open, the owner merges; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/python-route-guard` from release-0.3.1 137c4591, pull request pending; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## The Python route becomes a list of inputs the suite is held to — 2026-11-10 + +The owner re-rated +[Markdown-only changes run the whole Python unit suite](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) +major and chose the wider fix: the hosted Python job runs only when a +changed file is in `.github/ci-python-inputs.yml`, and a guard in +`tests/conftest.py` fails any counted unit test that opens or lists a +repository path outside that list, so no test can come to depend on a file +the route skips. Branch `ws-maintenance/python-route-guard` from +`release-0.3.1` at `137c4591`. The legacy `tests/test_ci_reporting.py`, whose +filter test the change breaks, is refurbished whole under rule 5. + +Judgments taken, for the owner's review: `docs/**` is listed as an input, +because one legacy scan reads all of `docs/` and counts on the hosted +runner, so docs-only pull requests run the suite until that scan is +retired; the routing tests are integration tests now and leave the hosted +job; the bug's target is set to 0.3.1 without the owner having named it. + +Found on the way and added to the blocking record: inside the owner's +capsule one expected-to-fail unit test downloads 1.5 GB of vendor artifacts +on every run, which is most of the local gate's twelve minutes and what +fills `/tmp`. + +Next action: the owner's review of the pull request. Then, on the owner's +word, the local gate's routing and the retirement of the `docs/` scan. + ## The pile of ideas, a workflow rule for 0.3.1 — 2026-11-10 Owner direction of 2026-11-10: a directory, `engineering-docs/pile-of-ideas/`, From e0f135444907515ca9883fde8cae8812007b6e7e Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Tue, 10 Nov 2026 13:34:55 +0000 Subject: [PATCH 03/75] Record PR #25 and its hosted runs for the Python route guard Co-Authored-By: Claude --- .../wip/2026-09-18-maintenance/CURRENT-STATUS.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index d3ded1e2..a76d92f1 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -12,7 +12,7 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/python-route-guard` from release-0.3.1 137c4591, pull request pending; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/python-route-guard` from release-0.3.1 137c4591, PR #25 open, the owner merges; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` @@ -39,8 +39,13 @@ capsule one expected-to-fail unit test downloads 1.5 GB of vendor artifacts on every run, which is most of the local gate's twelve minutes and what fills `/tmp`. -Next action: the owner's review of the pull request. Then, on the owner's -word, the local gate's routing and the retirement of the `docs/` scan. +PR #25. Hosted runs: the guard alone at `772c3e77`, 2976 passed with no +breach; the flip at `3bd6cc27`, 2947 passed, the new filter matching the 11 +changed files under `devcapsule-src/` and `.github/` and none of the 5 under +`engineering-docs/`. + +Next action: the owner's review of PR #25. Then, on the owner's word, the +local gate's routing and the retirement of the `docs/` scan. ## The pile of ideas, a workflow rule for 0.3.1 — 2026-11-10 From 8274a546d02d161acbd7bba1126ea276af7e1bcf Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 11 Nov 2026 01:10:53 +0000 Subject: [PATCH 04/75] Remove the test-only parameters of PR #18; tests set the host at its source PR #18 gave eight production signatures twenty keyword parameters that no production caller passes, so that no refurbished test would patch a devcapsule attribute. Every new test passed the parameter, so the default, the branch a release ships, was run by none of them: of six faults planted in those defaults, the unit suite caught none, where the retired legacy files had caught five. Runtime: entrypoint.run, console_child, plan_filesystem, prepare_filesystem and foreground_command take what they took before PR #18. run's body is the one 0.3.0 shipped, and with it goes the conditional forwarding of caller_uid and runtime_root that kept two legacy tests' stand-in for prepare_filesystem working. console_child also loses launcher_source, added by PR #16 in the same style. The one addition is a name for a fact: filesystem.RUNTIME_ROOT, /tmp. Commands: VersionCommand and CheckoutDecisionsCommand no longer override invoke to carry test inputs through the framework's group-context argument; the private _DecisionsInvocation is gone, and run_console_decisions takes its arguments alone. Tests: the mirror files set each host input where the code reads it. The caller's uid, ownership changes and the readiness connection go through os.geteuid, os.chown and socket.create_connection; the image's fixed locations through the public constants CONSOLE_PYTHON, LAUNCHER_CONSOLE_SOURCE, RUNTIME_ROOT and RUNTIME_PLAN_PATH; for run alone, the supervisor, the display and the log setup are stand-ins. identity.py gets its mirror file. The integration test of the wrapper's help builds a base without a console interpreter again. images/contract.py no longer calls the runtime's check at start a backstop for the recipe: since PR #18 removed the per-start dependency probe, that check finds only an absent interpreter. Evidence: 26 faults planted one at a time in a scratch copy and run against the touched unit files; 24 caught there, the five lost by PR #18 among them; one caught by the integration file only, the decisions command dropping its arguments; one caught by neither, as before PR #18, a built executable that never finds its stamped record. Left alone: current_build_info keeps its three parameters, because the stamped record lies inside the installed package where a test cannot build it; console_decisions_command keeps the four it had before PR #18. Co-Authored-By: Claude --- devcapsule-src/devcapsule/commands/project.py | 33 +--- devcapsule-src/devcapsule/commands/version.py | 16 +- devcapsule-src/devcapsule/console_tools.py | 17 +- .../devcapsule/container_runtime/console.py | 38 +--- .../container_runtime/entrypoint.py | 82 ++------ .../container_runtime/filesystem.py | 24 +-- .../devcapsule/container_runtime/identity.py | 10 +- devcapsule-src/devcapsule/images/contract.py | 5 +- .../integration/test_console_decisions_cli.py | 22 +-- .../unit/devcapsule/commands/test_version.py | 21 +- .../container_runtime/test_console.py | 142 +++++++------- .../container_runtime/test_entrypoint.py | 185 ++++++++---------- .../container_runtime/test_filesystem.py | 111 ++++++----- .../container_runtime/test_identity.py | 40 ++++ .../unit/devcapsule/test_console_tools.py | 46 +++-- 15 files changed, 338 insertions(+), 454 deletions(-) create mode 100644 devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 48253ed6..3aea6dc5 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -597,13 +597,6 @@ def subcommands(cls) -> Mapping[str, type[Command] | type[Group]]: } -@dataclass(frozen=True) -class _DecisionsInvocation: - environ: Mapping[str, str] | None = None - console_python: Path | None = None - runtime_plan_path: Path | None = None - - class CheckoutDecisionsCommand(Command): """``project checkout decisions ...``: the web console's decision tools, from one CLI. @@ -626,35 +619,11 @@ def configure(cls, parser: argparse.ArgumentParser) -> None: help="from-table, check or hand-off with their arguments, as " "`python -m devcapsule_webconsole.decisions` takes them.") - @classmethod - def invoke( - cls, - prog: str, - argv: Sequence[str], - context: object | None = None, - *, - environ: Mapping[str, str] | None = None, - console_python: Path | None = None, - runtime_plan_path: Path | None = None, - ) -> int: - invocation = ( - _DecisionsInvocation(environ=environ, console_python=console_python, runtime_plan_path=runtime_plan_path) - if environ is not None or console_python is not None or runtime_plan_path is not None - else context - ) - return super().invoke(prog, argv, invocation) - @classmethod def run(cls, arguments: argparse.Namespace, context: object | None) -> int: from devcapsule.console_tools import run_console_decisions - invocation = context if isinstance(context, _DecisionsInvocation) else _DecisionsInvocation() - return run_console_decisions( - arguments.arguments, - environ=invocation.environ, - console_python=invocation.console_python, - runtime_plan_path=invocation.runtime_plan_path, - ) + return run_console_decisions(arguments.arguments) class CheckoutGroup(Group): diff --git a/devcapsule-src/devcapsule/commands/version.py b/devcapsule-src/devcapsule/commands/version.py index 487bf51d..7eb78019 100644 --- a/devcapsule-src/devcapsule/commands/version.py +++ b/devcapsule-src/devcapsule/commands/version.py @@ -3,9 +3,8 @@ from __future__ import annotations import argparse -from typing import Sequence -from devcapsule.build_info import BuildInfo, build_info_json, current_build_info +from devcapsule.build_info import build_info_json, current_build_info from devcapsule.commands.framework import Command __all__ = ["COMMAND", "VersionCommand"] @@ -24,20 +23,9 @@ def configure(cls, parser: argparse.ArgumentParser) -> None: help="Emit stable machine-readable JSON.", ) - @classmethod - def invoke( - cls, - prog: str, - argv: Sequence[str], - context: object | None = None, - *, - build_info: BuildInfo | None = None, - ) -> int: - return super().invoke(prog, argv, build_info if build_info is not None else context) - @classmethod def run(cls, arguments: argparse.Namespace, context: object | None) -> int: - info = context if isinstance(context, BuildInfo) else current_build_info() + info = current_build_info() if arguments.as_json: print(build_info_json(info)) return 0 diff --git a/devcapsule-src/devcapsule/console_tools.py b/devcapsule-src/devcapsule/console_tools.py index 732f9a3f..f9475d43 100644 --- a/devcapsule-src/devcapsule/console_tools.py +++ b/devcapsule-src/devcapsule/console_tools.py @@ -75,22 +75,9 @@ def console_decisions_command( return command -def run_console_decisions( - arguments: Sequence[str], - *, - environ: Mapping[str, str] | None = None, - console_python: Path | None = None, - runtime_plan_path: Path | None = None, - launcher_console_source: Path | None = None, -) -> int: +def run_console_decisions(arguments: Sequence[str]) -> int: """Execute ``devcapsule_webconsole.decisions`` in the capsule's console interpreter.""" - command = console_decisions_command( - arguments, - environ=environ, - console_python=console_python, - runtime_plan_path=runtime_plan_path, - launcher_console_source=launcher_console_source, - ) + command = console_decisions_command(arguments) try: return subprocess.run(command, check=False).returncode except OSError as error: diff --git a/devcapsule-src/devcapsule/container_runtime/console.py b/devcapsule-src/devcapsule/container_runtime/console.py index cf109568..bcaed3f2 100644 --- a/devcapsule-src/devcapsule/container_runtime/console.py +++ b/devcapsule-src/devcapsule/container_runtime/console.py @@ -16,7 +16,6 @@ from __future__ import annotations -from contextlib import AbstractContextManager from pathlib import Path import socket import sys @@ -33,7 +32,6 @@ "CONSOLE_READY_TIMEOUT_SECONDS", "CONSOLE_ROOT", "CommandWrapper", - "ConnectionProbe", "LAUNCHER_CONSOLE_SOURCE", "RUNTIME_CLI", "console_child", @@ -53,17 +51,9 @@ CONSOLE_READY_TIMEOUT_SECONDS = 60.0 CommandWrapper = Callable[[tuple[str, ...]], tuple[str, ...]] -ConnectionProbe = Callable[[tuple[str, int], float], AbstractContextManager[object]] -def console_child( - plan: RuntimePlan, - run_as_identity: CommandWrapper, - *, - console_python: Path | None = None, - launcher_source: Path | None = None, - connect: ConnectionProbe | None = None, -) -> SupervisedChild | None: +def console_child(plan: RuntimePlan, run_as_identity: CommandWrapper) -> SupervisedChild | None: """The console child for ``plan``, or ``None`` when there is none to start. ``None`` when the plan carries no console section, and, announced, when @@ -71,15 +61,12 @@ def console_child( launcher-supplied and runs on any base carrying the display label, so an absent console is a known degradation rather than a failed start. The package the child imports is :func:`console_package_path`'s choice. - ``console_python``, ``launcher_source``, and ``connect`` replace the - installed paths and TCP readiness probe. """ console = plan.console if console is None: return None - python = Path(CONSOLE_PYTHON) if console_python is None else console_python - if not python.is_file(): + if not Path(CONSOLE_PYTHON).is_file(): print( f"devcapsule console: this base has no web console (base recipe 10 adds it at {CONSOLE_ROOT}); " "the capsule runs without one", @@ -88,15 +75,14 @@ def console_child( ) return None command: tuple[str, ...] = ( - str(python), "-m", PACKAGE_NAME, + CONSOLE_PYTHON, "-m", PACKAGE_NAME, "--project", plan.project_path, "--cli", RUNTIME_CLI, "--token-file", console.token_path, "--listen", console.listen_address, "--port", str(console.port), ) - bundled = Path(LAUNCHER_CONSOLE_SOURCE) if launcher_source is None else launcher_source - package_path = console_package_path(console.source_path, bundled) + package_path = console_package_path(console.source_path, Path(LAUNCHER_CONSOLE_SOURCE)) if package_path: # ``env`` replaces any ambient PYTHONPATH: the same interpreter and # dependencies, the selected package ahead of the base's installed copy. @@ -111,7 +97,7 @@ def console_child( return SupervisedChild( name=CONSOLE_CHILD, command=run_as_identity(command), - ready=lambda: _accepts_connections(probe_address, console.port, connect=connect), + ready=lambda: _accepts_connections(probe_address, console.port), ready_timeout_seconds=CONSOLE_READY_TIMEOUT_SECONDS, ) @@ -132,19 +118,9 @@ def console_package_path(source_path: str, launcher_source: Path) -> str: return "" -def _accepts_connections( - address: str, - port: int, - *, - connect: ConnectionProbe | None = None, -) -> bool: - open_connection: ConnectionProbe = ( - (lambda target, timeout: socket.create_connection(target, timeout=timeout)) - if connect is None - else connect - ) +def _accepts_connections(address: str, port: int) -> bool: try: - with open_connection((address, port), 0.2): + with socket.create_connection((address, port), timeout=0.2): return True except OSError: return False diff --git a/devcapsule-src/devcapsule/container_runtime/entrypoint.py b/devcapsule-src/devcapsule/container_runtime/entrypoint.py index 697d430b..ce6717de 100644 --- a/devcapsule-src/devcapsule/container_runtime/entrypoint.py +++ b/devcapsule-src/devcapsule/container_runtime/entrypoint.py @@ -19,27 +19,22 @@ import os from pathlib import Path import sys -from typing import Callable, MutableMapping, Protocol, Sequence +from typing import Sequence from . import contract as rtcontract from .. import logs from .components import eclipse, jetbrains, vscode -from .console import CommandWrapper, console_child +from .console import console_child from .contract import RuntimePlan, RuntimePlanError -from .display import ContainedDisplay, prepare_contained_display +from .display import prepare_contained_display from .filesystem import plan_filesystem, prepare_filesystem from .graphics import environment as graphics_environment from .identity import foreground_command from .supervisor import SupervisedChild, Supervisor, SupervisorError __all__ = [ - "ConsoleBuilder", - "DisplayPreparer", - "LogConfigurer", "SUPERVISOR_LOG_COMPONENT", - "SupervisorFactory", - "SupervisorRunner", "USAGE", "log_rotation", "logged_children", @@ -56,57 +51,20 @@ SUPERVISOR_LOG_COMPONENT = "supervisor" -class SupervisorRunner(Protocol): - def run(self) -> int: ... - - -SupervisorFactory = Callable[..., SupervisorRunner] -LogConfigurer = Callable[..., Path | None] -DisplayPreparer = Callable[[RuntimePlan, str, CommandWrapper], ContainedDisplay] -ConsoleBuilder = Callable[[RuntimePlan, CommandWrapper], SupervisedChild | None] - - -def run( - plan: rtcontract.RuntimePlan, - job: tuple[str, ...] | None = None, - *, - environ: MutableMapping[str, str] | None = None, - runtime_root: Path | None = None, - caller_uid: int | None = None, - configure_logs: LogConfigurer | None = None, - prepare_display: DisplayPreparer | None = None, - build_console_child: ConsoleBuilder | None = None, - supervisor_factory: SupervisorFactory | None = None, -) -> int: - target_env: MutableMapping[str, str] = os.environ if environ is None else environ - setup_logs: LogConfigurer = logs.configure if configure_logs is None else configure_logs - make_display = prepare_contained_display if prepare_display is None else prepare_display - make_console = console_child if build_console_child is None else build_console_child - make_supervisor: SupervisorFactory = Supervisor if supervisor_factory is None else supervisor_factory - +def run(plan: rtcontract.RuntimePlan, job: tuple[str, ...] | None = None) -> int: owner = (plan.identity.uid, plan.identity.gid) log_directory = None if plan.logs is None else plan.logs.directory segment_bytes, rotations = log_rotation(plan) - setup_logs( - SUPERVISOR_LOG_COMPONENT, - log_directory, - environ=target_env, - owner=owner, - segment_bytes=segment_bytes, - rotations=rotations, - ) - filesystem = plan_filesystem(plan) if runtime_root is None else plan_filesystem(plan, runtime_root=runtime_root) - if caller_uid is None: - prepare_filesystem(filesystem, plan.identity) - else: - prepare_filesystem(filesystem, plan.identity, caller_uid=caller_uid) - target_env.update(filesystem.environment) - target_env.update(plan.component_environment()) - target_env.update(graphics_environment(target_env)) + logs.configure(SUPERVISOR_LOG_COMPONENT, log_directory, owner=owner, segment_bytes=segment_bytes, rotations=rotations) + filesystem = plan_filesystem(plan) + prepare_filesystem(filesystem, plan.identity) + os.environ.update(filesystem.environment) + os.environ.update(plan.component_environment()) + os.environ.update(graphics_environment(os.environ)) if plan.component.adapter == "jetbrains": launch = jetbrains.plan(plan) Path(launch.properties_path).write_text(launch.properties, encoding="utf-8") - target_env[launch.properties_environment_variable] = launch.properties_path + os.environ[launch.properties_environment_variable] = launch.properties_path command = launch.command elif plan.component.adapter == "vscode": command = vscode.plan(plan).command @@ -115,23 +73,21 @@ def run( else: raise RuntimePlanError(f"unsupported component adapter: {plan.component.adapter}") - def wrap_for_user(child_command: tuple[str, ...]) -> tuple[str, ...]: - if caller_uid is None: - return foreground_command(child_command, plan.identity) - return foreground_command(child_command, plan.identity, caller_uid=caller_uid) + def as_capsule_user(child_command: tuple[str, ...]) -> tuple[str, ...]: + return foreground_command(child_command, plan.identity) infrastructure: tuple[SupervisedChild, ...] = () if job is None and plan.display is not None and plan.display.is_contained: - contained = make_display(plan, filesystem.environment["XDG_RUNTIME_DIR"], wrap_for_user) - target_env.update(contained.environment) + contained = prepare_contained_display(plan, filesystem.environment["XDG_RUNTIME_DIR"], as_capsule_user) + os.environ.update(contained.environment) infrastructure = contained.children - console = make_console(plan, wrap_for_user) + console = console_child(plan, as_capsule_user) if console is not None: infrastructure = (*infrastructure, console) if job is None: child = SupervisedChild( name=plan.component.id, - command=wrap_for_user(command), + command=foreground_command(command, plan.identity), foreground=True, ) else: @@ -139,13 +95,13 @@ def wrap_for_user(child_command: tuple[str, ...]) -> tuple[str, ...]: # in the project it was launched against, not the image's workdir. child = SupervisedChild( name="job", - command=wrap_for_user(job), + command=foreground_command(job, plan.identity), foreground=True, working_directory=plan.project_path, ) guard = jetbrains.session_lock(plan) if plan.component.adapter == "jetbrains" and job is None else nullcontext() with guard: - return make_supervisor( + return Supervisor( logged_children((*infrastructure, child), log_directory), log_owner=owner, segment_bytes=segment_bytes, rotations=rotations, ).run() diff --git a/devcapsule-src/devcapsule/container_runtime/filesystem.py b/devcapsule-src/devcapsule/container_runtime/filesystem.py index 920cd6d1..4f903d0f 100644 --- a/devcapsule-src/devcapsule/container_runtime/filesystem.py +++ b/devcapsule-src/devcapsule/container_runtime/filesystem.py @@ -2,16 +2,16 @@ from __future__ import annotations -from collections.abc import Callable from dataclasses import dataclass import os from pathlib import Path from .contract import Identity, RuntimePlan -__all__ = ["ChownFunc", "FilesystemPlan", "plan_filesystem", "prepare_filesystem"] +__all__ = ["FilesystemPlan", "RUNTIME_ROOT", "plan_filesystem", "prepare_filesystem"] -ChownFunc = Callable[[Path, int, int], None] +RUNTIME_ROOT = "/tmp" +"""Where a session's ``XDG_RUNTIME_DIR`` is made: the image's temporary directory.""" @dataclass(frozen=True) @@ -20,7 +20,7 @@ class FilesystemPlan: environment: dict[str, str] -def plan_filesystem(runtime: RuntimePlan, *, runtime_root: Path = Path("/tmp")) -> FilesystemPlan: +def plan_filesystem(runtime: RuntimePlan) -> FilesystemPlan: home = Path(runtime.home) slots = tuple(slot.path for slot in runtime.state_slots) environment = { @@ -29,22 +29,14 @@ def plan_filesystem(runtime: RuntimePlan, *, runtime_root: Path = Path("/tmp")) "XDG_DATA_HOME": str(home / ".local" / "share"), "XDG_STATE_HOME": str(home / ".local" / "state"), "XDG_CACHE_HOME": str(home / ".cache"), - "XDG_RUNTIME_DIR": str(runtime_root / f"devcapsule-runtime-{runtime.identity.uid}"), + "XDG_RUNTIME_DIR": str(Path(RUNTIME_ROOT) / f"devcapsule-runtime-{runtime.identity.uid}"), } directories = (str(home), str(home / ".ssh"), str(home / "xtras" / "bin"), *environment.values(), *slots) return FilesystemPlan(tuple(dict.fromkeys(directories)), environment) -def prepare_filesystem( - plan: FilesystemPlan, - identity: Identity, - *, - caller_uid: int | None = None, - chown: ChownFunc | None = None, -) -> None: - effective_uid = os.geteuid() if caller_uid is None else caller_uid - apply_chown: ChownFunc = os.chown if chown is None else chown +def prepare_filesystem(plan: FilesystemPlan, identity: Identity) -> None: for directory in plan.directories: path = Path(directory) missing: list[Path] = [] @@ -53,8 +45,8 @@ def prepare_filesystem( missing.append(cursor) cursor = cursor.parent path.mkdir(parents=True, exist_ok=True) - if effective_uid == 0: + if os.geteuid() == 0: for created in reversed(missing): - apply_chown(created, identity.uid, identity.gid) + os.chown(created, identity.uid, identity.gid) Path(plan.environment["XDG_RUNTIME_DIR"]).chmod(0o700) Path(plan.environment["HOME"], ".ssh").chmod(0o700) diff --git a/devcapsule-src/devcapsule/container_runtime/identity.py b/devcapsule-src/devcapsule/container_runtime/identity.py index b6077bad..2f0bf1d8 100644 --- a/devcapsule-src/devcapsule/container_runtime/identity.py +++ b/devcapsule-src/devcapsule/container_runtime/identity.py @@ -9,12 +9,7 @@ __all__ = ["foreground_command"] -def foreground_command( - command: tuple[str, ...], - identity: Identity, - *, - caller_uid: int | None = None, -) -> tuple[str, ...]: +def foreground_command(command: tuple[str, ...], identity: Identity) -> tuple[str, ...]: """Wrap ``command`` so it runs as the capsule user when the caller is root. Named for its first use; every supervised child, infrastructure included, @@ -23,7 +18,6 @@ def foreground_command( if not command: raise ValueError("foreground command must not be empty") - effective_uid = os.geteuid() if caller_uid is None else caller_uid - if effective_uid == 0: + if os.geteuid() == 0: return ("gosu", f"{identity.uid}:{identity.gid}", *command) return command diff --git a/devcapsule-src/devcapsule/images/contract.py b/devcapsule-src/devcapsule/images/contract.py index e2938bab..ee98e7f8 100644 --- a/devcapsule-src/devcapsule/images/contract.py +++ b/devcapsule-src/devcapsule/images/contract.py @@ -64,8 +64,9 @@ def web_console_availability(labels: Mapping[str, str]) -> WebConsoleAvailabilit Available when the base labels the console's root and its recipe is ``WEBCONSOLE_RECIPE`` or later. A missing label, a recipe below it, or no - recipe labels at all mean no console; the runtime's own check at start - remains the backstop for a base the launcher could not inspect. + recipe labels at all mean no console. The runtime at start checks only + that the console interpreter exists, not its recipe, so these labels are + the one gate against a base too old for the launcher's console package. """ family = labels.get(FAMILY_LABEL) diff --git a/devcapsule-src/tests/integration/test_console_decisions_cli.py b/devcapsule-src/tests/integration/test_console_decisions_cli.py index 930800cd..9fd8121a 100644 --- a/devcapsule-src/tests/integration/test_console_decisions_cli.py +++ b/devcapsule-src/tests/integration/test_console_decisions_cli.py @@ -7,9 +7,9 @@ import pytest -from devcapsule import cli -from devcapsule.commands.project import CheckoutDecisionsCommand +from devcapsule import cli, recursive_dogfood from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template +from devcapsule.container_runtime import console from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan pytestmark = pytest.mark.integration @@ -31,8 +31,9 @@ def runtime_plan_with_source(source: Path) -> RuntimePlan: def test_wrapper_help_succeeds_without_running_console_interpreter( tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch, inside: bool, flag: str, ) -> None: - """``devcapsule project checkout decisions -h/--help`` prints wrapper help without requiring a console interpreter.""" + """``devcapsule project checkout decisions -h/--help`` prints wrapper help on a base that has no console interpreter.""" monkeypatch.setenv("DEVCAPSULE_CONTAINER_NAME", "capsule-fixture" if inside else "") + monkeypatch.setattr(console, "CONSOLE_PYTHON", str(tmp_path / "absent")) monkeypatch.chdir(tmp_path) assert cli.main([*CLI_PREFIX, flag]) == 0 @@ -53,22 +54,21 @@ def test_wrapper_help_succeeds_without_running_console_interpreter( def test_decisions_module_owns_empty_arguments_and_subcommand_help( tmp_path: Path, capfd: pytest.CaptureFixture[str], + monkeypatch: pytest.MonkeyPatch, arguments: list[str], status: int, expected: str, ) -> None: - """``CheckoutDecisionsCommand`` delegates subcommand ``--help`` and empty-argument errors to ``devcapsule_webconsole.decisions``.""" + """Inside a capsule, ``project checkout decisions`` leaves subcommand ``--help`` and empty-argument errors to ``devcapsule_webconsole.decisions``.""" source = Path(__file__).resolve().parents[3] / "devcapsule-webconsole" plan = tmp_path / "plan.json" plan.write_text(runtime_plan_with_source(source).to_json(), encoding="utf-8") + monkeypatch.setenv("DEVCAPSULE_CONTAINER_NAME", "capsule-fixture") + monkeypatch.setattr(console, "CONSOLE_PYTHON", sys.executable) + monkeypatch.setattr(recursive_dogfood, "RUNTIME_PLAN_PATH", plan) + monkeypatch.chdir(tmp_path) - result = CheckoutDecisionsCommand.invoke( - "devcapsule project checkout decisions", - arguments, - environ={"DEVCAPSULE_CONTAINER_NAME": "capsule-fixture"}, - console_python=Path(sys.executable), - runtime_plan_path=plan, - ) + result = cli.main([*CLI_PREFIX, *arguments]) assert result == status output = capfd.readouterr() diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_version.py b/devcapsule-src/tests/unit/devcapsule/commands/test_version.py index 145f6392..a1e1e971 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_version.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_version.py @@ -7,6 +7,7 @@ import pytest from devcapsule.build_info import BuildInfo +from devcapsule.commands import version from devcapsule.commands.version import VersionCommand @@ -20,19 +21,27 @@ ) -def test_version_json_emits_machine_readable_build_info(capsys: pytest.CaptureFixture[str]) -> None: - """``version --json`` prints the ``BuildInfo`` mapping as JSON on stdout and returns 0.""" - status = VersionCommand.invoke("devcapsule version", ["--json"], build_info=SAMPLE_BUILD) +@pytest.fixture +def running_sample_build(monkeypatch: pytest.MonkeyPatch) -> None: + """Make ``SAMPLE_BUILD`` the build the command finds itself running.""" + monkeypatch.setattr(version, "current_build_info", lambda: SAMPLE_BUILD) + + +def test_version_json_emits_machine_readable_build_info( + capsys: pytest.CaptureFixture[str], running_sample_build: None, +) -> None: + """``version --json`` prints the running build's ``BuildInfo`` mapping as JSON on stdout and returns 0.""" + status = VersionCommand.invoke("devcapsule version", ["--json"]) assert status == 0 assert json.loads(capsys.readouterr().out) == SAMPLE_BUILD.to_mapping() def test_version_text_prints_mnemonic_package_version_and_source_identity( - capsys: pytest.CaptureFixture[str], + capsys: pytest.CaptureFixture[str], running_sample_build: None, ) -> None: - """``version`` without ``--json`` prints the mnemonic, package version, repository, revision, and URL.""" - status = VersionCommand.invoke("devcapsule version", [], build_info=SAMPLE_BUILD) + """``version`` without ``--json`` prints the running build's mnemonic, package version, repository, revision, and URL.""" + status = VersionCommand.invoke("devcapsule version", []) assert status == 0 lines = capsys.readouterr().out.splitlines() diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py index 6f8d3ff3..b3163135 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py @@ -2,13 +2,13 @@ from __future__ import annotations -from contextlib import contextmanager from pathlib import Path -from typing import Iterator +import socket import pytest from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template +from devcapsule.container_runtime import console from devcapsule.container_runtime.console import ( CONSOLE_CHILD, CONSOLE_PYTHON, @@ -44,6 +44,23 @@ def launcher_bundle(path: Path) -> Path: return path +@pytest.fixture +def base_python(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + """A base image built under ``tmp_path``: a console interpreter at ``CONSOLE_PYTHON`` and no launcher package.""" + python = tmp_path / "base-python" + python.touch() + monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) + monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) + return python + + +def install_launcher_package(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + """Put the launcher's console package at ``LAUNCHER_CONSOLE_SOURCE``, as materialization does, and return its directory.""" + bundled = launcher_bundle(tmp_path / "launcher-webconsole") + monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(bundled)) + return bundled + + def test_runtime_and_base_recipe_agree_on_console_paths() -> None: """``console.py`` constants match the base image's web-console root, venv interpreter, launcher bundle path, and CLI path.""" assert CONSOLE_ROOT == WEBCONSOLE_ROOT @@ -73,19 +90,14 @@ def test_console_package_path_is_empty_when_only_the_base_copy_exists(tmp_path: assert console_package_path("", absent) == "" -def test_console_child_runs_the_launcher_package_on_the_base_interpreter(tmp_path: Path) -> None: +def test_console_child_runs_the_launcher_package_on_the_base_interpreter( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, base_python: Path, +) -> None: """With an empty ``console.source_path`` and an installed launcher package, ``PYTHONPATH`` selects that package.""" - python = tmp_path / "python" - python.touch() - bundled = launcher_bundle(tmp_path / "launcher-webconsole") + bundled = install_launcher_package(tmp_path, monkeypatch) plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) - child = console_child( - plan, - lambda command: ("as-user", *command), - console_python=python, - launcher_source=bundled, - ) + child = console_child(plan, lambda command: ("as-user", *command)) assert child is not None assert child.name == CONSOLE_CHILD @@ -94,7 +106,7 @@ def test_console_child_runs_the_launcher_package_on_the_base_interpreter(tmp_pat "as-user", "env", f"PYTHONPATH={bundled}", - str(python), + str(base_python), "-m", "devcapsule_webconsole", "--project", @@ -113,24 +125,17 @@ def test_console_child_runs_the_launcher_package_on_the_base_interpreter(tmp_pat def test_console_child_runs_the_base_copy_without_a_launcher_package( - tmp_path: Path, capsys: pytest.CaptureFixture[str], + tmp_path: Path, capsys: pytest.CaptureFixture[str], base_python: Path, ) -> None: """With neither a checkout source nor a launcher package, the command carries no ``PYTHONPATH`` and nothing is announced.""" - python = tmp_path / "python" - python.touch() plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) - child = console_child( - plan, - lambda command: ("as-user", *command), - console_python=python, - launcher_source=tmp_path / "absent-launcher-webconsole", - ) + child = console_child(plan, lambda command: ("as-user", *command)) assert child is not None assert child.command == ( "as-user", - str(python), + str(base_python), "-m", "devcapsule_webconsole", "--project", @@ -148,21 +153,19 @@ def test_console_child_runs_the_base_copy_without_a_launcher_package( def test_console_child_runs_the_mounted_checkout_source_and_says_so( - tmp_path: Path, capsys: pytest.CaptureFixture[str], + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], base_python: Path, ) -> None: """With ``console.source_path`` set beside a launcher package, ``PYTHONPATH`` selects the checkout and stderr announces it.""" - python = tmp_path / "python" - python.touch() - bundled = launcher_bundle(tmp_path / "launcher-webconsole") + install_launcher_package(tmp_path, monkeypatch) plan = runtime_plan( tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token", source_path=CHECKOUT_SOURCE), ) - child = console_child(plan, lambda command: command, console_python=python, launcher_source=bundled) + child = console_child(plan, lambda command: command) assert child is not None - assert child.command[:3] == ("env", f"PYTHONPATH={CHECKOUT_SOURCE}", str(python)) + assert child.command[:3] == ("env", f"PYTHONPATH={CHECKOUT_SOURCE}", str(base_python)) assert f"running the mounted checkout's source at {CHECKOUT_SOURCE}" in capsys.readouterr().err @@ -176,56 +179,49 @@ def test_console_child_runs_the_mounted_checkout_source_and_says_so( ], ) def test_console_readiness_probes_loopback_of_listener_address_family( - tmp_path: Path, listen: str, expected_probe: str, + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, base_python: Path, listen: str, expected_probe: str, ) -> None: - """``child.ready`` connects to the matching IPv4/IPv6 loopback address with a 0.2s timeout and closes the socket.""" - python = tmp_path / "python" - python.touch() - seen: list[tuple[tuple[str, int], float, str]] = [] + """``child.ready`` opens one connection to the loopback of the listener's family, waits 0.2 s at most, and closes it.""" + events: list[object] = [] - @contextmanager - def fake_connect(target: tuple[str, int], timeout: float) -> Iterator[object]: - seen.append((target, timeout, "enter")) - try: - yield object() - finally: - seen.append((target, timeout, "exit")) + class Connection: + def __enter__(self) -> "Connection": + return self - plan = runtime_plan(tmp_path, console=ConsolePlan(listen, 45678, "/run/devcapsule-console-token")) - child = console_child( - plan, - lambda command: command, - console_python=python, - launcher_source=tmp_path / "absent", - connect=fake_connect, - ) + def __exit__(self, *_exception: object) -> None: + events.append("closed") + + def accept(address: tuple[str, int], timeout: float | None = None) -> Connection: + events.append((address, timeout)) + return Connection() + monkeypatch.setattr(socket, "create_connection", accept) + plan = runtime_plan(tmp_path, console=ConsolePlan(listen, 45678, "/run/devcapsule-console-token")) + child = console_child(plan, lambda command: command) assert child is not None and child.ready is not None - assert child.ready() is True - assert seen == [((expected_probe, 45678), 0.2, "enter"), ((expected_probe, 45678), 0.2, "exit")] + ready = child.ready() -def test_console_readiness_returns_false_when_probe_connection_fails(tmp_path: Path) -> None: - """``child.ready`` returns ``False`` when the TCP connection attempt raises ``OSError``.""" - python = tmp_path / "python" - python.touch() + assert ready is True + assert events == [((expected_probe, 45678), 0.2), "closed"] - @contextmanager - def refused(_target: tuple[str, int], _timeout: float) -> Iterator[object]: - raise OSError("connection refused") - yield # pragma: no cover - plan = runtime_plan(tmp_path, console=ConsolePlan("127.0.0.1", 45678, "/run/devcapsule-console-token")) - child = console_child( - plan, - lambda command: command, - console_python=python, - launcher_source=tmp_path / "absent", - connect=refused, - ) +def test_console_readiness_returns_false_when_probe_connection_fails( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, base_python: Path, +) -> None: + """``child.ready`` returns ``False`` when nothing accepts the connection.""" + + def refuse(address: tuple[str, int], timeout: float | None = None) -> socket.socket: + raise ConnectionRefusedError("connection refused") + monkeypatch.setattr(socket, "create_connection", refuse) + plan = runtime_plan(tmp_path, console=ConsolePlan("127.0.0.1", 45678, "/run/devcapsule-console-token")) + child = console_child(plan, lambda command: command) assert child is not None and child.ready is not None - assert child.ready() is False + + ready = child.ready() + + assert ready is False def test_console_child_is_none_when_plan_omits_console( @@ -239,17 +235,13 @@ def test_console_child_is_none_when_plan_omits_console( def test_console_child_warns_and_returns_none_when_interpreter_is_absent( - tmp_path: Path, capsys: pytest.CaptureFixture[str], + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], ) -> None: """When the base image lacks ``CONSOLE_PYTHON``, ``console_child`` prints a degradation notice and returns ``None``.""" + monkeypatch.setattr(console, "CONSOLE_PYTHON", str(tmp_path / "absent")) plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) - child = console_child( - plan, - lambda command: command, - console_python=tmp_path / "absent", - launcher_source=tmp_path / "absent-bundle", - ) + child = console_child(plan, lambda command: command) assert child is None assert "this base has no web console (base recipe 10 adds it" in capsys.readouterr().err diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py index a1db50de..c4aca5cd 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py @@ -1,12 +1,17 @@ -"""Unit tests of ``devcapsule/container_runtime/entrypoint.py``: console child placement across launch modes.""" +"""Unit tests of ``devcapsule/container_runtime/entrypoint.py``: the children ``run`` supervises and the environment it gives them.""" from __future__ import annotations +from dataclasses import dataclass, field import os from pathlib import Path +import pytest + +from devcapsule import logs from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime.console import CONSOLE_CHILD, CommandWrapper, console_child +from devcapsule.container_runtime import console, entrypoint, filesystem +from devcapsule.container_runtime.console import CONSOLE_CHILD, CommandWrapper from devcapsule.container_runtime.contract import ( CONTAINED_DISPLAY_TRANSPORT, ConsolePlan, @@ -15,47 +20,70 @@ RuntimePlan, ) from devcapsule.container_runtime.display import ContainedDisplay, NOVNC_CHILD, XVNC_CHILD -from devcapsule.container_runtime.entrypoint import ConsoleBuilder, SupervisorFactory, run +from devcapsule.container_runtime.entrypoint import run from devcapsule.container_runtime.supervisor import SupervisedChild +SUPERVISOR_STATUS = 42 -class RecordingSupervisor: - """Supervisor stand-in that records supervised children and returns a fixed status.""" - def __init__(self, children: tuple[SupervisedChild, ...], **_kwargs: object) -> None: - self.children = children +@dataclass +class SessionHost: + """What ``run`` reads from and leaves on the host, as one test built and observes it.""" - def run(self) -> int: - return 42 + environ: dict[str, str] = field(default_factory=dict) + supervised: list[tuple[SupervisedChild, ...]] = field(default_factory=list) -def recording_supervisor_factory() -> tuple[SupervisorFactory, list[RecordingSupervisor]]: - """A supervisor factory for ``run`` and the list it appends each supervisor it makes to.""" - recorded: list[RecordingSupervisor] = [] +def fake_display(_plan: RuntimePlan, _runtime_dir: str, as_user: CommandWrapper) -> ContainedDisplay: + """Stand-in for ``prepare_contained_display``: two infrastructure children and their environment, no X server.""" + return ContainedDisplay( + children=( + SupervisedChild(name=XVNC_CHILD, command=as_user(("Xvnc",))), + SupervisedChild(name=NOVNC_CHILD, command=as_user(("websockify",))), + ), + environment={"DISPLAY": ":99", "XAUTHORITY": "/tmp/Xauthority"}, + display_number=99, + xauthority_path="/tmp/Xauthority", + rfb_socket_path="/tmp/rfb.sock", + openbox_configuration_path="/tmp/openbox.xml", + panel_configuration_path="/tmp/tint2rc", + ) - def make_supervisor(children: tuple[SupervisedChild, ...], **kwargs: object) -> RecordingSupervisor: - instance = RecordingSupervisor(children, **kwargs) - recorded.append(instance) - return instance - return make_supervisor, recorded +@pytest.fixture +def host(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> SessionHost: + """A host built for one ``run``. + The process environment is an empty mapping, the caller is not root, and + the image's fixed locations lie under ``tmp_path``: the runtime root, a + console interpreter, no launcher console package. The display, the + supervisor and the log setup are stand-ins, so no program starts and the + root logger stays as it was. + """ + session = SessionHost() -def noop_log_configurer(*_args: object, **_kwargs: object) -> Path | None: - """Stand-in for ``logs.configure`` so unit tests never mutate the process root logger.""" - return None + class RecordingSupervisor: + def __init__(self, children: tuple[SupervisedChild, ...], **_settings: object) -> None: + session.supervised.append(children) + def run(self) -> int: + return SUPERVISOR_STATUS -def console_builder_with_interpreter(tmp_path: Path) -> ConsoleBuilder: - """A console builder whose base interpreter is an empty file under ``tmp_path``, so a console child is made.""" - python = tmp_path / "python" + python = tmp_path / "base-python" python.touch() - absent_bundle = tmp_path / "absent-launcher-webconsole" - return lambda plan, as_user: console_child(plan, as_user, console_python=python, launcher_source=absent_bundle) + monkeypatch.setattr(os, "environ", session.environ) + monkeypatch.setattr(os, "geteuid", lambda: 1000) + monkeypatch.setattr(filesystem, "RUNTIME_ROOT", str(tmp_path / "runtime")) + monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) + monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) + monkeypatch.setattr(entrypoint, "prepare_contained_display", fake_display) + monkeypatch.setattr(entrypoint, "Supervisor", RecordingSupervisor) + monkeypatch.setattr(logs, "configure", lambda *_arguments, **_settings: None) + return session def make_plan(tmp_path: Path, *, with_display: bool) -> RuntimePlan: - """Construct a ``RuntimePlan`` whose project, home, state slots, and properties file all live under ``tmp_path``.""" + """Construct a ``RuntimePlan`` with a console whose project, home, state slots, and properties file all live under ``tmp_path``.""" base = RuntimePlan.for_component( pycharm_runtime_template(), project_path=str(tmp_path / "project"), @@ -82,105 +110,48 @@ def make_plan(tmp_path: Path, *, with_display: bool) -> RuntimePlan: return RuntimePlan.from_mapping(document) -def fake_display(_plan: RuntimePlan, _runtime_dir: str, as_user: CommandWrapper) -> ContainedDisplay: - return ContainedDisplay( - children=( - SupervisedChild(name=XVNC_CHILD, command=as_user(("Xvnc",))), - SupervisedChild(name=NOVNC_CHILD, command=as_user(("websockify",))), - ), - environment={"DISPLAY": ":99", "XAUTHORITY": "/tmp/Xauthority"}, - display_number=99, - xauthority_path="/tmp/Xauthority", - rfb_socket_path="/tmp/rfb.sock", - openbox_configuration_path="/tmp/openbox.xml", - panel_configuration_path="/tmp/tint2rc", - ) - - -def test_run_places_console_after_contained_display_and_before_foreground_surface(tmp_path: Path) -> None: +def test_run_places_console_after_contained_display_and_before_foreground_surface( + tmp_path: Path, host: SessionHost, +) -> None: """With a contained display and console, ``run`` orders display children, ``console``, and foreground IDE.""" - make_supervisor, recorded = recording_supervisor_factory() - - status = run( - make_plan(tmp_path, with_display=True), - environ={}, - runtime_root=tmp_path / "runtime", - caller_uid=1000, - configure_logs=noop_log_configurer, - prepare_display=fake_display, - build_console_child=console_builder_with_interpreter(tmp_path), - supervisor_factory=make_supervisor, - ) + status = run(make_plan(tmp_path, with_display=True)) - assert status == 42 - children = recorded[0].children + assert status == SUPERVISOR_STATUS + (children,) = host.supervised assert [child.name for child in children] == [XVNC_CHILD, NOVNC_CHILD, CONSOLE_CHILD, "pycharm"] assert all(not child.foreground for child in children[:-1]) assert children[-1].foreground is True -def test_run_places_console_before_foreground_surface_without_display(tmp_path: Path) -> None: +def test_run_places_console_before_foreground_surface_without_display(tmp_path: Path, host: SessionHost) -> None: """Without a contained display, ``run`` starts ``console`` in background and the surface in foreground.""" - make_supervisor, recorded = recording_supervisor_factory() - - status = run( - make_plan(tmp_path, with_display=False), - environ={}, - runtime_root=tmp_path / "runtime", - caller_uid=1000, - configure_logs=noop_log_configurer, - build_console_child=console_builder_with_interpreter(tmp_path), - supervisor_factory=make_supervisor, - ) + status = run(make_plan(tmp_path, with_display=False)) - assert status == 42 - children = recorded[0].children + assert status == SUPERVISOR_STATUS + (children,) = host.supervised assert [child.name for child in children] == [CONSOLE_CHILD, "pycharm"] assert children[0].foreground is False and children[1].foreground is True -def test_run_suppresses_contained_display_and_keeps_console_in_job_mode(tmp_path: Path) -> None: +def test_run_suppresses_contained_display_and_keeps_console_in_job_mode(tmp_path: Path, host: SessionHost) -> None: """In headless ``job`` mode, ``run`` omits display children even if declared and supervises ``[console, job]``.""" - make_supervisor, recorded = recording_supervisor_factory() - - status = run( - make_plan(tmp_path, with_display=True), - job=("pytest", "-q"), - environ={}, - runtime_root=tmp_path / "runtime", - caller_uid=1000, - configure_logs=noop_log_configurer, - prepare_display=fake_display, - build_console_child=console_builder_with_interpreter(tmp_path), - supervisor_factory=make_supervisor, - ) + status = run(make_plan(tmp_path, with_display=True), job=("pytest", "-q")) - assert status == 42 - children = recorded[0].children + assert status == SUPERVISOR_STATUS + (children,) = host.supervised assert [child.name for child in children] == [CONSOLE_CHILD, "job"] assert children[0].foreground is False and children[1].foreground is True + assert children[1].command == ("pytest", "-q") + assert children[1].working_directory == str(tmp_path / "project") -def test_run_writes_the_session_environment_into_the_given_mapping_only(tmp_path: Path) -> None: - """``run`` with ``environ`` and ``runtime_root`` confines session paths and variables to ``tmp_path`` and ``environ``.""" - make_supervisor, _recorded = recording_supervisor_factory() - environ: dict[str, str] = {} - process_environment_before = dict(os.environ) - - run( - make_plan(tmp_path, with_display=True), - environ=environ, - runtime_root=tmp_path / "runtime", - caller_uid=1000, - configure_logs=noop_log_configurer, - prepare_display=fake_display, - build_console_child=console_builder_with_interpreter(tmp_path), - supervisor_factory=make_supervisor, - ) +def test_run_gives_the_session_its_environment_before_the_children_start(tmp_path: Path, host: SessionHost) -> None: + """``run`` puts the session's runtime directory, the display's variables and the IDE's properties file in the process environment.""" + run(make_plan(tmp_path, with_display=True)) - assert environ["DISPLAY"] == ":99" - assert environ["XAUTHORITY"] == "/tmp/Xauthority" - assert environ["XDG_RUNTIME_DIR"] == str(tmp_path / "runtime" / "devcapsule-runtime-1000") - assert environ["PYCHARM_PROPERTIES"] == str(tmp_path / "jetbrains.properties") + assert host.environ["HOME"] == str(tmp_path / "home") + assert host.environ["XDG_RUNTIME_DIR"] == str(tmp_path / "runtime" / "devcapsule-runtime-1000") + assert host.environ["DISPLAY"] == ":99" + assert host.environ["XAUTHORITY"] == "/tmp/Xauthority" + assert host.environ["PYCHARM_PROPERTIES"] == str(tmp_path / "jetbrains.properties") assert (tmp_path / "jetbrains.properties").is_file() - assert dict(os.environ) == process_environment_before diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py index 3be60b0f..f303a057 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py @@ -2,6 +2,7 @@ from __future__ import annotations +import os from pathlib import Path import stat @@ -9,7 +10,9 @@ from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.container_runtime.contract import Identity, RuntimePlan -from devcapsule.container_runtime.filesystem import FilesystemPlan, plan_filesystem, prepare_filesystem +from devcapsule.container_runtime.filesystem import RUNTIME_ROOT, FilesystemPlan, plan_filesystem, prepare_filesystem + +DEVELOPER = Identity(1000, 1001, "developer") def sandboxed_plan(tmp_path: Path) -> RuntimePlan: @@ -18,7 +21,7 @@ def sandboxed_plan(tmp_path: Path) -> RuntimePlan: pycharm_runtime_template(), project_path=str(tmp_path / "project"), home=str(tmp_path / "home"), - identity=Identity(1000, 1001, "developer"), + identity=DEVELOPER, ) document = base.to_mapping() document["state_slots"] = [ @@ -28,67 +31,67 @@ def sandboxed_plan(tmp_path: Path) -> RuntimePlan: return RuntimePlan.from_mapping(document) -@pytest.mark.parametrize("custom_root", [False, True]) -def test_plan_filesystem_places_xdg_runtime_dir_under_the_requested_root( - tmp_path: Path, custom_root: bool, +def filesystem_under(root: Path) -> FilesystemPlan: + """A ``FilesystemPlan`` whose home, ``.ssh`` and runtime directory all lie beneath ``root``.""" + home = root / "home" + runtime_directory = root / "runtime" / "devcapsule-runtime-1000" + return FilesystemPlan( + directories=(str(home), str(home / ".ssh"), str(runtime_directory)), + environment={"HOME": str(home), "XDG_RUNTIME_DIR": str(runtime_directory)}, + ) + + +def record_ownership_changes(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Path, int, int]]: + """Replace ``os.chown`` for the test and return the list its calls are appended to.""" + changes: list[tuple[Path, int, int]] = [] + monkeypatch.setattr(os, "chown", lambda path, uid, gid: changes.append((Path(path), uid, gid))) + return changes + + +def test_plan_filesystem_derives_the_session_directories_from_the_home_the_user_and_the_slots( + tmp_path: Path, ) -> None: - """``plan_filesystem`` places ``XDG_RUNTIME_DIR`` under ``/tmp`` by default or under an explicit ``runtime_root``.""" + """``plan_filesystem`` names the runtime directory after the uid under ``RUNTIME_ROOT`` and lists it, the home and every state slot.""" runtime = sandboxed_plan(tmp_path) - expected_root = (tmp_path / "runtime") if custom_root else Path("/tmp") - plan = ( - plan_filesystem(runtime, runtime_root=expected_root) - if custom_root - else plan_filesystem(runtime) - ) + plan = plan_filesystem(runtime) - expected_runtime_dir = str(expected_root / "devcapsule-runtime-1000") - assert plan.environment["XDG_RUNTIME_DIR"] == expected_runtime_dir - assert expected_runtime_dir in plan.directories - assert all(slot.path in plan.directories for slot in runtime.state_slots) + runtime_directory = f"{RUNTIME_ROOT}/devcapsule-runtime-1000" + assert plan.environment["HOME"] == str(tmp_path / "home") + assert plan.environment["XDG_RUNTIME_DIR"] == runtime_directory + assert {str(tmp_path / "home"), runtime_directory} <= set(plan.directories) + assert {slot.path for slot in runtime.state_slots} <= set(plan.directories) -def test_prepare_filesystem_creates_sandboxed_directories_and_private_modes(tmp_path: Path) -> None: - """For a non-root caller, ``prepare_filesystem`` creates home, XDG, runtime, and slot directories with ``0700`` private modes.""" - runtime = sandboxed_plan(tmp_path) - filesystem = plan_filesystem(runtime, runtime_root=tmp_path / "runtime") - chowned: list[tuple[Path, int, int]] = [] - - prepare_filesystem( - filesystem, - runtime.identity, - caller_uid=1000, - chown=lambda path, uid, gid: chowned.append((path, uid, gid)), - ) +def test_prepare_filesystem_creates_every_directory_and_keeps_ssh_and_runtime_private( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + """For a caller that is not root, ``prepare_filesystem`` creates each directory, sets ``0700`` on ``.ssh`` and the runtime directory, and changes no owner.""" + filesystem = filesystem_under(tmp_path) + monkeypatch.setattr(os, "geteuid", lambda: 1000) + changes = record_ownership_changes(monkeypatch) + + prepare_filesystem(filesystem, DEVELOPER) - assert chowned == [] assert all(Path(directory).is_dir() for directory in filesystem.directories) - ssh_mode = stat.S_IMODE((Path(filesystem.environment["HOME"]) / ".ssh").stat().st_mode) - runtime_mode = stat.S_IMODE(Path(filesystem.environment["XDG_RUNTIME_DIR"]).stat().st_mode) - assert ssh_mode == 0o700 - assert runtime_mode == 0o700 - - -def test_prepare_filesystem_assigns_ownership_only_to_newly_created_ancestors_when_root(tmp_path: Path) -> None: - """When ``caller_uid`` is 0, ``prepare_filesystem`` invokes ``chown`` only on directories that did not already exist.""" - existing = tmp_path / "home" - existing.mkdir() - runtime_dir = tmp_path / "runtime" / "devcapsule-runtime-1000" - plan = FilesystemPlan( - directories=(str(existing), str(existing / ".ssh"), str(runtime_dir)), - environment={"HOME": str(existing), "XDG_RUNTIME_DIR": str(runtime_dir)}, - ) - chowned: list[tuple[Path, int, int]] = [] + assert stat.S_IMODE((tmp_path / "home" / ".ssh").stat().st_mode) == 0o700 + assert stat.S_IMODE(Path(filesystem.environment["XDG_RUNTIME_DIR"]).stat().st_mode) == 0o700 + assert changes == [] - prepare_filesystem( - plan, - Identity(1000, 1001, "developer"), - caller_uid=0, - chown=lambda path, uid, gid: chowned.append((path, uid, gid)), - ) - assert chowned == [ - (existing / ".ssh", 1000, 1001), +def test_prepare_filesystem_gives_the_capsule_user_only_the_directories_it_created_when_root( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + """For root, ``prepare_filesystem`` hands each directory it created to the capsule user, outermost first, and leaves an existing one alone.""" + filesystem = filesystem_under(tmp_path) + (tmp_path / "home").mkdir() + monkeypatch.setattr(os, "geteuid", lambda: 0) + changes = record_ownership_changes(monkeypatch) + + prepare_filesystem(filesystem, DEVELOPER) + + assert changes == [ + (tmp_path / "home" / ".ssh", 1000, 1001), (tmp_path / "runtime", 1000, 1001), - (runtime_dir, 1000, 1001), + (tmp_path / "runtime" / "devcapsule-runtime-1000", 1000, 1001), ] diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py new file mode 100644 index 00000000..a6055c7c --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py @@ -0,0 +1,40 @@ +"""Unit tests of ``devcapsule/container_runtime/identity.py``: the privilege drop planned for a supervised child.""" + +from __future__ import annotations + +import os + +import pytest + +from devcapsule.container_runtime.contract import Identity +from devcapsule.container_runtime.identity import foreground_command + +DEVELOPER = Identity(1000, 1001, "developer") + + +def test_foreground_command_drops_to_the_capsule_user_when_the_caller_is_root( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Called as root, ``foreground_command`` prefixes the command with ``gosu`` and the capsule user's ``uid:gid``.""" + monkeypatch.setattr(os, "geteuid", lambda: 0) + + command = foreground_command(("ide", "--wait"), DEVELOPER) + + assert command == ("gosu", "1000:1001", "ide", "--wait") + + +def test_foreground_command_leaves_the_command_alone_when_the_caller_is_not_root( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Called as any user but root, ``foreground_command`` returns the command unchanged.""" + monkeypatch.setattr(os, "geteuid", lambda: 1000) + + command = foreground_command(("ide", "--wait"), DEVELOPER) + + assert command == ("ide", "--wait") + + +def test_foreground_command_refuses_an_empty_command() -> None: + """An empty command raises ``ValueError``, whoever the caller is.""" + with pytest.raises(ValueError, match="must not be empty"): + foreground_command((), DEVELOPER) diff --git a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py index 832206bd..aae2c1e3 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py +++ b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py @@ -8,10 +8,12 @@ import pytest +from devcapsule import recursive_dogfood from devcapsule.compat import CliError from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.configuration.file_formats import ProjectConfigurationError from devcapsule.console_tools import DECISIONS_MODULE, console_decisions_command, run_console_decisions +from devcapsule.container_runtime import console from devcapsule.container_runtime.console import console_child from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan @@ -35,6 +37,14 @@ def launcher_bundle(path: Path) -> Path: return path +def enter_capsule(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, console_python: Path) -> None: + """Make the process a capsule's: its name in the environment, ``console_python`` as the base's console interpreter, no runtime plan and no launcher console package.""" + monkeypatch.setenv(recursive_dogfood.CONTAINER_NAME_ENV, "capsule-fixture") + monkeypatch.setattr(console, "CONSOLE_PYTHON", str(console_python)) + monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) + monkeypatch.setattr(recursive_dogfood, "RUNTIME_PLAN_PATH", tmp_path / "no-plan.json") + + @pytest.mark.parametrize("environ", [{}, {"DEVCAPSULE_CONTAINER_NAME": ""}]) def test_outside_capsule_refuses_and_names_host_module(tmp_path: Path, environ: dict[str, str]) -> None: """Outside a capsule, ``console_decisions_command`` raises ``ProjectConfigurationError`` naming the host module.""" @@ -114,7 +124,9 @@ def test_decisions_command_uses_launcher_package_when_plan_sets_no_checkout_sour ) -def test_mounted_source_uses_same_pythonpath_prefix_as_console_child_ahead_of_launcher_package(tmp_path: Path) -> None: +def test_mounted_source_uses_same_pythonpath_prefix_as_console_child_ahead_of_launcher_package( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: """When ``console.source_path`` is set, ``console_decisions_command`` matches ``console_child`` and overrides ``launcher_console_source``.""" python = tmp_path / "python" python.touch() @@ -122,8 +134,10 @@ def test_mounted_source_uses_same_pythonpath_prefix_as_console_child_ahead_of_la plan = runtime_plan("/workspace/project with spaces/devcapsule-webconsole") plan_path = tmp_path / "plan.json" plan_path.write_text(plan.to_json(), encoding="utf-8") + monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) + monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(bundled)) - child = console_child(plan, lambda command: command, console_python=python, launcher_source=bundled) + child = console_child(plan, lambda command: command) command = console_decisions_command( ["check", "x.json"], environ={"DEVCAPSULE_CONTAINER_NAME": "c"}, @@ -142,9 +156,9 @@ def test_mounted_source_uses_same_pythonpath_prefix_as_console_child_ahead_of_la @pytest.mark.parametrize("status", [0, 3]) def test_run_console_decisions_preserves_arguments_streams_and_exit_status( - tmp_path: Path, capfd: pytest.CaptureFixture[str], status: int, + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capfd: pytest.CaptureFixture[str], status: int, ) -> None: - """``run_console_decisions`` passes argv verbatim to ``console_python``, streams output, and returns its exit code.""" + """Inside a capsule, ``run_console_decisions`` passes argv verbatim to the base's console interpreter, streams its output, and returns its exit code.""" fake = tmp_path / "fake-console-python" fake.write_text( f"#!{sys.executable}\nimport json, sys\nprint(json.dumps(sys.argv[1:]))\n" @@ -153,14 +167,9 @@ def test_run_console_decisions_preserves_arguments_streams_and_exit_status( ) fake.chmod(0o755) arguments = ["from-table", "table with spaces.md", "--id", "pass", "--title", "A title", "--context", "a\nb", "", "--"] + enter_capsule(tmp_path, monkeypatch, fake) - result = run_console_decisions( - arguments, - environ={"DEVCAPSULE_CONTAINER_NAME": "capsule-fixture"}, - console_python=fake, - runtime_plan_path=tmp_path / "no-plan.json", - launcher_console_source=tmp_path / "absent-launcher-webconsole", - ) + result = run_console_decisions(arguments) assert result == status output = capfd.readouterr() @@ -168,18 +177,15 @@ def test_run_console_decisions_preserves_arguments_streams_and_exit_status( assert output.err == "console diagnostic\n" -def test_run_console_decisions_raises_cli_error_naming_an_interpreter_that_cannot_start(tmp_path: Path) -> None: - """When executing ``console_python`` raises ``OSError``, ``run_console_decisions`` wraps it in a ``CliError`` that names the interpreter.""" +def test_run_console_decisions_raises_cli_error_naming_an_interpreter_that_cannot_start( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + """When the base's console interpreter cannot be executed, ``run_console_decisions`` raises a ``CliError`` that names it.""" python = tmp_path / "not-executable" python.touch(mode=0o600) + enter_capsule(tmp_path, monkeypatch, python) with pytest.raises(CliError, match="cannot run the console's decision tools") as caught: - run_console_decisions( - ["check", "x.json"], - environ={"DEVCAPSULE_CONTAINER_NAME": "capsule-fixture"}, - console_python=python, - runtime_plan_path=tmp_path / "no-plan.json", - launcher_console_source=tmp_path / "absent-launcher-webconsole", - ) + run_console_decisions(["check", "x.json"]) assert str(python) in str(caught.value) From 9dc4acfec2b1cb238effe0863ec0de9958add9e4 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 11 Nov 2026 01:19:01 +0000 Subject: [PATCH 05/75] Record the PR #18 follow-up and brief its review The maintenance status records the findings of the assessment of PR #18, what this slice delivers, the four judgments taken for the owner, the planted-fault evidence, the validation counts in the owner's capsule and the proposals not implemented. It also records that PR #25 is merged. The brief for the Codex and GPT-6 Astra pair is committed under the workstream's evidence. It asks for the hosted check's result and names the capsule's 17 standing unit failures, so that neither is read past. Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 103 ++++++++- .../review-brief.md | 211 ++++++++++++++++++ 2 files changed, 310 insertions(+), 4 deletions(-) create mode 100644 engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-11-host-inputs-at-source/review-brief.md diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index a76d92f1..cf1a0c07 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, on `ws-maintenance/python-route-guard` +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d92bdcbb0a01 @@ -12,10 +12,103 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/python-route-guard` from release-0.3.1 137c4591, PR #25 open, the owner merges; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/host-inputs-at-source` from release-0.3.1 2f1109db, PR #26 open, the owner merges; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## PR #18's test-only parameters removed; the tests set the host at its source — 2026-11-11 + +On 2026-11-10 the owner asked for an independent assessment of +[PR #18](https://github.com/mycodespace-ai/devcapsule/pull/18), then asked +for its shortcomings to be fixed, by Pair Review with Codex and GPT-6 Astra +as the review partner. The assessment's findings, each measured on the tree +at the merge `b84b06e9`: + +- PR #18 gave eight production signatures twenty keyword parameters that no + production caller passes, so that no new test would patch a `devcapsule.*` + attribute. Each test passed the parameter, so the branch that ships, the + default, was run by no new test. Of six production faults planted in those + defaults, the four retired legacy files had caught five; the whole unit + suite after PR #18 caught none of the six. +- `entrypoint.run` forwarded `caller_uid` and `runtime_root` only when given, + so that two legacy tests' `lambda *args: None` stand-in for + `prepare_filesystem` kept working. +- `VersionCommand` and `CheckoutDecisionsCommand` carried test inputs through + the command framework's group-context argument and told them apart by type. +- The hosted run was red on five consecutive pushes while the slice was + reviewed, accepted and recorded as validated; both pairs had validated + inside a capsule, where `/ide-config` exists. + +Delivered on `ws-maintenance/host-inputs-at-source`, from `release-0.3.1` at +`2f1109db`, as [PR #26](https://github.com/mycodespace-ai/devcapsule/pull/26): + +- `entrypoint.run`, `console_child`, `plan_filesystem`, `prepare_filesystem`, + `foreground_command`, `VersionCommand`, `CheckoutDecisionsCommand` and + `run_console_decisions` have their signatures of before PR #18 again: + seventeen of the twenty parameters, the type aliases that served them and + the private `_DecisionsInvocation` are gone, and `console_child` loses the + `launcher_source` parameter PR #16 added in the same style. `run`'s body is + the one 0.3.0 shipped. The one addition is a name for a fact, + `filesystem.RUNTIME_ROOT`, `/tmp`. +- The mirror tests set each host input where the code reads it: + the caller's uid, ownership changes and the readiness connection through + `os.geteuid`, `os.chown` and `socket.create_connection`; the image's fixed + locations through the public constants `CONSOLE_PYTHON`, + `LAUNCHER_CONSOLE_SOURCE`, `RUNTIME_ROOT` and `RUNTIME_PLAN_PATH`; the + environment with `monkeypatch`; and, for `run` alone, the supervisor, the + display and the log setup by stand-ins. The code a test runs is the code + that ships. +- `identity.py` has its mirror file. `images/contract.py` no longer calls the + runtime's check at start a backstop for the recipe. The integration test of + the wrapper's help builds a base without a console interpreter again. + +Judgments taken, for the owner's review: + +1. A production signature has a parameter only when production passes it. + This reverses the choice recorded on 2026-11-08, that no refurbished test + patches a `devcapsule.*` attribute. The tests patch public names only, + and never a private one; the conforming tests merged on 2026-11-04 and + 2026-11-05 do the same (`status.read_metadata`, + `runtime_artifact.current_build_info`). +2. `current_build_info` keeps its three parameters: the stamped record lies + inside the installed package, where a test cannot build it. + `console_decisions_command` keeps the four it had before PR #18; its + defaults are now run by the tests of `run_console_decisions`. +3. `commands/project.py` gets no mirror test: a mirror would oblige its + public surface to be declared and `tests/test_project.py` to be retired + in the same change. The one line by which `project checkout decisions` + delegates is run by the integration file only. +4. The target is `release-0.3.1`, as it was for PR #18. + +Evidence: 26 faults planted one at a time in a scratch copy of the tree and +run against the touched unit files. 24 are caught there, among them the five +that PR #18 had lost. One, the command dropping its arguments, is caught by +the integration file only. One survives both, as it did before PR #18: a +built executable that never finds its stamped record; the gate's smoke runs +`version --json` and reads only its exit status. + +Validation at `8274a546`, in the owner's capsule: `nox -s tests` gives 17 +failed and 2913 passed, the 17 of the +[blocking record](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) +and no other; the convention check counts 103 legacy files with 1372 legacy +tests and 49 conforming files, 0 breaches; mypy is clean over 330 files; the +integration file gives 10 passed. The gate as a whole cannot pass in this +capsule while those 17 stand, so the hosted run is the authority for the +suite. + +Proposals not implemented, for the owner: + +- *Unit Tests*, rule 2 or its companion: a parameter is added to production + code for a test only when production passes it, and the default a release + ships stays under a test of the gate. +- *Pair Review Loop*: a review is accepted, and a slice recorded as + validated, only on a green hosted run of the head; the brief asks for it. +- The gate's smoke compares `version --json` of the built executable with + the stamp the build wrote. +- `WORKFLOW-LOCAL.md`, *Pair Review Loop In This Checkout*, rule 3 still + names `/opt/devcapsule-gate` as the review partner's scratch, which the + owner retired on 2026-11-04. + ## The Python route becomes a list of inputs the suite is held to — 2026-11-10 The owner re-rated @@ -44,8 +137,9 @@ breach; the flip at `3bd6cc27`, 2947 passed, the new filter matching the 11 changed files under `devcapsule-src/` and `.github/` and none of the 5 under `engineering-docs/`. -Next action: the owner's review of PR #25. Then, on the owner's word, the -local gate's routing and the retirement of the `docs/` scan. +PR #25 is merged into `release-0.3.1` at `2f1109db`. Next action, on the +owner's word: the local gate's routing and the retirement of the `docs/` +scan. ## The pile of ideas, a workflow rule for 0.3.1 — 2026-11-10 @@ -4959,6 +5053,7 @@ Earlier open-thread history (read against the current scope above): - [PR #16 Pair Review brief (PR16.1)](evidence/2026-11-08-webconsole-delivery/review-brief.md), [D-0017](../../decisions/product/d-0017-launcher-delivers-web-console-package.md), and [0.3.1rc1 web console delivery bug](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md): launcher-delivered web console slice (`ws-maintenance/webconsole-delivery`, stacked on PR #18). +- [PR #26 Pair Review brief (PR26.1)](evidence/2026-11-11-host-inputs-at-source/review-brief.md): brief for `Codex + GPT-6 Astra` on the removal of PR #18's test-only parameters and the tests that set the host at its source. - [PR #18 Pair Review brief (PR18.1)](evidence/2026-11-08-webconsole-legacy-tests/review-brief.md): brief for `Claude Code + Claude Fable 5.1` on whole-file legacy test retirement and 4-file refurbishment (`ws-maintenance/webconsole-legacy-tests`). - [RC9 preparation and component verification](evidence/2026-10-31-rc9/README.md). diff --git a/engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-11-host-inputs-at-source/review-brief.md b/engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-11-host-inputs-at-source/review-brief.md new file mode 100644 index 00000000..831ddaea --- /dev/null +++ b/engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-11-host-inputs-at-source/review-brief.md @@ -0,0 +1,211 @@ +# Review brief for the Codex + GPT-6 Astra pair: PR26.1 on the removal of PR #18's test-only parameters + +The Claude Code + Claude Fable 5.2 pair opened PR #26 ("Remove the test-only +parameters of PR #18; tests set the host at its source") on the branch +`ws-maintenance/host-inputs-at-source`, targeting `release-0.3.1`. It is a +follow-up to the merged PR #18 and its review, PR #19. No earlier review of +PR #26 exists. Your job is one improvement pull request, PR26.1, against +`ws-maintenance/host-inputs-at-source`. + +## Your checkout + +You are in the git worktree at `/home/devcapsule/worktrees/maintenance-review`, +on the branch `ws-maintenance/host-inputs-at-source-review`, branched from +`ws-maintenance/host-inputs-at-source`. Work only there. Do not touch the +implementor's checkout at `/workspace/301e4208ef81-ChatGPT_Codex`, and run no +test there. + +Read first, in this order: + +1. `AGENTS.md`, `WORKFLOW.md` topic 9.11, `WORKFLOW-LOCAL.md` (*Unit Tests* + rules 1 to 7, *Pair Review Loop In This Checkout*, *Commit Authorship*), + `WORKFLOW-LOCAL-humane.md` (*Unit Tests*). +2. `engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md`, the + section "PR #18's test-only parameters removed; the tests set the host at + its source — 2026-11-11". It holds the findings this slice answers, the + four judgments taken for the owner, and the proposals not implemented. + The section "Whole-file legacy test retirement and 4-file refurbishment + for 0.3.1" below it records what PR #18 did and why. +3. `engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md`. + It explains the 17 unit tests that fail in this capsule on every branch. +4. `devcapsule-src/devcapsule/container_runtime/entrypoint.py`, whose module + docstring is the contract of the largest change. + +## GitHub CLI + +In every shell that uses `gh`, first execute: + + . /opt/xtras/miniconda3/etc/profile.d/conda.sh && conda activate gh + +Then `gh` is logged in to github.com as the owner's account. Pass +`-R mycodespace-ai/devcapsule` to every `gh` command. Do not edit `.bashrc` +or any shell profile. + +## Validation environment + +Your worktree's `devcapsule-src/.venv` exists. Run everything from +`devcapsule-src`. These are the commands, verbatim: + + DEVCAPSULE_DIFF_BASE=origin/release-0.3.1 .venv/bin/python -m nox -s typecheck + .venv/bin/python -m pytest --no-cov -q tests/unit/devcapsule/container_runtime tests/unit/devcapsule/commands/test_version.py tests/unit/devcapsule/test_console_tools.py tests/unit/devcapsule/test_build_info.py + .venv/bin/python -m pytest --no-cov -q -m integration tests/integration/test_console_decisions_cli.py + .venv/bin/python -m pytest --no-cov -q tests/test_runtime_entrypoint.py tests/test_contained_display.py tests/test_eclipse_component.py tests/test_vscode_component.py tests/test_runtime_diagnose.py + DEVCAPSULE_DIFF_BASE=origin/release-0.3.1 .venv/bin/python -m nox -s tests + +Facts of this capsule that you must know before you read a result: + +- `nox -s tests` ends with 17 failed here, on this branch and on + `release-0.3.1` alike. The bug record of item 3 names the six files and the + counts. A failure outside that list is a finding. Because of them + `nox -s build` cannot pass in this capsule; do not run it. The hosted run + is the authority for the whole suite. +- One unit test downloads 1.5 GB into its scratch under `/tmp`, a 2 GB + tmpfs. Run the unit session once, as the last command. Before it, run + `df -h /tmp`, and delete only the `/tmp/pytest-of-*/pytest-` directories + that your own earlier runs left. Use the default scratch: no `--basetemp`, + no `/opt/devcapsule-gate`, nothing under `/home/devcapsule`. +- Run commands in the foreground and one at a time. Two pytest sessions at + once collide in `/tmp`. +- You are inside a capsule: `DEVCAPSULE_CONTAINER_NAME` is set, + `/opt/devcapsule-webconsole` and `/ide-config` exist. The hosted runner has + none of them. A test that passes here for that reason is the defect class + this slice exists to remove. + +Read the hosted check of the head before you start and again before your +final report: + + gh pr checks 26 -R mycodespace-ai/devcapsule + +State its result in your pull request body. If it is red or pending when you +finish, say so in the first line of the body. + +Do not build images, start capsules or run the end-to-end sessions. + +## The task + +Review the diff of PR #26 against its base: + + gh pr diff 26 -R mycodespace-ai/devcapsule + +The code of before PR #18 is at `b84b06e9^1`; `git show b84b06e9^1:` +shows any file as 0.3.0 shipped it. + +What the change does. PR #18 added twenty keyword parameters to eight +production signatures so that no refurbished test would patch a +`devcapsule.*` attribute. No production caller passes them. PR #26 removes +seventeen and restores the bodies of before PR #18. The mirror tests now set +each host input where the code reads it, with `monkeypatch`, on public names +only: `os.geteuid`, `os.chown`, `socket.create_connection`, `os.environ`; the +constants `CONSOLE_PYTHON`, `LAUNCHER_CONSOLE_SOURCE`, `RUNTIME_ROOT` and +`RUNTIME_PLAN_PATH`; and, in `test_entrypoint.py` only, `entrypoint.Supervisor`, +`entrypoint.prepare_contained_display` and `logs.configure`. + +Improve it on your branch, focused on these four things, in this order. + +1. **Correctness of the new and modified lines.** + - Is each restored function the function of before PR #18 in behaviour? + Compare `entrypoint.run`, `console_child`, `prepare_filesystem` and + `foreground_command` with `b84b06e9^1`, and account for every difference. + - Does any caller still pass a removed parameter or import a removed name + (`ConnectionProbe`, `ChownFunc`, `SupervisorFactory`, `SupervisorRunner`, + `LogConfigurer`, `DisplayPreparer`, `ConsoleBuilder`)? Look in + `devcapsule/`, `scripts/`, `noxfile.py`, `devcapsule-webconsole/` and + every test, legacy ones included. + - `filesystem.RUNTIME_ROOT` is new. Is it read at call time? Is `/tmp` + what a real session still gets? `container_runtime/diagnose.py` writes + the same path as a literal; is that a defect of this change or a + neighbour to leave? + - `run` calls `logs.configure` without `environ=` again. Does the log level + still come from the process environment? + - `console_child` lost `launcher_source`, which PR #16 added. Is the + precedence of `D-0017` intact: the plan's checkout source, then the + launcher's package, then the base's copy? Does `tests/conftest.py` still + keep every test away from the capsule's real `/opt/devcapsule/webconsole`? + - Is the new sentence in `images/contract.py` true? Read where + `launch/pycharm/_launcher.py` plans a console without having read labels. +2. **Clarity of the new and modified lines.** The standard is "obviously no + deficiencies". Read the fixtures `host` in `test_entrypoint.py`, + `base_python` in `test_console.py` and `enter_capsule` in + `test_console_tools.py` as a stranger would. +3. **Test coverage of the new and modified lines.** Plant faults of your own + in the touched production code and report which test catches each; do not + only repeat the 26 of the status section. Add a test where a line of the + touched code is run by no test of the gate. Every test must fail if the + line it covers is broken. Do not pad. Two gaps are known and recorded: + the one line by which `CheckoutDecisionsCommand.run` delegates, and the + default record locations of `current_build_info`. +4. **Every new or changed test against *Unit Tests* in `WORKFLOW-LOCAL.md`.** + It lives in the mirror and names its unit; it establishes its own + precondition, calls one public operation and asserts a promised + postcondition; its docstring states the contract. For each, name what + would make it fail for a reason that is not a bug. Group tests that share + one isolation pattern, and name every distinct cause. Ask in particular: + - Does any test patch a private name, or a name the unit does not read? + - Does replacing `os.environ`, `os.geteuid` or `os.chown` for one test + reach pytest's own work, another fixture, or the next test? + - Would any of these tests give another result as root, on macOS, where + IPv6 is off, where `/tmp` is not writable, outside a capsule, or on the + hosted runner? + - Which refactoring of the unit, with its behaviour unchanged, would turn + a test red? + A finding here is a finding; "confined to tests" does not dismiss it. + +Stay inside the scope: the signatures PR #18 changed, their mirror tests, the +integration file `tests/integration/test_console_decisions_cli.py` and the one +docstring in `images/contract.py`. Do not retire another legacy file. Do not +change `current_build_info` or the signature of `console_decisions_command`. +Do not change `WORKFLOW.md`, `WORKFLOW-LOCAL.md` or their companions. + +The first judgment of the status section, that a production signature has a +parameter only when production passes it, is the owner's to decide. If you +believe the parameters were the better design, argue it under "Proposals not +implemented" and do not put them back. + +## What you must not do + +- Do not edit `CURRENT-STATUS.md` files, `intake-dispositions.md` or the + `evidence/` directory. Do not run `devcapsule workflow publish` or + `devcapsule0 workflow publish`. +- Do not commit the `website` submodule pointer, `.idea/` files, + `.devcapsule/` files, `*.egg-info`, `.nox/`, `dist/` or `__pycache__`. + Stage explicit paths; never `git add -A` or `git commit -a`. +- Do not merge anything. Do not push to `main`, `release-0.3.1`, + `ws-maintenance/host-inputs-at-source` or any branch other than + `ws-maintenance/host-inputs-at-source-review`. +- Do not rebase or force-push. Do not build images or run capsules. + +## Deliverable + +1. Commits on `ws-maintenance/host-inputs-at-source-review`. Keep the human's + author identity, `Costin Cozianu `; check it with + `git var GIT_AUTHOR_IDENT`. Each message names the component and the + evidence and ends, after a blank line, with your trailer as *Commit + Authorship* prescribes, for example + `Co-authored-by: GPT-6 Astra Codex `; read your + session's model identity and do not copy the example blindly. +2. Push the branch with + `git push -u origin ws-maintenance/host-inputs-at-source-review` and open + one pull request with + `gh pr create -R mycodespace-ai/devcapsule --base ws-maintenance/host-inputs-at-source --head ws-maintenance/host-inputs-at-source-review`. + Title: `Correctness, clarity and coverage review of #26 (PR26.1)`. + The body lists: + - the hosted check's result for the head you reviewed; + - each finding as: what was wrong or unclear, where, what you changed, how + a test proves it; + - per *Unit Tests* rule 7, for the new and changed tests, what would make + each fail for a reason that is not a bug; + - "Considered and left alone, because"; + - "Proposals not implemented"; + - the result of each validation command, with counts, and what you did + not run. + If you find nothing to change, say so in your final report and open no + empty pull request. +3. Print the pull request's URL as the last line of your output, or `NO PR` + if you opened none. + +Write the body and your report at about 80% ASD-STE100: one fact per +sentence, about twenty words, active voice. Back every claim about behaviour +with a test or a command you ran. + +If you cannot proceed, because of a blocker like network or credentials, +stop and say exactly what blocked you. Do not work around a blocker. From 1b5d3fc766ec3393d67d72dd007f89f219b8480b Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 11 Nov 2026 01:34:17 +0000 Subject: [PATCH 06/75] Runtime review: isolate host fixtures and test default build records Correct the console label-gate claim and keep process-wide patches inside test actions. Assert environment timing, graphics defaults, the runtime root, and package-resource build identity. Keep the decisions mirror focused on one unit and isolate its fake interpreter from Python startup settings. Evidence: 81 focused tests, 10 integration tests, and 98 legacy tests pass. Typecheck passes over 336 files. Thirteen planted production faults and one fixture fault are detected. Co-authored-by: GPT-6 Astra Codex --- devcapsule-src/devcapsule/images/contract.py | 7 +-- .../container_runtime/test_console.py | 16 ++++-- .../container_runtime/test_entrypoint.py | 53 +++++++++++++------ .../container_runtime/test_filesystem.py | 22 ++++---- .../container_runtime/test_identity.py | 12 ++--- .../tests/unit/devcapsule/test_build_info.py | 20 +++++++ .../unit/devcapsule/test_console_tools.py | 24 ++++----- 7 files changed, 101 insertions(+), 53 deletions(-) diff --git a/devcapsule-src/devcapsule/images/contract.py b/devcapsule-src/devcapsule/images/contract.py index ee98e7f8..d5d053ab 100644 --- a/devcapsule-src/devcapsule/images/contract.py +++ b/devcapsule-src/devcapsule/images/contract.py @@ -64,9 +64,10 @@ def web_console_availability(labels: Mapping[str, str]) -> WebConsoleAvailabilit Available when the base labels the console's root and its recipe is ``WEBCONSOLE_RECIPE`` or later. A missing label, a recipe below it, or no - recipe labels at all mean no console. The runtime at start checks only - that the console interpreter exists, not its recipe, so these labels are - the one gate against a base too old for the launcher's console package. + recipe labels at all mean no console for callers that use this result. + The low-level launcher defaults to available when no result is supplied. + The runtime checks only that the console interpreter exists; it does not + check the recipe or the package's dependencies. """ family = labels.get(FAMILY_LABEL) diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py index b3163135..5383830f 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py @@ -46,7 +46,11 @@ def launcher_bundle(path: Path) -> Path: @pytest.fixture def base_python(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: - """A base image built under ``tmp_path``: a console interpreter at ``CONSOLE_PYTHON`` and no launcher package.""" + """Set the image paths to an empty interpreter file and an absent package. + + Child construction only checks that the interpreter file exists; these + tests never execute it. + """ python = tmp_path / "base-python" python.touch() monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) @@ -195,12 +199,13 @@ def accept(address: tuple[str, int], timeout: float | None = None) -> Connection events.append((address, timeout)) return Connection() - monkeypatch.setattr(socket, "create_connection", accept) plan = runtime_plan(tmp_path, console=ConsolePlan(listen, 45678, "/run/devcapsule-console-token")) child = console_child(plan, lambda command: command) assert child is not None and child.ready is not None - ready = child.ready() + with monkeypatch.context() as network: + network.setattr(socket, "create_connection", accept) + ready = child.ready() assert ready is True assert events == [((expected_probe, 45678), 0.2), "closed"] @@ -214,12 +219,13 @@ def test_console_readiness_returns_false_when_probe_connection_fails( def refuse(address: tuple[str, int], timeout: float | None = None) -> socket.socket: raise ConnectionRefusedError("connection refused") - monkeypatch.setattr(socket, "create_connection", refuse) plan = runtime_plan(tmp_path, console=ConsolePlan("127.0.0.1", 45678, "/run/devcapsule-console-token")) child = console_child(plan, lambda command: command) assert child is not None and child.ready is not None - ready = child.ready() + with monkeypatch.context() as network: + network.setattr(socket, "create_connection", refuse) + ready = child.ready() assert ready is False diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py index c4aca5cd..4c35b739 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py @@ -2,6 +2,8 @@ from __future__ import annotations +from collections.abc import Iterator +from contextlib import contextmanager from dataclasses import dataclass, field import os from pathlib import Path @@ -32,6 +34,15 @@ class SessionHost: environ: dict[str, str] = field(default_factory=dict) supervised: list[tuple[SupervisedChild, ...]] = field(default_factory=list) + environment_at_start: dict[str, str] = field(default_factory=dict) + + @contextmanager + def process(self) -> Iterator[None]: + """Replace process inputs only during the action, before pytest resumes.""" + with pytest.MonkeyPatch.context() as process: + process.setattr(os, "environ", self.environ) + process.setattr(os, "geteuid", lambda: 1000) + yield def fake_display(_plan: RuntimePlan, _runtime_dir: str, as_user: CommandWrapper) -> ContainedDisplay: @@ -54,9 +65,9 @@ def fake_display(_plan: RuntimePlan, _runtime_dir: str, as_user: CommandWrapper) def host(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> SessionHost: """A host built for one ``run``. - The process environment is an empty mapping, the caller is not root, and - the image's fixed locations lie under ``tmp_path``: the runtime root, a - console interpreter, no launcher console package. The display, the + Within ``host.process()``, the environment is an empty mapping and the + caller is not root. The image paths lie under ``tmp_path``: a runtime + root, an empty interpreter file, and an absent launcher package. The display, the supervisor and the log setup are stand-ins, so no program starts and the root logger stays as it was. """ @@ -65,14 +76,13 @@ def host(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> SessionHost: class RecordingSupervisor: def __init__(self, children: tuple[SupervisedChild, ...], **_settings: object) -> None: session.supervised.append(children) + session.environment_at_start = dict(os.environ) def run(self) -> int: return SUPERVISOR_STATUS python = tmp_path / "base-python" python.touch() - monkeypatch.setattr(os, "environ", session.environ) - monkeypatch.setattr(os, "geteuid", lambda: 1000) monkeypatch.setattr(filesystem, "RUNTIME_ROOT", str(tmp_path / "runtime")) monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) @@ -114,7 +124,9 @@ def test_run_places_console_after_contained_display_and_before_foreground_surfac tmp_path: Path, host: SessionHost, ) -> None: """With a contained display and console, ``run`` orders display children, ``console``, and foreground IDE.""" - status = run(make_plan(tmp_path, with_display=True)) + plan = make_plan(tmp_path, with_display=True) + with host.process(): + status = run(plan) assert status == SUPERVISOR_STATUS (children,) = host.supervised @@ -125,7 +137,9 @@ def test_run_places_console_after_contained_display_and_before_foreground_surfac def test_run_places_console_before_foreground_surface_without_display(tmp_path: Path, host: SessionHost) -> None: """Without a contained display, ``run`` starts ``console`` in background and the surface in foreground.""" - status = run(make_plan(tmp_path, with_display=False)) + plan = make_plan(tmp_path, with_display=False) + with host.process(): + status = run(plan) assert status == SUPERVISOR_STATUS (children,) = host.supervised @@ -135,7 +149,9 @@ def test_run_places_console_before_foreground_surface_without_display(tmp_path: def test_run_suppresses_contained_display_and_keeps_console_in_job_mode(tmp_path: Path, host: SessionHost) -> None: """In headless ``job`` mode, ``run`` omits display children even if declared and supervises ``[console, job]``.""" - status = run(make_plan(tmp_path, with_display=True), job=("pytest", "-q")) + plan = make_plan(tmp_path, with_display=True) + with host.process(): + status = run(plan, job=("pytest", "-q")) assert status == SUPERVISOR_STATUS (children,) = host.supervised @@ -146,12 +162,17 @@ def test_run_suppresses_contained_display_and_keeps_console_in_job_mode(tmp_path def test_run_gives_the_session_its_environment_before_the_children_start(tmp_path: Path, host: SessionHost) -> None: - """``run`` puts the session's runtime directory, the display's variables and the IDE's properties file in the process environment.""" - run(make_plan(tmp_path, with_display=True)) - - assert host.environ["HOME"] == str(tmp_path / "home") - assert host.environ["XDG_RUNTIME_DIR"] == str(tmp_path / "runtime" / "devcapsule-runtime-1000") - assert host.environ["DISPLAY"] == ":99" - assert host.environ["XAUTHORITY"] == "/tmp/Xauthority" - assert host.environ["PYCHARM_PROPERTIES"] == str(tmp_path / "jetbrains.properties") + """Before supervision, ``run`` sets session paths and display variables, supplies graphics defaults, and preserves graphics overrides.""" + plan = make_plan(tmp_path, with_display=True) + host.environ["LIBGL_ALWAYS_SOFTWARE"] = "0" + with host.process(): + run(plan) + + assert host.environment_at_start["HOME"] == str(tmp_path / "home") + assert host.environment_at_start["XDG_RUNTIME_DIR"] == str(tmp_path / "runtime" / "devcapsule-runtime-1000") + assert host.environment_at_start["DISPLAY"] == ":99" + assert host.environment_at_start["XAUTHORITY"] == "/tmp/Xauthority" + assert host.environment_at_start["PYCHARM_PROPERTIES"] == str(tmp_path / "jetbrains.properties") + assert host.environment_at_start["NO_AT_BRIDGE"] == "1" + assert host.environment_at_start["LIBGL_ALWAYS_SOFTWARE"] == "0" assert (tmp_path / "jetbrains.properties").is_file() diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py index f303a057..04a44d98 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py @@ -10,7 +10,7 @@ from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.container_runtime.contract import Identity, RuntimePlan -from devcapsule.container_runtime.filesystem import RUNTIME_ROOT, FilesystemPlan, plan_filesystem, prepare_filesystem +from devcapsule.container_runtime.filesystem import FilesystemPlan, plan_filesystem, prepare_filesystem DEVELOPER = Identity(1000, 1001, "developer") @@ -51,12 +51,12 @@ def record_ownership_changes(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Path def test_plan_filesystem_derives_the_session_directories_from_the_home_the_user_and_the_slots( tmp_path: Path, ) -> None: - """``plan_filesystem`` names the runtime directory after the uid under ``RUNTIME_ROOT`` and lists it, the home and every state slot.""" + """``plan_filesystem`` names the runtime directory after the uid under /tmp and lists it, the home and every state slot.""" runtime = sandboxed_plan(tmp_path) plan = plan_filesystem(runtime) - runtime_directory = f"{RUNTIME_ROOT}/devcapsule-runtime-1000" + runtime_directory = "/tmp/devcapsule-runtime-1000" assert plan.environment["HOME"] == str(tmp_path / "home") assert plan.environment["XDG_RUNTIME_DIR"] == runtime_directory assert {str(tmp_path / "home"), runtime_directory} <= set(plan.directories) @@ -68,10 +68,10 @@ def test_prepare_filesystem_creates_every_directory_and_keeps_ssh_and_runtime_pr ) -> None: """For a caller that is not root, ``prepare_filesystem`` creates each directory, sets ``0700`` on ``.ssh`` and the runtime directory, and changes no owner.""" filesystem = filesystem_under(tmp_path) - monkeypatch.setattr(os, "geteuid", lambda: 1000) - changes = record_ownership_changes(monkeypatch) - - prepare_filesystem(filesystem, DEVELOPER) + with monkeypatch.context() as process: + process.setattr(os, "geteuid", lambda: 1000) + changes = record_ownership_changes(process) + prepare_filesystem(filesystem, DEVELOPER) assert all(Path(directory).is_dir() for directory in filesystem.directories) assert stat.S_IMODE((tmp_path / "home" / ".ssh").stat().st_mode) == 0o700 @@ -85,10 +85,10 @@ def test_prepare_filesystem_gives_the_capsule_user_only_the_directories_it_creat """For root, ``prepare_filesystem`` hands each directory it created to the capsule user, outermost first, and leaves an existing one alone.""" filesystem = filesystem_under(tmp_path) (tmp_path / "home").mkdir() - monkeypatch.setattr(os, "geteuid", lambda: 0) - changes = record_ownership_changes(monkeypatch) - - prepare_filesystem(filesystem, DEVELOPER) + with monkeypatch.context() as process: + process.setattr(os, "geteuid", lambda: 0) + changes = record_ownership_changes(process) + prepare_filesystem(filesystem, DEVELOPER) assert changes == [ (tmp_path / "home" / ".ssh", 1000, 1001), diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py index a6055c7c..dce1fd69 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py @@ -16,9 +16,9 @@ def test_foreground_command_drops_to_the_capsule_user_when_the_caller_is_root( monkeypatch: pytest.MonkeyPatch, ) -> None: """Called as root, ``foreground_command`` prefixes the command with ``gosu`` and the capsule user's ``uid:gid``.""" - monkeypatch.setattr(os, "geteuid", lambda: 0) - - command = foreground_command(("ide", "--wait"), DEVELOPER) + with monkeypatch.context() as process: + process.setattr(os, "geteuid", lambda: 0) + command = foreground_command(("ide", "--wait"), DEVELOPER) assert command == ("gosu", "1000:1001", "ide", "--wait") @@ -27,9 +27,9 @@ def test_foreground_command_leaves_the_command_alone_when_the_caller_is_not_root monkeypatch: pytest.MonkeyPatch, ) -> None: """Called as any user but root, ``foreground_command`` returns the command unchanged.""" - monkeypatch.setattr(os, "geteuid", lambda: 1000) - - command = foreground_command(("ide", "--wait"), DEVELOPER) + with monkeypatch.context() as process: + process.setattr(os, "geteuid", lambda: 1000) + command = foreground_command(("ide", "--wait"), DEVELOPER) assert command == ("ide", "--wait") diff --git a/devcapsule-src/tests/unit/devcapsule/test_build_info.py b/devcapsule-src/tests/unit/devcapsule/test_build_info.py index b6ce9f29..aef69c96 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_build_info.py +++ b/devcapsule-src/tests/unit/devcapsule/test_build_info.py @@ -8,6 +8,7 @@ import pytest +from devcapsule import build_info from devcapsule.build_info import ( BuildInfo, BuildInfoError, @@ -18,6 +19,25 @@ ) +def test_current_build_info_reads_the_default_package_record( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +) -> None: + """Without record paths, ``current_build_info`` reads the stamp from the devcapsule package resources.""" + package = tmp_path / "devcapsule" + package.mkdir() + stamped = BuildInfo(2, "1.2.3", "unknown", "unknown", "unknown", "v1.2.3") + (package / "_build_info.json").write_text(build_info_json(stamped), encoding="utf-8") + + def package_resources(anchor: str) -> Path: + return tmp_path / anchor + + monkeypatch.setattr(build_info, "files", package_resources) + + info = current_build_info(pyproject_path=tmp_path / "absent.toml", installed_version="9.9.9") + + assert info == stamped + + def test_public_build_identity_requires_matching_github_commit_url() -> None: """``has_public_revision`` is True only when ``source_url`` matches ``/commit/``.""" revision = "a" * 40 diff --git a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py index aae2c1e3..2e8b979a 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py +++ b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py @@ -14,7 +14,6 @@ from devcapsule.configuration.file_formats import ProjectConfigurationError from devcapsule.console_tools import DECISIONS_MODULE, console_decisions_command, run_console_decisions from devcapsule.container_runtime import console -from devcapsule.container_runtime.console import console_child from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan @@ -38,7 +37,11 @@ def launcher_bundle(path: Path) -> Path: def enter_capsule(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, console_python: Path) -> None: - """Make the process a capsule's: its name in the environment, ``console_python`` as the base's console interpreter, no runtime plan and no launcher console package.""" + """Set capsule detection and the paths that the wrapper reads by default. + + The caller supplies the interpreter. The plan and launcher package are + absent, so execution uses that interpreter without a PYTHONPATH prefix. + """ monkeypatch.setenv(recursive_dogfood.CONTAINER_NAME_ENV, "capsule-fixture") monkeypatch.setattr(console, "CONSOLE_PYTHON", str(console_python)) monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) @@ -124,20 +127,16 @@ def test_decisions_command_uses_launcher_package_when_plan_sets_no_checkout_sour ) -def test_mounted_source_uses_same_pythonpath_prefix_as_console_child_ahead_of_launcher_package( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, +def test_mounted_source_takes_precedence_over_launcher_package( + tmp_path: Path, ) -> None: - """When ``console.source_path`` is set, ``console_decisions_command`` matches ``console_child`` and overrides ``launcher_console_source``.""" + """``console_decisions_command`` selects the plan's checkout source ahead of the launcher package, preserving spaces.""" python = tmp_path / "python" python.touch() bundled = launcher_bundle(tmp_path / "launcher-webconsole") plan = runtime_plan("/workspace/project with spaces/devcapsule-webconsole") plan_path = tmp_path / "plan.json" plan_path.write_text(plan.to_json(), encoding="utf-8") - monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) - monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(bundled)) - - child = console_child(plan, lambda command: command) command = console_decisions_command( ["check", "x.json"], environ={"DEVCAPSULE_CONTAINER_NAME": "c"}, @@ -146,8 +145,7 @@ def test_mounted_source_uses_same_pythonpath_prefix_as_console_child_ahead_of_la launcher_console_source=bundled, ) - assert child is not None - assert command[:2] == child.command[:2] == ( + assert command[:2] == ( "env", "PYTHONPATH=/workspace/project with spaces/devcapsule-webconsole", ) @@ -161,13 +159,15 @@ def test_run_console_decisions_preserves_arguments_streams_and_exit_status( """Inside a capsule, ``run_console_decisions`` passes argv verbatim to the base's console interpreter, streams its output, and returns its exit code.""" fake = tmp_path / "fake-console-python" fake.write_text( - f"#!{sys.executable}\nimport json, sys\nprint(json.dumps(sys.argv[1:]))\n" + f"#!{sys.executable} -I\nimport json, sys\nprint(json.dumps(sys.argv[1:]))\n" f"print('console diagnostic', file=sys.stderr)\nsys.exit({status})\n", encoding="utf-8", ) fake.chmod(0o755) arguments = ["from-table", "table with spaces.md", "--id", "pass", "--title", "A title", "--context", "a\nb", "", "--"] enter_capsule(tmp_path, monkeypatch, fake) + # The fixture interpreter ignores Python startup settings from the host. + monkeypatch.setenv("PYTHONHOME", str(tmp_path / "not-a-python-installation")) result = run_console_decisions(arguments) From e401b825db92ec4ba61446c9fbe71ace793bc52c Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Wed, 11 Nov 2026 02:00:24 +0000 Subject: [PATCH 07/75] Record the review of PR #26 and the validation of the merged branch PR #27, the Codex and GPT-6 Astra review, was accepted at 1b5d3fc7 without a round and merged at 60ad2c5a. The status records what it changed, and corrects a judgment of mine it disproved: the default build-record lookup can be tested, by building a package directory and replacing files at its lookup site. Validation on the merged branch in the owner's capsule: the unit session gives the 17 standing failures of the blocking record and 2914 passed; type check, CLI smoke, executable build and smoke, documentation contract and console session pass. Hosted run of PR #26 at the merge: 2950 passed. 25 of the 26 planted faults are caught by the unit files, the last by the integration file. The pair review document gains the loop's row. Co-Authored-By: Claude --- .../development/review-partner-loop.md | 1 + .../2026-09-18-maintenance/CURRENT-STATUS.md | 69 ++++++++++++++----- 2 files changed, 54 insertions(+), 16 deletions(-) diff --git a/engineering-docs/development/review-partner-loop.md b/engineering-docs/development/review-partner-loop.md index 09c54df5..5d73637d 100644 --- a/engineering-docs/development/review-partner-loop.md +++ b/engineering-docs/development/review-partner-loop.md @@ -299,6 +299,7 @@ when the workstream pauses, and say so in its open threads. | Date | Workstream | Implementor | Review partner | Slices and reviews | Outcome | |---|---|---|---|---|---| +| 2026-11-11 | maintenance, PR #18's test-only parameters removed and the tests set the host at its source (follow-up to #18, `0.3.1`) | Claude Code, Claude Fable 5.2 pair | Codex, gpt-6-astra (high) pair | #26/#27 | accepted at `1b5d3fc7` without a round, merged at `60ad2c5a`; the first loop whose brief asks for the hosted check's result and names the capsule's standing unit failures, and whose review started only on a green hosted run; the reviewer corrected a docstring that claimed more than the launcher enforces, ended each process-wide test patch with its action, read the session environment when the supervisor is made, replaced an expected value derived from the constant under test, and added a test of the default build-record lookup that the implementor had recorded as impossible; 13 planted faults of its own and 25 of the implementor's 26 caught by the unit files, the last by the integration file; GitHub runs no check on a pull request into a slice branch, so the hosted run of #26 after the merge is the one that counts; the capsule's 17 standing failures keep `nox -s build` from passing as one session, its parts were run one by one; four proposals recorded in the `maintenance` status; brief committed under `evidence/2026-11-11-host-inputs-at-source/review-brief.md` | | 2026-11-08 / 2026-11-09 | maintenance, launcher-delivered web console (`D-0017`, 0.3.1 candidate 2 blocker, stacked on #18) | Antigravity, Gemini 4 Argon (High) pair | Claude Code, Claude Fable 5.1 pair | #16/#17 | accepted at `e23e22c7` without a round, merged at `9919f4ce`, and rebased onto PR #18 (`ws-maintenance/webconsole-legacy-tests`) per owner decision `stacked-delivery-branch = force-push-pr-16`; the reviewer removed the dead per-start `import psutil` subprocess probe (`WEBCONSOLE_RECIPE` 11 settles compatibility on the host) and unified console package precedence in `console_package_path`, fixed `extract_webconsole_bundle` to mask `external_attr >> 16` with `S_IFMT` so typeless regular zip entries (`ZipFile.writestr`) extract, pinned `match=` on every bundle refusal test (99% bundle coverage), tightened `DEVCAPSULE_DEV_WEBCONSOLE` to `1`/`true`/`0`/`false`, and aligned `D-0017` and the bug record; stacked gate 2904 unit tests, 40 integration (3 skipped), 458 webconsole, 332 mypy files, 104 legacy / 44 conforming files with 0 breaches, 249 contract pages, plus live base-Python HTTP check; remaining unimplemented proposals recorded in `maintenance` status; brief committed under `evidence/2026-11-08-webconsole-delivery/review-brief.md` | | 2026-11-09 | maintenance, whole-file legacy test retirement and 4-file refurbishment (`0.3.1` prerequisite) | Antigravity, Gemini 4 Argon (High) pair | Claude Code, Claude Fable 5.1 pair | #18/#19 | accepted at `4aac5dfc` without a round, merged at `a1aad17f`; completed `__all__` in `console.py`, `entrypoint.py` and `materialization.py`, dropped a dead `subprocess` import in `project.py`, stated basename pairing and mirror test deletion refusal across rule 5, the companion, the developer guide and the checker with 4 new checker tests, proved `entrypoint.run` writes session variables only into the supplied `environ`, and restored interpreter-path matching in `test_console_tools.py`; hosted CI on `e301367d` caught `/ide-config` state-slot paths in `test_entrypoint.py` (masked inside the PyCharm capsule), resolved by confining `make_plan` to `tmp_path` and injecting `runtime_root`, `caller_uid`, and `configure_logs` across `filesystem.py`, `identity.py`, and `entrypoint.run` (`test_filesystem.py` added, implementing PR #19's third proposal with zero global state); gate 2842 unit, 36 integration (1 skipped), 458 webconsole, 330 mypy files, 104 legacy / 43 conforming files with 0 breaches, 249 contract pages; two remaining proposals recorded in `maintenance` status; brief committed under `evidence/2026-11-08-webconsole-legacy-tests/review-brief.md` | | 2026-11-08 | maintenance, the web console's Files page (slice 2 of 0.3.1) | Antigravity, Gemini 4 Argon (High) pair | Claude Code, Claude Fable 5.1 pair | #12/#13 | accepted at `49bb2e8e` without a round, merged at `83949a30`; the first loop with the pairs reversed at the owner's word, the reviewer's pair writing the implementor brief from the owner's order; the reviewer removed a raw-route branch that detected its own test and repointed the legacy permission test at the streaming open, and smoked the routes against a standalone console; gate on the merged branch 458 console tests, 2825 unit tests, 0 breaches, 249 contract pages; both briefs committed under the workstream's evidence; the Antigravity stream-json form relayed one event per tool step, proving that form | diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index cf1a0c07..9cc32cc8 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -70,8 +70,12 @@ Judgments taken, for the owner's review: and never a private one; the conforming tests merged on 2026-11-04 and 2026-11-05 do the same (`status.read_metadata`, `runtime_artifact.current_build_info`). -2. `current_build_info` keeps its three parameters: the stamped record lies - inside the installed package, where a test cannot build it. +2. `current_build_info` keeps its three parameters. The reason first + recorded here, that a test cannot build the stamped record where the + function looks for it, was wrong, and the review showed it: its test + builds a package directory and replaces `files` at its lookup site. The + parameters stay because the authored `pyproject.toml` is found through a + private constant, which a test does not patch. `console_decisions_command` keeps the four it had before PR #18; its defaults are now run by the tests of `run_console_decisions`. 3. `commands/project.py` gets no mirror test: a mirror would oblige its @@ -80,21 +84,48 @@ Judgments taken, for the owner's review: delegates is run by the integration file only. 4. The target is `release-0.3.1`, as it was for PR #18. +Pair Review (`Codex + GPT-6 Astra`, +[brief](evidence/2026-11-11-host-inputs-at-source/review-brief.md)) opened +[PR #27](https://github.com/mycodespace-ai/devcapsule/pull/27) (`PR26.1`), +accepted at `1b5d3fc7` without a round and merged at `60ad2c5a`. The review +started only after the hosted run of PR #26 was green, and read it again +before reporting. It found that the new sentence in `images/contract.py` +claimed more than the launcher enforces, since `_launcher.py` plans a +console when no label result is supplied, and reworded it; ended each +process-wide patch (`os.environ`, `os.geteuid`, `os.chown`, +`socket.create_connection`) with the action it serves; made the environment +test read the environment when the supervisor is made and assert the +graphics defaults; asserted the runtime directory under `/tmp` and not under +the constant the code reads; kept the console tools mirror to its own unit; +isolated the fake interpreter from Python startup settings; and added the +test of the default build-record lookup. Its own 13 planted faults were all +caught. GitHub runs no check on a pull request into a slice branch, so the +hosted run of PR #26 after the merge is the one that counts. + Evidence: 26 faults planted one at a time in a scratch copy of the tree and -run against the touched unit files. 24 are caught there, among them the five -that PR #18 had lost. One, the command dropping its arguments, is caught by -the integration file only. One survives both, as it did before PR #18: a -built executable that never finds its stamped record; the gate's smoke runs -`version --json` and reads only its exit status. - -Validation at `8274a546`, in the owner's capsule: `nox -s tests` gives 17 -failed and 2913 passed, the 17 of the +run against the touched unit files. On the merged branch 25 are caught +there, among them the five that PR #18 had lost and the one no unit test +had ever caught, a built executable that never finds its stamped record. +The last, the command dropping its arguments, is caught by the integration +file only. + +Validation in the owner's capsule, on the merged branch at `60ad2c5a`: +`nox -s tests` gives 17 failed and 2914 passed, the 17 of the [blocking record](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) -and no other; the convention check counts 103 legacy files with 1372 legacy -tests and 49 conforming files, 0 breaches; mypy is clean over 330 files; the -integration file gives 10 passed. The gate as a whole cannot pass in this -capsule while those 17 stand, so the hosted run is the authority for the -suite. +and no other, as before the review at `8274a546` with 2913 passed; the +convention check counts 103 legacy files with 1372 legacy tests and 49 +conforming files, 0 breaches; mypy is clean over 336 files; the CLI smoke +passes; the executable builds and its smoke passes; the documentation +contract holds over 249 pages; the console session gives 458 passed; the +integration file gives 10 passed. `nox -s build` as one session cannot pass +in this capsule while those 17 stand, so its parts were run one by one. Hosted run of PR #26: 2949 passed at +`9dc4acfe` before the review, 2950 passed at the merge `60ad2c5a`, none +failed in either. The commit of these records after it changes no input of +the suite. + +Next action: the owner's review of PR #26 and of the four judgments. The +review partner's worktree, `~/worktrees/maintenance-review`, is kept until +the owner has decided. Proposals not implemented, for the owner: @@ -104,7 +135,13 @@ Proposals not implemented, for the owner: - *Pair Review Loop*: a review is accepted, and a slice recorded as validated, only on a green hosted run of the head; the brief asks for it. - The gate's smoke compares `version --json` of the built executable with - the stamp the build wrote. + the stamp the build wrote; today it reads the exit status only. The + review's unit test proves the lookup, not the contents of a built + executable. +- From the review: test the delegation of `project checkout decisions` in + the gate when the owner orders the refurbishment of + `tests/test_project.py`; decide whether the launcher's low-level default, + a console planned without labels read, should stand. - `WORKFLOW-LOCAL.md`, *Pair Review Loop In This Checkout*, rule 3 still names `/opt/devcapsule-gate` as the review partner's scratch, which the owner retired on 2026-11-04. From 60cab937e9f75942a54512acac3af69ef666ce14 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 01:00:50 +0000 Subject: [PATCH 08/75] Runtime, console tools, build info: host inputs become values; no touched test patches Owner direction of 2026-11-11: a value an inner module would be patched to supply is a parameter at construction; only the top layer maps the host; a unit test constructs ordinary values; classes bind the values that are used again and again. Product code: - identity: CapsuleUser(identity, caller_uid) replaces foreground_command; its owner_changes decides which new directories change owner. - filesystem: create_directories returns what it created; prepare_filesystem(plan, user) performs the owner changes. RUNTIME_ROOT is removed. - console: ConsoleInstallation(python, launcher_source) with package_path and child replaces console_package_path and console_child; probe_address is public. - session, new: Session(plan, job, user, console) decides the filesystem plan, the surface's launch, the variables to set, the display, the profile lock, the log settings and the children. - entrypoint: run reads the effective uid and the environment once, builds the session and performs its answers. Same signature. - console_tools: DecisionTools(in_capsule, console, runtime_plan_path) replaces two functions with four optional parameters; the command reads the environment. - build_info: distribution_build_info and embedded_build_info take every location as a value; current_build_info and is_built_distribution take none. build_info_text is the text `version` prints. Tests: the mirror files of these units and three integration files hold no monkeypatch use, from 26. The readiness probe meets a real loopback socket. run and the two command classes are exercised by integration tests that start the real programs in an environment the test builds: a headless and an interactive session with a stand-in IDE, `version`, and `project checkout decisions`. Rule 5: tests/test_runtime_entrypoint.py pinned the old signatures under patches, so the whole file is refurbished into the mirrors of contract, filesystem, identity, session, entrypoint, graphics and components/jetbrains, and deleted. graphics and jetbrains declare __all__. tests/test_contained_display.py, legacy, now defines the three helpers it imported from that file; none of its test functions changed. conftest no longer patches console.LAUNCHER_CONSOLE_SOURCE, which no unit test reads through an entry layer any more. Convention check: 102 legacy files, 1350 legacy tests, 0 breaches. Evidence: of 43 planted faults, the mirror files catch 26, legacy unit files 4, the integration files 8, and 5 are caught by nothing: the probe's timeout (two faults), `checkout decisions` dropping its arguments, uid and gid swapped in the one chown call, and the stamped record looked for outside the package. Of the 26 faults of 2026-11-11, the unit suite now catches 21, where the patched tests caught 25. Validation in the capsule: unit session 17 failed, the standing ones of the blocking record and no other, 2959 passed; type check, smoke, PEX build and smoke, docs contract pass. Co-Authored-By: Claude --- devcapsule-src/devcapsule/build_info.py | 117 ++--- devcapsule-src/devcapsule/commands/project.py | 13 +- devcapsule-src/devcapsule/commands/version.py | 10 +- devcapsule-src/devcapsule/console_tools.py | 104 ++-- .../container_runtime/components/jetbrains.py | 2 + .../devcapsule/container_runtime/console.py | 143 +++--- .../container_runtime/entrypoint.py | 117 ++--- .../container_runtime/filesystem.py | 36 +- .../devcapsule/container_runtime/graphics.py | 1 + .../devcapsule/container_runtime/identity.py | 54 ++- .../devcapsule/container_runtime/session.py | 163 +++++++ devcapsule-src/tests/conftest.py | 4 - .../integration/test_console_decisions_cli.py | 133 +++--- .../test_runtime_entrypoint_cli.py | 196 ++++++++ .../tests/integration/test_version_cli.py | 45 ++ .../tests/test_contained_display.py | 65 ++- .../tests/test_runtime_entrypoint.py | 444 ------------------ .../unit/devcapsule/commands/test_version.py | 53 --- .../container_runtime/components/__init__.py | 0 .../components/test_jetbrains.py | 92 ++++ .../container_runtime/test_console.py | 196 ++++---- .../container_runtime/test_contract.py | 245 +++++++++- .../container_runtime/test_entrypoint.py | 194 ++------ .../container_runtime/test_filesystem.py | 77 +-- .../container_runtime/test_graphics.py | 28 ++ .../container_runtime/test_identity.py | 53 ++- .../container_runtime/test_session.py | 434 +++++++++++++++++ .../tests/unit/devcapsule/test_build_info.py | 147 +++--- .../unit/devcapsule/test_console_tools.py | 151 +++--- ...7-launcher-delivers-web-console-package.md | 2 +- 30 files changed, 1991 insertions(+), 1328 deletions(-) create mode 100644 devcapsule-src/devcapsule/container_runtime/session.py create mode 100644 devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py create mode 100644 devcapsule-src/tests/integration/test_version_cli.py delete mode 100644 devcapsule-src/tests/test_runtime_entrypoint.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/commands/test_version.py create mode 100644 devcapsule-src/tests/unit/devcapsule/container_runtime/components/__init__.py create mode 100644 devcapsule-src/tests/unit/devcapsule/container_runtime/components/test_jetbrains.py create mode 100644 devcapsule-src/tests/unit/devcapsule/container_runtime/test_graphics.py create mode 100644 devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py diff --git a/devcapsule-src/devcapsule/build_info.py b/devcapsule-src/devcapsule/build_info.py index 459f1c90..fc2939c8 100644 --- a/devcapsule-src/devcapsule/build_info.py +++ b/devcapsule-src/devcapsule/build_info.py @@ -10,14 +10,17 @@ from pathlib import Path import re import tomllib -from typing import Any, Mapping, Sequence +from typing import Any, Callable, Mapping, Sequence from zipfile import BadZipFile, ZipFile __all__ = [ "BuildInfo", "BuildInfoError", "build_info_json", + "build_info_text", "current_build_info", + "distribution_build_info", + "embedded_build_info", "is_built_distribution", "read_pex_build_info", ] @@ -89,10 +92,7 @@ def to_mapping(self) -> dict[str, Any]: _SOURCE_PYPROJECT = Path(__file__).parents[1] / "pyproject.toml" -def is_built_distribution( - *, - record_paths: Sequence[Traversable | Path] | None = None, -) -> bool: +def is_built_distribution() -> bool: """Whether this process runs from a ``scripts/build-pex.sh`` artifact rather than source. Only that script creates ``_build_info.json``, so the record's presence is @@ -102,69 +102,57 @@ def is_built_distribution( record raises :class:`BuildInfoError` instead of masquerading as source. """ - return _embedded_build_info(record_paths) is not None + return embedded_build_info(_package_locations()) is not None -def current_build_info( - *, - record_paths: Sequence[Traversable | Path] | None = None, - pyproject_path: Path | None = None, - installed_version: str | None = None, -) -> BuildInfo: +def current_build_info() -> BuildInfo: """Describe this running distribution: its stamped build, or its source form. - Only ``scripts/build-pex.sh`` creates ``_build_info.json``, so the record's - presence is the definition of a built artifact; a present-but-malformed - record therefore stays an error rather than masquerading as source. In its - absence this is a source-form run — nothing was built, so there is no build - to describe — and the identity is derived: the version from the installed - distribution metadata that ``pyproject.toml`` alone authors, and the - ``v-local`` mnemonic that marks an unbuilt source run. + This names where the running distribution keeps its package, its authored + ``pyproject.toml`` and its installed metadata; :func:`distribution_build_info` + decides from them. """ - embedded = _embedded_build_info(record_paths) - if embedded is not None: - return embedded - return _source_form_build_info( - pyproject_path=_SOURCE_PYPROJECT if pyproject_path is None else pyproject_path, - installed_version=installed_version, + return distribution_build_info( + package_locations=_package_locations(), + pyproject_path=_SOURCE_PYPROJECT, + installed_version=_installed_version, ) -def _embedded_build_info( - record_paths: Sequence[Traversable | Path] | None = None, -) -> BuildInfo | None: - """The stamped record of a built artifact, or ``None`` in a source-form run.""" - - candidates: Sequence[Traversable | Path] = ( - record_paths - if record_paths is not None - else ( - files("devcapsule").joinpath("_build_info.json"), - # Some editable installers expose the project root as the package's - # resource location even though imports resolve to this source tree. - # The sibling path preserves source/PEX command parity without - # weakening the packaged-resource validation. - Path(__file__).with_name("_build_info.json"), - ) +def _package_locations() -> tuple[Traversable | Path, ...]: + return ( + files("devcapsule"), + # Some editable installers expose the project root as the package's + # resource location even though imports resolve to this source tree. + # The module's own directory preserves source/PEX command parity + # without weakening the packaged-resource validation. + Path(__file__).parent, ) - for candidate in candidates: - try: - text = candidate.read_text(encoding="utf-8") - except OSError: - continue - return BuildInfo.from_json(text) - return None -def _source_form_build_info( +def distribution_build_info( *, + package_locations: Sequence[Traversable | Path], pyproject_path: Path, - installed_version: str | None, + installed_version: Callable[[], str], ) -> BuildInfo: - package_version = _authored_version(pyproject_path) or ( - installed_version if installed_version is not None else _installed_version() - ) + """Describe the distribution these locations belong to: its stamped build, or its source form. + + Only ``scripts/build-pex.sh`` creates ``_build_info.json``, so the record's + presence in the package is the definition of a built artifact; a + present-but-malformed record therefore stays an error rather than + masquerading as source. In its absence this is a source-form run — nothing + was built, so there is no build to describe — and the identity is derived: + the version from ``pyproject_path`` when that is the authored file of a + source checkout, else from ``installed_version``, which is asked only then; + and the ``v-local`` mnemonic that marks an unbuilt source run. + """ + + embedded = embedded_build_info(package_locations) + if embedded is not None: + return embedded + package_version = _authored_version(pyproject_path) or installed_version() return BuildInfo( schema_version=2, version=package_version, @@ -175,6 +163,18 @@ def _source_form_build_info( ) +def embedded_build_info(package_locations: Sequence[Traversable | Path]) -> BuildInfo | None: + """The stamped ``_build_info.json`` of the first of ``package_locations`` that holds a readable one, or ``None``.""" + + for location in package_locations: + try: + text = location.joinpath("_build_info.json").read_text(encoding="utf-8") + except OSError: + continue + return BuildInfo.from_json(text) + return None + + def _authored_version(pyproject_path: Path) -> str | None: """The version pyproject.toml authors, when running from a source checkout. @@ -226,6 +226,17 @@ def build_info_json(info: BuildInfo) -> str: return json.dumps(info.to_mapping(), ensure_ascii=False, sort_keys=True, separators=(",", ":")) +def build_info_text(info: BuildInfo) -> str: + """The lines ``devcapsule version`` shows a person: the build, then where its source is.""" + + return "\n".join(( + f"DevCapsule {info.build_mnemonic} (package {info.version})", + f"Source repository: {info.source_repository}", + f"Source revision: {info.source_revision}", + f"Source URL: {info.source_url}", + )) + + def _string(value: Mapping[str, Any], key: str) -> str: selected = value.get(key) if not isinstance(selected, str) or not selected or "\x00" in selected: diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 3aea6dc5..01994c3f 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -621,9 +621,16 @@ def configure(cls, parser: argparse.ArgumentParser) -> None: @classmethod def run(cls, arguments: argparse.Namespace, context: object | None) -> int: - from devcapsule.console_tools import run_console_decisions - - return run_console_decisions(arguments.arguments) + from devcapsule.console_tools import DecisionTools + from devcapsule.container_runtime.console import ConsoleInstallation + from devcapsule.recursive_dogfood import CONTAINER_NAME_ENV, RUNTIME_PLAN_PATH + + tools = DecisionTools( + in_capsule=bool(os.environ.get(CONTAINER_NAME_ENV)), + console=ConsoleInstallation.of_image(), + runtime_plan_path=RUNTIME_PLAN_PATH, + ) + return tools.run(arguments.arguments) class CheckoutGroup(Group): diff --git a/devcapsule-src/devcapsule/commands/version.py b/devcapsule-src/devcapsule/commands/version.py index 7eb78019..05651ee2 100644 --- a/devcapsule-src/devcapsule/commands/version.py +++ b/devcapsule-src/devcapsule/commands/version.py @@ -4,7 +4,7 @@ import argparse -from devcapsule.build_info import build_info_json, current_build_info +from devcapsule.build_info import build_info_json, build_info_text, current_build_info from devcapsule.commands.framework import Command __all__ = ["COMMAND", "VersionCommand"] @@ -26,13 +26,7 @@ def configure(cls, parser: argparse.ArgumentParser) -> None: @classmethod def run(cls, arguments: argparse.Namespace, context: object | None) -> int: info = current_build_info() - if arguments.as_json: - print(build_info_json(info)) - return 0 - print(f"DevCapsule {info.build_mnemonic} (package {info.version})") - print(f"Source repository: {info.source_repository}") - print(f"Source revision: {info.source_revision}") - print(f"Source URL: {info.source_url}") + print(build_info_json(info) if arguments.as_json else build_info_text(info)) return 0 diff --git a/devcapsule-src/devcapsule/console_tools.py b/devcapsule-src/devcapsule/console_tools.py index f9475d43..4a94af77 100644 --- a/devcapsule-src/devcapsule/console_tools.py +++ b/devcapsule-src/devcapsule/console_tools.py @@ -12,73 +12,73 @@ from __future__ import annotations -import os +from dataclasses import dataclass from pathlib import Path import subprocess -from typing import Mapping, Sequence +from typing import Sequence from devcapsule.compat import CliError from devcapsule.configuration.file_formats import ProjectConfigurationError -from devcapsule.container_runtime import console as console_child +from devcapsule.container_runtime.console import CONSOLE_ROOT, ConsoleInstallation from devcapsule.container_runtime.contract import RuntimePlan, RuntimePlanError -from devcapsule import recursive_dogfood __all__ = [ "DECISIONS_MODULE", - "console_decisions_command", - "run_console_decisions", + "DecisionTools", ] DECISIONS_MODULE = "devcapsule_webconsole.decisions" -def console_decisions_command( - arguments: Sequence[str], - *, - environ: Mapping[str, str] | None = None, - console_python: Path | None = None, - runtime_plan_path: Path | None = None, - launcher_console_source: Path | None = None, -) -> tuple[str, ...]: - """The command that runs the console's ``decisions`` module with ``arguments``. +@dataclass(frozen=True) +class DecisionTools: + """The console's ``decisions`` module as one process can reach it. - Refuses outside a capsule, and inside one whose base predates the console, - naming what to run instead. The package on ``PYTHONPATH`` is the console - child's own choice, :func:`devcapsule.container_runtime.console.console_package_path`: - the runtime plan's ``console.source_path`` first, else the launcher-delivered - package at ``/opt/devcapsule/webconsole`` when present, else the base copy. + ``in_capsule`` says whether the process runs inside a capsule, ``console`` + where that capsule's image keeps the console, and ``runtime_plan_path`` + where the capsule's runtime plan is. The command that owns the CLI reads + the three from its process and builds this. """ - values = os.environ if environ is None else environ - python = console_python or Path(console_child.CONSOLE_PYTHON) - plan_path = runtime_plan_path or recursive_dogfood.RUNTIME_PLAN_PATH - bundled = launcher_console_source or Path(console_child.LAUNCHER_CONSOLE_SOURCE) - if not values.get(recursive_dogfood.CONTAINER_NAME_ENV): - raise ProjectConfigurationError( - "project checkout decisions runs inside a capsule, where the web console is installed; " - f"on a host, run `python -m {DECISIONS_MODULE}` from the devcapsule-webconsole checkout instead." - ) - if not python.is_file(): - raise ProjectConfigurationError( - f"this capsule's base has no web console at {console_child.CONSOLE_ROOT} (base recipe 10 adds it); " - "relaunch on a newer base to hand decisions to the console." - ) - source_path = "" - try: - plan = RuntimePlan.from_file(plan_path) - source_path = plan.console.source_path if plan.console else "" - except (RuntimePlanError, UnicodeError): - pass # Without a readable plan, the launcher package or the base copy answers. - command: tuple[str, ...] = (str(python), "-m", DECISIONS_MODULE, *arguments) - package_path = console_child.console_package_path(source_path, bundled) - if package_path: - command = ("env", f"PYTHONPATH={package_path}", *command) - return command + in_capsule: bool + console: ConsoleInstallation + runtime_plan_path: Path -def run_console_decisions(arguments: Sequence[str]) -> int: - """Execute ``devcapsule_webconsole.decisions`` in the capsule's console interpreter.""" - command = console_decisions_command(arguments) - try: - return subprocess.run(command, check=False).returncode - except OSError as error: - raise CliError(f"cannot run the console's decision tools: {error}") from error + def command(self, arguments: Sequence[str]) -> tuple[str, ...]: + """The command that runs the console's ``decisions`` module with ``arguments``. + + Refuses outside a capsule, and inside one whose base predates the console, + naming what to run instead. The package on ``PYTHONPATH`` is the console + child's own choice, :meth:`ConsoleInstallation.package_path`: the runtime + plan's ``console.source_path`` first, else the launcher-delivered package + when present, else the base copy. + """ + if not self.in_capsule: + raise ProjectConfigurationError( + "project checkout decisions runs inside a capsule, where the web console is installed; " + f"on a host, run `python -m {DECISIONS_MODULE}` from the devcapsule-webconsole checkout instead." + ) + if not self.console.python.is_file(): + raise ProjectConfigurationError( + f"this capsule's base has no web console at {CONSOLE_ROOT} (base recipe 10 adds it); " + "relaunch on a newer base to hand decisions to the console." + ) + source_path = "" + try: + plan = RuntimePlan.from_file(self.runtime_plan_path) + source_path = plan.console.source_path if plan.console else "" + except (RuntimePlanError, UnicodeError): + pass # Without a readable plan, the launcher package or the base copy answers. + command: tuple[str, ...] = (str(self.console.python), "-m", DECISIONS_MODULE, *arguments) + package_path = self.console.package_path(source_path) + if package_path: + command = ("env", f"PYTHONPATH={package_path}", *command) + return command + + def run(self, arguments: Sequence[str]) -> int: + """Execute the ``decisions`` module with ``arguments`` and return its exit status.""" + command = self.command(arguments) + try: + return subprocess.run(command, check=False).returncode + except OSError as error: + raise CliError(f"cannot run the console's decision tools: {error}") from error diff --git a/devcapsule-src/devcapsule/container_runtime/components/jetbrains.py b/devcapsule-src/devcapsule/container_runtime/components/jetbrains.py index d85b58d7..79b26c88 100644 --- a/devcapsule-src/devcapsule/container_runtime/components/jetbrains.py +++ b/devcapsule-src/devcapsule/container_runtime/components/jetbrains.py @@ -16,6 +16,8 @@ from ..contract import RuntimePlan, RuntimePlanError +__all__ = ["JetBrainsLaunch", "plan", "recover_dead_socket", "session_lock"] + @contextmanager def session_lock(runtime: RuntimePlan) -> Iterator[None]: diff --git a/devcapsule-src/devcapsule/container_runtime/console.py b/devcapsule-src/devcapsule/container_runtime/console.py index bcaed3f2..d9424671 100644 --- a/devcapsule-src/devcapsule/container_runtime/console.py +++ b/devcapsule-src/devcapsule/container_runtime/console.py @@ -16,6 +16,7 @@ from __future__ import annotations +from dataclasses import dataclass from pathlib import Path import socket import sys @@ -32,10 +33,10 @@ "CONSOLE_READY_TIMEOUT_SECONDS", "CONSOLE_ROOT", "CommandWrapper", + "ConsoleInstallation", "LAUNCHER_CONSOLE_SOURCE", "RUNTIME_CLI", - "console_child", - "console_package_path", + "probe_address", ] CONSOLE_CHILD = "console" @@ -53,69 +54,95 @@ CommandWrapper = Callable[[tuple[str, ...]], tuple[str, ...]] -def console_child(plan: RuntimePlan, run_as_identity: CommandWrapper) -> SupervisedChild | None: - """The console child for ``plan``, or ``None`` when there is none to start. +@dataclass(frozen=True) +class ConsoleInstallation: + """Where one image keeps the web console: the base's interpreter and the launcher's package. - ``None`` when the plan carries no console section, and, announced, when - the base predates the console (recipe 9 and earlier): the runtime is - launcher-supplied and runs on any base carrying the display label, so an - absent console is a known degradation rather than a failed start. The - package the child imports is :func:`console_package_path`'s choice. + An entry layer builds the image's own with :meth:`of_image` and hands it + down; nothing below names a console path of its own. """ - console = plan.console - if console is None: - return None - if not Path(CONSOLE_PYTHON).is_file(): - print( - f"devcapsule console: this base has no web console (base recipe 10 adds it at {CONSOLE_ROOT}); " - "the capsule runs without one", - file=sys.stderr, - flush=True, + python: Path + launcher_source: Path + + @classmethod + def of_image(cls) -> ConsoleInstallation: + """The installation at the paths every DevCapsule image uses.""" + + return cls(Path(CONSOLE_PYTHON), Path(LAUNCHER_CONSOLE_SOURCE)) + + def package_path(self, source_path: str) -> str: + """The directory to put first on ``PYTHONPATH``, or empty for the base's copy. + + Precedence under ``D-0017``: the runtime plan's ``console.source_path`` + when it names a mounted checkout, else ``launcher_source`` when + materialization installed the launcher's package there, else empty, and + the base image's installed copy answers the import. + """ + + if source_path: + return source_path + if (self.launcher_source / PACKAGE_NAME / "__init__.py").is_file(): + return str(self.launcher_source) + return "" + + def child(self, plan: RuntimePlan, run_as_identity: CommandWrapper) -> SupervisedChild | None: + """The console child for ``plan``, or ``None`` when there is none to start. + + ``None`` when the plan carries no console section, and, announced, when + the base predates the console (recipe 9 and earlier): the runtime is + launcher-supplied and runs on any base carrying the display label, so an + absent console is a known degradation rather than a failed start. The + package the child imports is :meth:`package_path`'s choice. + """ + + console = plan.console + if console is None: + return None + if not self.python.is_file(): + print( + f"devcapsule console: this base has no web console (base recipe 10 adds it at {CONSOLE_ROOT}); " + "the capsule runs without one", + file=sys.stderr, + flush=True, + ) + return None + command: tuple[str, ...] = ( + str(self.python), "-m", PACKAGE_NAME, + "--project", plan.project_path, + "--cli", RUNTIME_CLI, + "--token-file", console.token_path, + "--listen", console.listen_address, + "--port", str(console.port), ) - return None - command: tuple[str, ...] = ( - CONSOLE_PYTHON, "-m", PACKAGE_NAME, - "--project", plan.project_path, - "--cli", RUNTIME_CLI, - "--token-file", console.token_path, - "--listen", console.listen_address, - "--port", str(console.port), - ) - package_path = console_package_path(console.source_path, Path(LAUNCHER_CONSOLE_SOURCE)) - if package_path: - # ``env`` replaces any ambient PYTHONPATH: the same interpreter and - # dependencies, the selected package ahead of the base's installed copy. - command = ("env", f"PYTHONPATH={package_path}", *command) - if console.source_path: - print( - f"devcapsule console: running the mounted checkout's source at {console.source_path}", - file=sys.stderr, - flush=True, + package_path = self.package_path(console.source_path) + if package_path: + # ``env`` replaces any ambient PYTHONPATH: the same interpreter and + # dependencies, the selected package ahead of the base's installed copy. + command = ("env", f"PYTHONPATH={package_path}", *command) + if console.source_path: + print( + f"devcapsule console: running the mounted checkout's source at {console.source_path}", + file=sys.stderr, + flush=True, + ) + address = probe_address(console.listen_address) + return SupervisedChild( + name=CONSOLE_CHILD, + command=run_as_identity(command), + ready=lambda: _accepts_connections(address, console.port), + ready_timeout_seconds=CONSOLE_READY_TIMEOUT_SECONDS, ) - probe_address = {"0.0.0.0": "127.0.0.1", "::": "::1"}.get(console.listen_address, console.listen_address) - return SupervisedChild( - name=CONSOLE_CHILD, - command=run_as_identity(command), - ready=lambda: _accepts_connections(probe_address, console.port), - ready_timeout_seconds=CONSOLE_READY_TIMEOUT_SECONDS, - ) - - -def console_package_path(source_path: str, launcher_source: Path) -> str: - """The directory to put first on ``PYTHONPATH``, or empty for the base's copy. - - Precedence under ``D-0017``: the runtime plan's ``console.source_path`` - when it names a mounted checkout, else ``launcher_source`` when - materialization installed the launcher's package there, else empty, and - the base image's installed copy answers the import. + + +def probe_address(listen_address: str) -> str: + """The address at which to ask whether a listener on ``listen_address`` answers. + + A listener on every interface is asked on the loopback of its family; + one on a named address is asked there. """ - if source_path: - return source_path - if (launcher_source / PACKAGE_NAME / "__init__.py").is_file(): - return str(launcher_source) - return "" + return {"0.0.0.0": "127.0.0.1", "::": "::1"}.get(listen_address, listen_address) def _accepts_connections(address: str, port: int) -> bool: diff --git a/devcapsule-src/devcapsule/container_runtime/entrypoint.py b/devcapsule-src/devcapsule/container_runtime/entrypoint.py index ce6717de..54b125bd 100644 --- a/devcapsule-src/devcapsule/container_runtime/entrypoint.py +++ b/devcapsule-src/devcapsule/container_runtime/entrypoint.py @@ -10,34 +10,33 @@ bridge); see ``display.py``. A headless job declares no display at all. When the plan carries a console section, the web console runs beside either; see ``console.py``. + +What a session needs and which children it runs is decided in ``session.py``, +from values alone. This module reads the host and performs those decisions. """ from __future__ import annotations from contextlib import nullcontext -from dataclasses import replace import os from pathlib import Path import sys from typing import Sequence -from . import contract as rtcontract from .. import logs -from .components import eclipse, jetbrains, vscode -from .console import console_child +from .components import jetbrains +from .console import ConsoleInstallation from .contract import RuntimePlan, RuntimePlanError from .display import prepare_contained_display -from .filesystem import plan_filesystem, prepare_filesystem -from .graphics import environment as graphics_environment -from .identity import foreground_command +from .filesystem import prepare_filesystem +from .identity import CapsuleUser +from .session import Session from .supervisor import SupervisedChild, Supervisor, SupervisorError __all__ = [ "SUPERVISOR_LOG_COMPONENT", "USAGE", - "log_rotation", - "logged_children", "main", "run", ] @@ -51,84 +50,40 @@ SUPERVISOR_LOG_COMPONENT = "supervisor" -def run(plan: rtcontract.RuntimePlan, job: tuple[str, ...] | None = None) -> int: - owner = (plan.identity.uid, plan.identity.gid) - log_directory = None if plan.logs is None else plan.logs.directory - segment_bytes, rotations = log_rotation(plan) - logs.configure(SUPERVISOR_LOG_COMPONENT, log_directory, owner=owner, segment_bytes=segment_bytes, rotations=rotations) - filesystem = plan_filesystem(plan) - prepare_filesystem(filesystem, plan.identity) - os.environ.update(filesystem.environment) - os.environ.update(plan.component_environment()) - os.environ.update(graphics_environment(os.environ)) - if plan.component.adapter == "jetbrains": - launch = jetbrains.plan(plan) - Path(launch.properties_path).write_text(launch.properties, encoding="utf-8") - os.environ[launch.properties_environment_variable] = launch.properties_path - command = launch.command - elif plan.component.adapter == "vscode": - command = vscode.plan(plan).command - elif plan.component.adapter == "eclipse": - command = eclipse.plan(plan).command - else: - raise RuntimePlanError(f"unsupported component adapter: {plan.component.adapter}") - - def as_capsule_user(child_command: tuple[str, ...]) -> tuple[str, ...]: - return foreground_command(child_command, plan.identity) - - infrastructure: tuple[SupervisedChild, ...] = () - if job is None and plan.display is not None and plan.display.is_contained: - contained = prepare_contained_display(plan, filesystem.environment["XDG_RUNTIME_DIR"], as_capsule_user) - os.environ.update(contained.environment) - infrastructure = contained.children - console = console_child(plan, as_capsule_user) - if console is not None: - infrastructure = (*infrastructure, console) - if job is None: - child = SupervisedChild( - name=plan.component.id, - command=foreground_command(command, plan.identity), - foreground=True, - ) - else: - # Headless mode: the same distinguished slot with no GUI. The job runs - # in the project it was launched against, not the image's workdir. - child = SupervisedChild( - name="job", - command=foreground_command(job, plan.identity), - foreground=True, - working_directory=plan.project_path, +def run(plan: RuntimePlan, job: tuple[str, ...] | None = None) -> int: + """Prepare the capsule for ``plan`` and supervise its session to the foreground child's exit. + + This is where the runtime meets its host. It reads the process once, its + effective uid and its environment, and names the image's console; from + there :class:`Session` decides, and each statement below performs one of + its answers. + """ + + session = Session(plan, job, CapsuleUser(plan.identity, os.geteuid()), ConsoleInstallation.of_image()) + segment_bytes, rotations = session.log_rotation + logs.configure( + SUPERVISOR_LOG_COMPONENT, session.log_directory, + owner=session.log_owner, segment_bytes=segment_bytes, rotations=rotations, + ) + prepare_filesystem(session.filesystem, session.user) + os.environ.update(session.environment(os.environ)) + for path, text in session.launch.files.items(): + Path(path).write_text(text, encoding="utf-8") + display_children: tuple[SupervisedChild, ...] = () + if session.shows_contained_display: + display = prepare_contained_display( + plan, session.filesystem.environment["XDG_RUNTIME_DIR"], session.user.command, ) - guard = jetbrains.session_lock(plan) if plan.component.adapter == "jetbrains" and job is None else nullcontext() + os.environ.update(display.environment) + display_children = display.children + children = session.children(display_children) + guard = jetbrains.session_lock(plan) if session.holds_profile_lock else nullcontext() with guard: return Supervisor( - logged_children((*infrastructure, child), log_directory), - log_owner=owner, segment_bytes=segment_bytes, rotations=rotations, + children, log_owner=session.log_owner, segment_bytes=segment_bytes, rotations=rotations, ).run() -def log_rotation(plan: rtcontract.RuntimePlan) -> tuple[int, int]: - """The segment and rotation count every writer of this session uses. - - The plan's logs section carries them when the launcher derived them from - the budget; a plan from before they existed gets the defaults. - """ - - if plan.logs is not None and plan.logs.rotates: - return plan.logs.segment_bytes, plan.logs.rotations - return logs.MAXIMUM_SEGMENT_BYTES, logs.ROTATIONS - - -def logged_children( - children: tuple[SupervisedChild, ...], log_directory: str | None -) -> tuple[SupervisedChild, ...]: - """Give every child its own log file, ``devcapsule-.log``, when logging is on.""" - - if log_directory is None: - return children - return tuple(replace(child, log_path=str(logs.log_path(log_directory, child.name))) for child in children) - - def main(argv: Sequence[str] | None = None) -> int: arguments = list(sys.argv[1:] if argv is None else argv) if arguments[:1] == ["diagnose-probe"]: diff --git a/devcapsule-src/devcapsule/container_runtime/filesystem.py b/devcapsule-src/devcapsule/container_runtime/filesystem.py index 4f903d0f..5d84388c 100644 --- a/devcapsule-src/devcapsule/container_runtime/filesystem.py +++ b/devcapsule-src/devcapsule/container_runtime/filesystem.py @@ -6,12 +6,10 @@ import os from pathlib import Path -from .contract import Identity, RuntimePlan +from .contract import RuntimePlan +from .identity import CapsuleUser -__all__ = ["FilesystemPlan", "RUNTIME_ROOT", "plan_filesystem", "prepare_filesystem"] - -RUNTIME_ROOT = "/tmp" -"""Where a session's ``XDG_RUNTIME_DIR`` is made: the image's temporary directory.""" +__all__ = ["FilesystemPlan", "create_directories", "plan_filesystem", "prepare_filesystem"] @dataclass(frozen=True) @@ -29,14 +27,22 @@ def plan_filesystem(runtime: RuntimePlan) -> FilesystemPlan: "XDG_DATA_HOME": str(home / ".local" / "share"), "XDG_STATE_HOME": str(home / ".local" / "state"), "XDG_CACHE_HOME": str(home / ".cache"), - "XDG_RUNTIME_DIR": str(Path(RUNTIME_ROOT) / f"devcapsule-runtime-{runtime.identity.uid}"), + "XDG_RUNTIME_DIR": f"/tmp/devcapsule-runtime-{runtime.identity.uid}", } directories = (str(home), str(home / ".ssh"), str(home / "xtras" / "bin"), *environment.values(), *slots) return FilesystemPlan(tuple(dict.fromkeys(directories)), environment) -def prepare_filesystem(plan: FilesystemPlan, identity: Identity) -> None: +def create_directories(plan: FilesystemPlan) -> tuple[Path, ...]: + """Create every directory of ``plan``; keep ``.ssh`` and the runtime directory private. + + Returns the directories this call created, a parent before its child. + A directory that existed is not among them, so its owner stays as the + volume or the image set it. + """ + + created: list[Path] = [] for directory in plan.directories: path = Path(directory) missing: list[Path] = [] @@ -45,8 +51,18 @@ def prepare_filesystem(plan: FilesystemPlan, identity: Identity) -> None: missing.append(cursor) cursor = cursor.parent path.mkdir(parents=True, exist_ok=True) - if os.geteuid() == 0: - for created in reversed(missing): - os.chown(created, identity.uid, identity.gid) + created.extend(reversed(missing)) Path(plan.environment["XDG_RUNTIME_DIR"]).chmod(0o700) Path(plan.environment["HOME"], ".ssh").chmod(0o700) + return tuple(created) + + +def prepare_filesystem(plan: FilesystemPlan, user: CapsuleUser) -> None: + """Create the session's directories and give the new ones to the capsule user. + + Which owners change is :meth:`CapsuleUser.owner_changes`' decision; this + only performs it. + """ + + for path, uid, gid in user.owner_changes(create_directories(plan)): + os.chown(path, uid, gid) diff --git a/devcapsule-src/devcapsule/container_runtime/graphics.py b/devcapsule-src/devcapsule/container_runtime/graphics.py index 130ff8d1..3de57d60 100644 --- a/devcapsule-src/devcapsule/container_runtime/graphics.py +++ b/devcapsule-src/devcapsule/container_runtime/graphics.py @@ -4,6 +4,7 @@ from typing import Mapping +__all__ = ["DEFAULTS", "environment"] DEFAULTS = { "NO_AT_BRIDGE": "1", diff --git a/devcapsule-src/devcapsule/container_runtime/identity.py b/devcapsule-src/devcapsule/container_runtime/identity.py index 2f0bf1d8..6392f2a6 100644 --- a/devcapsule-src/devcapsule/container_runtime/identity.py +++ b/devcapsule-src/devcapsule/container_runtime/identity.py @@ -1,23 +1,53 @@ -"""Privilege-drop command planning; gosu owns the security-sensitive switch.""" +"""The capsule user as the preparing process sees it; gosu owns the security-sensitive switch.""" from __future__ import annotations -import os +from dataclasses import dataclass +from pathlib import Path +from typing import Iterable from .contract import Identity -__all__ = ["foreground_command"] +__all__ = ["CapsuleUser"] -def foreground_command(command: tuple[str, ...], identity: Identity) -> tuple[str, ...]: - """Wrap ``command`` so it runs as the capsule user when the caller is root. +@dataclass(frozen=True) +class CapsuleUser: + """The capsule's user, and the effective uid of the process that prepares the session. - Named for its first use; every supervised child, infrastructure included, - is wrapped the same way, so no display or IDE process ever runs as root. + The entrypoint reads that uid once and builds this value. Everything + below asks it, and never the operating system, whether the caller is + root: root must hand each child and each new directory to the capsule + user, and any other caller already is that user. """ - if not command: - raise ValueError("foreground command must not be empty") - if os.geteuid() == 0: - return ("gosu", f"{identity.uid}:{identity.gid}", *command) - return command + identity: Identity + caller_uid: int + + @property + def caller_is_root(self) -> bool: + return self.caller_uid == 0 + + def command(self, command: tuple[str, ...]) -> tuple[str, ...]: + """``command`` as a supervised child runs it: behind ``gosu`` when the caller is root. + + Every supervised child, infrastructure included, is wrapped the same + way, so no display or IDE process ever runs as root. + """ + + if not command: + raise ValueError("foreground command must not be empty") + if self.caller_is_root: + return ("gosu", f"{self.identity.uid}:{self.identity.gid}", *command) + return command + + def owner_changes(self, created: Iterable[Path]) -> tuple[tuple[Path, int, int], ...]: + """The ``(path, uid, gid)`` changes that give ``created`` to the capsule user. + + One per path, in the given order, when the caller is root; none + otherwise, since what another caller creates is the user's already. + """ + + if not self.caller_is_root: + return () + return tuple((path, self.identity.uid, self.identity.gid) for path in created) diff --git a/devcapsule-src/devcapsule/container_runtime/session.py b/devcapsule-src/devcapsule/container_runtime/session.py new file mode 100644 index 00000000..53aff08c --- /dev/null +++ b/devcapsule-src/devcapsule/container_runtime/session.py @@ -0,0 +1,163 @@ +"""One capsule session's decisions, made from values before anything starts. + +The entrypoint reads the process once, builds a :class:`Session`, and performs +what it answers: the directories and variables the session needs, the files +its surface reads, and the children to supervise in their start order. + +Nothing here reads the process environment or the caller's uid, and nothing +here starts a program or writes a file. The one look at the host is +:meth:`Session.children` asking the console installation it was given whether +the image has a console. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field, replace +from functools import cached_property +from typing import Mapping + +from .. import logs + +from .components import eclipse, jetbrains, vscode +from .console import ConsoleInstallation +from .contract import RuntimePlan, RuntimePlanError +from .filesystem import FilesystemPlan, plan_filesystem +from .graphics import environment as graphics_environment +from .identity import CapsuleUser +from .supervisor import SupervisedChild + +__all__ = ["JOB_CHILD", "Session", "SurfaceLaunch"] + +JOB_CHILD = "job" +"""The name of the foreground child of a headless session.""" + + +@dataclass(frozen=True) +class SurfaceLaunch: + """How the plan's interactive surface starts, and what must be in place first.""" + + command: tuple[str, ...] + files: Mapping[str, str] = field(default_factory=dict) + """Text to write, by path, before the surface starts.""" + environment: Mapping[str, str] = field(default_factory=dict) + """The variables by which the surface finds those files.""" + + +@dataclass(frozen=True) +class Session: + """The session of ``plan``: interactive, or the headless ``job`` when one is given. + + ``user`` says who prepares the session and for whom; ``console`` says + where the image keeps the web console. + """ + + plan: RuntimePlan + job: tuple[str, ...] | None + user: CapsuleUser + console: ConsoleInstallation + + @cached_property + def filesystem(self) -> FilesystemPlan: + return plan_filesystem(self.plan) + + @cached_property + def launch(self) -> SurfaceLaunch: + """The surface's launch, as the adapter of the plan's component plans it. + + A headless session prepares the same files and variables and leaves + only the command unused. + """ + + adapter = self.plan.component.adapter + if adapter == "jetbrains": + planned = jetbrains.plan(self.plan) + return SurfaceLaunch( + planned.command, + files={planned.properties_path: planned.properties}, + environment={planned.properties_environment_variable: planned.properties_path}, + ) + if adapter == "vscode": + return SurfaceLaunch(vscode.plan(self.plan).command) + if adapter == "eclipse": + return SurfaceLaunch(eclipse.plan(self.plan).command) + raise RuntimePlanError(f"unsupported component adapter: {adapter}") + + def environment(self, existing: Mapping[str, str]) -> dict[str, str]: + """The variables to set before any child starts, in a process that has ``existing``. + + They are the session's paths, every component's variables and the + surface's own, a later one winning a name; then each graphics default + that neither ``existing`` nor those already decide. + """ + + planned = { + **self.filesystem.environment, + **self.plan.component_environment(), + **self.launch.environment, + } + return {**planned, **graphics_environment({**existing, **planned})} + + @property + def shows_contained_display(self) -> bool: + """Whether the contained display is prepared: the plan selects it and no job replaces the surface.""" + + return self.job is None and self.plan.display is not None and self.plan.display.is_contained + + @property + def holds_profile_lock(self) -> bool: + """Whether the session owns a JetBrains profile for as long as its surface runs.""" + + return self.job is None and self.plan.component.adapter == "jetbrains" + + @property + def log_directory(self) -> str | None: + return None if self.plan.logs is None else self.plan.logs.directory + + @property + def log_owner(self) -> tuple[int, int]: + return (self.plan.identity.uid, self.plan.identity.gid) + + @property + def log_rotation(self) -> tuple[int, int]: + """The segment size and rotation count every writer of this session uses. + + The plan's logs section carries them when the launcher derived them from + the budget; a plan from before they existed gets the defaults. + """ + + if self.plan.logs is not None and self.plan.logs.rotates: + return self.plan.logs.segment_bytes, self.plan.logs.rotations + return logs.MAXIMUM_SEGMENT_BYTES, logs.ROTATIONS + + def children(self, display_children: tuple[SupervisedChild, ...]) -> tuple[SupervisedChild, ...]: + """Every child to supervise, in start order. + + ``display_children`` first, as the prepared display gave them; then + the console, when the plan has one and the image can run it; then the + one foreground child, the surface or the job. Each runs as the capsule + user, and each gets its own log file, ``devcapsule-.log``, when + the plan says where the logs go. + """ + + console = self.console.child(self.plan, self.user.command) + infrastructure = display_children if console is None else (*display_children, console) + if self.job is None: + foreground = SupervisedChild( + name=self.plan.component.id, + command=self.user.command(self.launch.command), + foreground=True, + ) + else: + # Headless mode: the same distinguished slot with no GUI. The job runs + # in the project it was launched against, not the image's workdir. + foreground = SupervisedChild( + name=JOB_CHILD, + command=self.user.command(self.job), + foreground=True, + working_directory=self.plan.project_path, + ) + children = (*infrastructure, foreground) + directory = self.log_directory + if directory is None: + return children + return tuple(replace(child, log_path=str(logs.log_path(directory, child.name))) for child in children) diff --git a/devcapsule-src/tests/conftest.py b/devcapsule-src/tests/conftest.py index 32b168b2..100d6586 100644 --- a/devcapsule-src/tests/conftest.py +++ b/devcapsule-src/tests/conftest.py @@ -150,10 +150,6 @@ def private_user_directories(request: pytest.FixtureRequest, tmp_path: Path, mon return monkeypatch.delenv("DEVCAPSULE_CONFIG_HOME", raising=False) monkeypatch.delenv("DEVCAPSULE_DEV_WEBCONSOLE", raising=False) - monkeypatch.setattr( - "devcapsule.container_runtime.console.LAUNCHER_CONSOLE_SOURCE", - str(tmp_path / "user" / "absent-launcher-webconsole"), - ) # The build tools' caches are content-addressed and shared by the # developer's own builds: pex's under PEX_ROOT, and the scie launcher's # unpacked Python under SCIE_BASE. Moving them under the scratch made every diff --git a/devcapsule-src/tests/integration/test_console_decisions_cli.py b/devcapsule-src/tests/integration/test_console_decisions_cli.py index 9fd8121a..96232cf6 100644 --- a/devcapsule-src/tests/integration/test_console_decisions_cli.py +++ b/devcapsule-src/tests/integration/test_console_decisions_cli.py @@ -1,91 +1,80 @@ -"""Integration tests of ``devcapsule project checkout decisions`` against ``devcapsule_webconsole.decisions``.""" +"""Integration tests of ``devcapsule project checkout decisions``: the real command line, in a process whose environment the test builds. + +What the command does inside a capsule depends on two fixed paths of the +image, the console interpreter and the runtime plan, which a test cannot +build. ``tests/unit/devcapsule/test_console_tools.py`` covers those +decisions from values, and ``tests/e2e/test_console_answers.py`` runs the +command in a real capsule. +""" from __future__ import annotations +import os from pathlib import Path +import subprocess import sys import pytest -from devcapsule import cli, recursive_dogfood -from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime import console -from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan - pytestmark = pytest.mark.integration -CLI_PREFIX = ["project", "checkout", "decisions"] - -def runtime_plan_with_source(source: Path) -> RuntimePlan: - return RuntimePlan.for_component( - pycharm_runtime_template(), - project_path="/workspace/p", - home="/home/devcapsule", - identity=Identity(1000, 1000, "developer"), - ).with_console(ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token", source_path=str(source))) - - -@pytest.mark.parametrize("inside", [False, True]) +def checkout_decisions( + tmp_path: Path, *arguments: str, container_name: str | None, +) -> subprocess.CompletedProcess[str]: + """Run ``devcapsule project checkout decisions`` in a new process. + + The process gets a search path, a home and a DevCapsule configuration + home under ``tmp_path``, and ``DEVCAPSULE_CONTAINER_NAME`` only when + ``container_name`` is given; nothing of the caller's environment. + """ + environment = { + "PATH": os.defpath, + "HOME": str(tmp_path / "home"), + "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "config"), + } + if container_name is not None: + environment["DEVCAPSULE_CONTAINER_NAME"] = container_name + return subprocess.run( + [sys.executable, "-m", "devcapsule", "project", "checkout", "decisions", *arguments], + cwd=tmp_path, env=environment, capture_output=True, text=True, timeout=120, check=False, + ) + + +@pytest.mark.parametrize("container_name", [None, "capsule-fixture"], ids=["on a host", "in a capsule"]) @pytest.mark.parametrize("flag", ["-h", "--help"]) def test_wrapper_help_succeeds_without_running_console_interpreter( - tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch, inside: bool, flag: str, -) -> None: - """``devcapsule project checkout decisions -h/--help`` prints wrapper help on a base that has no console interpreter.""" - monkeypatch.setenv("DEVCAPSULE_CONTAINER_NAME", "capsule-fixture" if inside else "") - monkeypatch.setattr(console, "CONSOLE_PYTHON", str(tmp_path / "absent")) - monkeypatch.chdir(tmp_path) - - assert cli.main([*CLI_PREFIX, flag]) == 0 - output = capsys.readouterr() - assert "from-table, check or hand-off" in output.out - assert output.err == "" - - -@pytest.mark.parametrize( - ("arguments", "status", "expected"), - [ - ([], 2, "the following arguments are required: command"), - (["from-table", "--help"], 0, "--asked-by"), - (["check", "--help"], 0, "decision"), - (["hand-off", "--help"], 0, "--token-file"), - ], -) -def test_decisions_module_owns_empty_arguments_and_subcommand_help( - tmp_path: Path, - capfd: pytest.CaptureFixture[str], - monkeypatch: pytest.MonkeyPatch, - arguments: list[str], - status: int, - expected: str, + tmp_path: Path, container_name: str | None, flag: str, ) -> None: - """Inside a capsule, ``project checkout decisions`` leaves subcommand ``--help`` and empty-argument errors to ``devcapsule_webconsole.decisions``.""" - source = Path(__file__).resolve().parents[3] / "devcapsule-webconsole" - plan = tmp_path / "plan.json" - plan.write_text(runtime_plan_with_source(source).to_json(), encoding="utf-8") - monkeypatch.setenv("DEVCAPSULE_CONTAINER_NAME", "capsule-fixture") - monkeypatch.setattr(console, "CONSOLE_PYTHON", sys.executable) - monkeypatch.setattr(recursive_dogfood, "RUNTIME_PLAN_PATH", plan) - monkeypatch.chdir(tmp_path) + """``project checkout decisions -h/--help`` prints the wrapper's help and exits 0, on a host and in a capsule alike.""" + completed = checkout_decisions(tmp_path, flag, container_name=container_name) - result = cli.main([*CLI_PREFIX, *arguments]) + assert completed.returncode == 0 + assert "from-table, check or hand-off" in completed.stdout + assert completed.stderr == "" - assert result == status - output = capfd.readouterr() - assert "devcapsule-webconsole decisions" in output.out + output.err - assert expected in (output.err if status else output.out) - assert (output.out if status else output.err) == "" - -@pytest.mark.parametrize("arguments", [[], ["check", "x.json"]]) +@pytest.mark.parametrize("container_name", [None, ""], ids=["no variable", "empty variable"]) +@pytest.mark.parametrize("arguments", [(), ("check", "x.json")], ids=["no arguments", "check"]) def test_cli_reports_outside_capsule_refusal_with_usage_exit_code( - tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch, arguments: list[str], + tmp_path: Path, container_name: str | None, arguments: tuple[str, ...], ) -> None: - """Outside a capsule, ``cli.main`` prints the ``runs inside a capsule`` refusal on stderr and returns exit code 2.""" - monkeypatch.setenv("DEVCAPSULE_CONTAINER_NAME", "") - monkeypatch.chdir(tmp_path) - - assert cli.main([*CLI_PREFIX, *arguments]) == 2 - output = capsys.readouterr() - assert output.out == "" - assert "runs inside a capsule" in output.err + """Without a container name in the environment, the command prints the ``runs inside a capsule`` refusal on stderr and exits 2.""" + completed = checkout_decisions(tmp_path, *arguments, container_name=container_name) + + assert completed.returncode == 2 + assert completed.stdout == "" + assert "runs inside a capsule" in completed.stderr + + +def test_cli_does_not_give_the_hosts_refusal_inside_a_capsule(tmp_path: Path) -> None: + """With a container name in the environment, the command gets past the refusal that belongs to a host. + + What it does next depends on the image: without a console it names the + missing base, with one it runs the console's own ``check``. Either way + ``x.json`` is not checked, so it fails, and not with the host's words. + """ + completed = checkout_decisions(tmp_path, "check", "x.json", container_name="capsule-fixture") + + assert completed.returncode != 0 + assert "runs inside a capsule" not in completed.stderr diff --git a/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py new file mode 100644 index 00000000..2c369b27 --- /dev/null +++ b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py @@ -0,0 +1,196 @@ +"""Integration tests of the runtime entrypoint: real sessions, in a process whose environment the test builds. + +``run`` is the layer that reads the process and acts on the host. These +tests start it as the program it is, with a plan whose every path lies under +the test's directory and a stand-in program where the IDE or the job would +be, and observe what that program was given and what the session left. +""" + +from __future__ import annotations + +from dataclasses import dataclass +import json +import os +from pathlib import Path +import stat +import subprocess +import sys +from typing import Sequence + +import pytest + +pytestmark = pytest.mark.integration + +STAND_IN_STATUS = 7 +SLOTS = ("config", "system", "plugins", "log") + + +@dataclass(frozen=True) +class FinishedSession: + """One session that ran to its end: the entrypoint's process, and what the stand-in program saw.""" + + completed: subprocess.CompletedProcess[str] + arguments: list[str] + environment: dict[str, str] + directory: str + + +def stand_in_program(tmp_path: Path) -> Path: + """Write the program that stands where the IDE is installed, and return its path. + + It records its arguments, environment and working directory in + ``tmp_path / "report.json"``, prints one line, and exits + ``STAND_IN_STATUS``. ``-I`` keeps it away from the Python settings of + the environment it is started in. + """ + program = tmp_path / "ide" / "bin" / "ide.sh" + program.parent.mkdir(parents=True) + program.write_text( + f"#!{sys.executable} -I\n" + "import json, os, sys\n" + f"with open({str(tmp_path / 'report.json')!r}, 'w') as report:\n" + " json.dump({'arguments': sys.argv[1:], 'environ': dict(os.environ), 'cwd': os.getcwd()}, report)\n" + "print('stand-in output')\n" + f"sys.exit({STAND_IN_STATUS})\n", + encoding="utf-8", + ) + program.chmod(0o755) + return program + + +def write_plan(tmp_path: Path, logs: dict[str, object]) -> Path: + """Write a JetBrains runtime plan under ``tmp_path`` whose IDE is the stand-in program, and return its path. + + The capsule user of the plan is the user that runs the test, since only + root may prepare a session for another user. + """ + (tmp_path / "project").mkdir() + plan = tmp_path / "plan.json" + plan.write_text(json.dumps({ + "version": 1, + "project_path": str(tmp_path / "project"), + "home": str(tmp_path / "home"), + "identity": {"uid": os.getuid(), "gid": os.getgid(), "user": "developer"}, + "state_slots": [{"name": f"jetbrains/{name}", "path": str(tmp_path / "slots" / name)} for name in SLOTS], + "component": { + "id": "jetbrains", + "adapter": "jetbrains", + "configuration": { + "installation_path": str(tmp_path / "ide"), + "launcher": "bin/ide.sh", + "properties_path": str(tmp_path / "idea.properties"), + "properties_environment_variable": "PYCHARM_PROPERTIES", + "recover_stale_directory_lock": True, + "state_slot_mapping": {name: name for name in SLOTS}, + }, + }, + "logs": logs, + }), encoding="utf-8") + return plan + + +def run_entrypoint(tmp_path: Path, plan: Path, job: Sequence[str]) -> subprocess.CompletedProcess[str]: + """Start the entrypoint on ``plan``, headless when ``job`` is given, and wait for it. + + The process starts in ``tmp_path`` with a search path and one graphics + setting, and nothing else of the caller's environment. + """ + if os.getuid() == 0: + pytest.skip("root starts each child through gosu, which a test host need not have") + return subprocess.run( + [sys.executable, "-m", "devcapsule.container_runtime.entrypoint", str(plan), *(("--", *job) if job else ())], + cwd=tmp_path, + env={"PATH": os.defpath, "LIBGL_ALWAYS_SOFTWARE": "0"}, + capture_output=True, text=True, timeout=120, check=False, + ) + + +def finished(tmp_path: Path, completed: subprocess.CompletedProcess[str]) -> FinishedSession: + report = tmp_path / "report.json" + assert report.is_file(), f"the stand-in program did not run: {completed.stderr}" + seen = json.loads(report.read_text(encoding="utf-8")) + return FinishedSession(completed, seen["arguments"], seen["environ"], seen["cwd"]) + + +@pytest.fixture +def headless(tmp_path: Path) -> FinishedSession: + """A finished headless session: the stand-in program ran as the job, with the argument ``as-job``.""" + program = stand_in_program(tmp_path) + plan = write_plan(tmp_path, {"directory": str(tmp_path / "logs")}) + return finished(tmp_path, run_entrypoint(tmp_path, plan, [str(program), "as-job"])) + + +@pytest.fixture +def interactive(tmp_path: Path) -> FinishedSession: + """A finished interactive session: the stand-in program ran as the plan's IDE.""" + stand_in_program(tmp_path) + plan = write_plan(tmp_path, {"directory": str(tmp_path / "logs")}) + return finished(tmp_path, run_entrypoint(tmp_path, plan, [])) + + +def test_a_headless_sessions_exit_status_is_the_jobs(headless: FinishedSession) -> None: + """The entrypoint runs the job with the job's own arguments and exits with its status.""" + assert headless.arguments == ["as-job"] + assert headless.completed.returncode == STAND_IN_STATUS + + +def test_the_job_runs_in_the_project_with_the_sessions_environment(tmp_path: Path, headless: FinishedSession) -> None: + """The job starts in the plan's project and finds the session's home, runtime directory and properties variable in its environment.""" + assert headless.directory == str(tmp_path / "project") + assert headless.environment["HOME"] == str(tmp_path / "home") + assert headless.environment["XDG_RUNTIME_DIR"] == f"/tmp/devcapsule-runtime-{os.getuid()}" + assert headless.environment["PYCHARM_PROPERTIES"] == str(tmp_path / "idea.properties") + + +def test_the_job_gets_the_graphics_defaults_and_keeps_the_setting_the_process_had(headless: FinishedSession) -> None: + """The job's environment has the default the process lacked and the graphics setting the process started with.""" + assert headless.environment["NO_AT_BRIDGE"] == "1" + assert headless.environment["LIBGL_ALWAYS_SOFTWARE"] == "0" + + +def test_the_session_prepares_its_directories_and_the_surfaces_properties_file( + tmp_path: Path, headless: FinishedSession, +) -> None: + """After the session, the home with a private ``.ssh``, every state slot and the IDE's properties file exist.""" + assert stat.S_IMODE((tmp_path / "home" / ".ssh").stat().st_mode) == 0o700 + assert all((tmp_path / "slots" / name).is_dir() for name in SLOTS) + properties = (tmp_path / "idea.properties").read_text(encoding="utf-8") + assert properties.startswith(f"idea.config.path={tmp_path / 'slots' / 'config'}\n") + + +def test_the_session_logs_the_supervisor_and_the_job_where_the_plan_says( + tmp_path: Path, headless: FinishedSession, +) -> None: + """With a logs directory in the plan, the supervisor's log exists there and the job's log holds the job's output.""" + assert (tmp_path / "logs" / "devcapsule-supervisor.log").is_file() + assert "stand-in output" in (tmp_path / "logs" / "devcapsule-job.log").read_text(encoding="utf-8") + + +def test_a_childs_log_rotates_at_the_segment_size_of_the_plan(tmp_path: Path) -> None: + """With a 4 KiB segment in the plan, a job that prints 20 KiB leaves a first rotated segment beside its live log.""" + plan = write_plan(tmp_path, {"directory": str(tmp_path / "logs"), "segment_bytes": 4096, "rotations": 2}) + lines = "import sys\nfor _ in range(200):\n print('x' * 100)\n sys.stdout.flush()\n" + + completed = run_entrypoint(tmp_path, plan, [sys.executable, "-I", "-c", lines]) + + assert completed.returncode == 0, completed.stderr + assert (tmp_path / "logs" / "devcapsule-job.log.1.gz").is_file() + + +def test_an_interactive_session_starts_the_surface_on_the_project(tmp_path: Path, interactive: FinishedSession) -> None: + """Without a job, the entrypoint starts the plan's IDE with the project as its argument, tells it its properties file, and exits with its status.""" + assert interactive.arguments == [str(tmp_path / "project")] + assert interactive.environment["PYCHARM_PROPERTIES"] == str(tmp_path / "idea.properties") + assert interactive.completed.returncode == STAND_IN_STATUS + assert "stand-in output" in (tmp_path / "logs" / "devcapsule-jetbrains.log").read_text(encoding="utf-8") + + +def test_an_interactive_jetbrains_session_takes_the_profile_lock(tmp_path: Path, interactive: FinishedSession) -> None: + """For a JetBrains surface that asks for stale-lock recovery, the session leaves its lock file in the config and the system slot.""" + assert (tmp_path / "slots" / "config" / ".devcapsule-session.lock").is_file() + assert (tmp_path / "slots" / "system" / ".devcapsule-session.lock").is_file() + + +def test_a_headless_session_takes_no_profile_lock(tmp_path: Path, headless: FinishedSession) -> None: + """With a job in place of the IDE, the session leaves no lock file in the profile.""" + assert not (tmp_path / "slots" / "config" / ".devcapsule-session.lock").exists() diff --git a/devcapsule-src/tests/integration/test_version_cli.py b/devcapsule-src/tests/integration/test_version_cli.py new file mode 100644 index 00000000..b0b7d7fc --- /dev/null +++ b/devcapsule-src/tests/integration/test_version_cli.py @@ -0,0 +1,45 @@ +"""Integration tests of ``devcapsule version``: the real command line, in a process whose environment the test builds.""" + +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +import pytest + +from devcapsule.build_info import build_info_json, build_info_text, current_build_info + +pytestmark = pytest.mark.integration + + +def version(tmp_path: Path, *arguments: str) -> subprocess.CompletedProcess[str]: + """Run ``devcapsule version`` in a new process with a search path, a home and a configuration home under ``tmp_path``.""" + environment = { + "PATH": os.defpath, + "HOME": str(tmp_path / "home"), + "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "config"), + } + return subprocess.run( + [sys.executable, "-m", "devcapsule", "version", *arguments], + cwd=tmp_path, env=environment, capture_output=True, text=True, timeout=120, check=False, + ) + + +def test_version_json_prints_the_build_info_of_the_distribution_it_runs_from(tmp_path: Path) -> None: + """``version --json`` prints, as one JSON line, the build information of the distribution this test imports too.""" + completed = version(tmp_path, "--json") + + assert completed.returncode == 0 + assert completed.stdout == build_info_json(current_build_info()) + "\n" + assert completed.stderr == "" + + +def test_version_prints_the_build_info_as_text_without_the_flag(tmp_path: Path) -> None: + """``version`` prints the same build information as the four lines a person reads.""" + completed = version(tmp_path) + + assert completed.returncode == 0 + assert completed.stdout == build_info_text(current_build_info()) + "\n" + assert completed.stderr == "" diff --git a/devcapsule-src/tests/test_contained_display.py b/devcapsule-src/tests/test_contained_display.py index c5da8d1d..64be82b6 100644 --- a/devcapsule-src/tests/test_contained_display.py +++ b/devcapsule-src/tests/test_contained_display.py @@ -24,12 +24,71 @@ x_socket_path, ) from devcapsule.container_runtime.entrypoint import run - -from tests.test_runtime_entrypoint import SupervisorCapture, captured_supervisor, runtime_document +from devcapsule.container_runtime.supervisor import SupervisedChild pytestmark = pytest.mark.legacy -_ = captured_supervisor # re-exported fixture + +# The three helpers below came with ``tests/test_runtime_entrypoint.py``, which +# was refurbished into the mirror; this file is their last user. + + +def runtime_document(tmp_path: Path) -> dict[str, object]: + return { + "version": 1, + "project_path": "/workspace/project", + "home": str(tmp_path / "home"), + "identity": {"uid": 1000, "gid": 1001, "user": "developer"}, + "state_slots": [ + {"name": "jetbrains/config", "path": str(tmp_path / "config")}, + {"name": "jetbrains/system", "path": str(tmp_path / "system")}, + {"name": "jetbrains/plugins", "path": str(tmp_path / "plugins")}, + {"name": "jetbrains/log", "path": str(tmp_path / "log")}, + ], + "component": { + "id": "jetbrains", + "adapter": "jetbrains", + "configuration": { + "installation_path": "/opt/jetbrains/pycharm", + "launcher": "bin/pycharm.sh", + "properties_path": str(tmp_path / "idea.properties"), + "properties_environment_variable": "PYCHARM_PROPERTIES", + "state_slot_mapping": { + "config": "config", + "system": "system", + "plugins": "plugins", + "log": "log", + }, + }, + }, + } + + +class SupervisorCapture: + """Stands in for the Supervisor to observe what the entrypoint declares.""" + + instances: list["SupervisorCapture"] = [] + + def __init__( + self, children: tuple[SupervisedChild, ...], *, log_owner: tuple[int, int] | None = None, + segment_bytes: int = 10 * 1024 * 1024, rotations: int = 4, + ) -> None: + self.children = children + self.log_owner = log_owner + self.segment_bytes = segment_bytes + self.rotations = rotations + SupervisorCapture.instances.append(self) + + def run(self) -> int: + return 42 + + +@pytest.fixture() +def captured_supervisor(monkeypatch: pytest.MonkeyPatch) -> type[SupervisorCapture]: + SupervisorCapture.instances = [] + monkeypatch.setattr("devcapsule.container_runtime.entrypoint.Supervisor", SupervisorCapture) + monkeypatch.setattr("devcapsule.container_runtime.entrypoint.os.geteuid", lambda: 1000) + return SupervisorCapture def contained_document(tmp_path: Path, token: str = "a1b2c3") -> dict[str, object]: diff --git a/devcapsule-src/tests/test_runtime_entrypoint.py b/devcapsule-src/tests/test_runtime_entrypoint.py deleted file mode 100644 index e2d65abd..00000000 --- a/devcapsule-src/tests/test_runtime_entrypoint.py +++ /dev/null @@ -1,444 +0,0 @@ -from __future__ import annotations - -import json -import logging -import os -from pathlib import Path - -import pytest - -from devcapsule.container_runtime.components.jetbrains import plan as plan_jetbrains -from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime.contract import ( - ComponentRuntimeTemplate, - Identity, - RuntimePlan, - RuntimePlanError, -) -from devcapsule.container_runtime.entrypoint import main, run -from devcapsule.container_runtime.filesystem import FilesystemPlan, plan_filesystem, prepare_filesystem -from devcapsule.container_runtime.graphics import environment as graphics_environment -from devcapsule.container_runtime.identity import foreground_command -from devcapsule.container_runtime.supervisor import SupervisedChild - -pytestmark = pytest.mark.legacy - - -def runtime_document(tmp_path: Path) -> dict[str, object]: - return { - "version": 1, - "project_path": "/workspace/project", - "home": str(tmp_path / "home"), - "identity": {"uid": 1000, "gid": 1001, "user": "developer"}, - "state_slots": [ - {"name": "jetbrains/config", "path": str(tmp_path / "config")}, - {"name": "jetbrains/system", "path": str(tmp_path / "system")}, - {"name": "jetbrains/plugins", "path": str(tmp_path / "plugins")}, - {"name": "jetbrains/log", "path": str(tmp_path / "log")}, - ], - "component": { - "id": "jetbrains", - "adapter": "jetbrains", - "configuration": { - "installation_path": "/opt/jetbrains/pycharm", - "launcher": "bin/pycharm.sh", - "properties_path": str(tmp_path / "idea.properties"), - "properties_environment_variable": "PYCHARM_PROPERTIES", - "state_slot_mapping": { - "config": "config", - "system": "system", - "plugins": "plugins", - "log": "log", - }, - }, - }, - } - - -def test_contract_parses_versioned_runtime_plan(tmp_path: Path) -> None: - plan = RuntimePlan.from_json(json.dumps(runtime_document(tmp_path))) - assert plan.identity.uid == 1000 - assert plan.component.adapter == "jetbrains" - assert plan.slots_by_name()["jetbrains/config"] == str(tmp_path / "config") - - -def test_component_declares_persistence_and_generates_generic_runtime_plan() -> None: - template = ComponentRuntimeTemplate.from_json(json.dumps(pycharm_runtime_template().to_mapping())) - assert template.persistence.home == "required" - assert template.persistence.xdg == "home-relative" - assert template.persistence.state_slots[0].kind == "durable" - assert template.logical_slot_name("config") == "pycharm/config" - - runtime = RuntimePlan.for_component( - template, - project_path="/workspace/project", - home="/home/devcapsule", - identity=Identity(1000, 1000), - ) - assert runtime.slots_by_name()["pycharm/config"] == "/ide-config" - assert runtime.slots_by_name()["pycharm/cache"] == "/home/devcapsule/.cache" - - -def test_home_only_component_needs_no_runtime_special_case() -> None: - template = ComponentRuntimeTemplate.from_mapping( - { - "version": 1, - "component": { - "id": "home-tool", - "adapter": "fixture", - "configuration": {}, - "persistence": { - "home": "required", - "xdg": "home-relative", - "state_slots": [], - }, - }, - } - ) - runtime = RuntimePlan.for_component( - template, - project_path="/workspace/project", - home="/home/devcapsule", - identity=Identity(1000, 1000), - ) - assert runtime.state_slots == () - - -@pytest.mark.parametrize( - ("change", "message"), - [ - (lambda doc: doc.update(version=2), "unsupported runtime plan version"), - (lambda doc: doc.update(identity={"uid": True, "gid": 1}), "identity.uid"), - (lambda doc: doc.update(state_slots=[{"name": "same", "path": "/a"}, {"name": "same", "path": "/b"}]), "duplicate state slot"), - (lambda doc: doc["component"].update(id="Tool/unsafe"), "component.id"), # type: ignore[index] - ], -) -def test_contract_rejects_invalid_input(tmp_path: Path, change: object, message: str) -> None: - document = runtime_document(tmp_path) - change(document) # type: ignore[operator] - with pytest.raises(RuntimePlanError, match=message): - RuntimePlan.from_mapping(document) - - -def test_component_contract_requires_explicit_home_overlay() -> None: - document = pycharm_runtime_template().to_mapping() - persistence = document["component"]["persistence"] # type: ignore[index] - cache = persistence["state_slots"][-1] # type: ignore[index] - cache.pop("home_overlay") - with pytest.raises(RuntimePlanError, match="must declare home_overlay"): - ComponentRuntimeTemplate.from_mapping(document) - - -def test_generic_filesystem_plan_uses_persistent_home_and_declared_slots(tmp_path: Path) -> None: - plan = plan_filesystem(RuntimePlan.from_mapping(runtime_document(tmp_path))) - assert plan.environment["XDG_CONFIG_HOME"] == str(tmp_path / "home" / ".config") - assert str(tmp_path / "plugins") in plan.directories - assert plan.environment["XDG_RUNTIME_DIR"] == "/tmp/devcapsule-runtime-1000" - - -def test_filesystem_assigns_only_new_directories_when_root( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch -) -> None: - existing = tmp_path / "existing" - existing.mkdir() - new = existing / "new" - changed: list[tuple[Path, int, int]] = [] - monkeypatch.setattr("devcapsule.container_runtime.filesystem.os.geteuid", lambda: 0) - monkeypatch.setattr( - "devcapsule.container_runtime.filesystem.os.chown", - lambda path, uid, gid: changed.append((Path(path), uid, gid)), - ) - prepare_filesystem( - FilesystemPlan( - (str(existing), str(existing / ".ssh"), str(new)), - {"HOME": str(existing), "XDG_RUNTIME_DIR": str(new)}, - ), - RuntimePlan.from_mapping(runtime_document(tmp_path)).identity, - ) - assert changed == [(existing / ".ssh", 1000, 1001), (new, 1000, 1001)] - - -def test_jetbrains_adapter_generates_properties_and_foreground_command(tmp_path: Path) -> None: - launch = plan_jetbrains(RuntimePlan.from_mapping(runtime_document(tmp_path))) - assert launch.command == ("/opt/jetbrains/pycharm/bin/pycharm.sh", "/workspace/project") - assert launch.properties_environment_variable == "PYCHARM_PROPERTIES" - assert f"idea.plugins.path={tmp_path / 'plugins'}\n" in launch.properties - - -def test_pycharm_component_disables_jcef_sandbox_before_startup() -> None: - runtime = RuntimePlan.for_component( - pycharm_runtime_template(), - project_path="/workspace/project", - home="/home/devcapsule", - identity=Identity(1000, 1000), - ) - launch = plan_jetbrains(runtime) - - assert "ide.browser.jcef.sandbox.enable=false\n" in launch.properties - assert runtime.component.environment == { - "JAVA_TOOL_OPTIONS": "-Dide.browser.jcef.sandbox.enable=false" - } - - -def test_jetbrains_adapter_requires_declared_slot(tmp_path: Path) -> None: - document = runtime_document(tmp_path) - configuration = document["component"]["configuration"] # type: ignore[index] - configuration["state_slot_mapping"]["log"] = "missing" # type: ignore[index] - with pytest.raises(RuntimePlanError, match="log mapping"): - plan_jetbrains(RuntimePlan.from_mapping(document)) - - -def test_graphics_preserves_explicit_environment() -> None: - assert graphics_environment({"LIBGL_ALWAYS_SOFTWARE": "0"})["LIBGL_ALWAYS_SOFTWARE"] == "0" - - -def test_identity_adds_gosu_only_when_root(monkeypatch: pytest.MonkeyPatch) -> None: - plan = RuntimePlan.from_mapping(runtime_document(Path("/tmp/test"))) - monkeypatch.setattr("devcapsule.container_runtime.identity.os.geteuid", lambda: 0) - assert foreground_command(("ide",), plan.identity) == ("gosu", "1000:1001", "ide") - monkeypatch.setattr("devcapsule.container_runtime.identity.os.geteuid", lambda: 1000) - assert foreground_command(("ide",), plan.identity) == ("ide",) - - -class SupervisorCapture: - """Stands in for the Supervisor to observe what the entrypoint declares.""" - - instances: list["SupervisorCapture"] = [] - - def __init__( - self, children: tuple[SupervisedChild, ...], *, log_owner: tuple[int, int] | None = None, - segment_bytes: int = 10 * 1024 * 1024, rotations: int = 4, - ) -> None: - self.children = children - self.log_owner = log_owner - self.segment_bytes = segment_bytes - self.rotations = rotations - SupervisorCapture.instances.append(self) - - def run(self) -> int: - return 42 - - -@pytest.fixture() -def captured_supervisor(monkeypatch: pytest.MonkeyPatch) -> type[SupervisorCapture]: - SupervisorCapture.instances = [] - monkeypatch.setattr("devcapsule.container_runtime.entrypoint.Supervisor", SupervisorCapture) - monkeypatch.setattr("devcapsule.container_runtime.identity.os.geteuid", lambda: 1000) - return SupervisorCapture - - -def test_entrypoint_prepares_properties_and_supervises_foreground( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, captured_supervisor: type[SupervisorCapture] -) -> None: - document = runtime_document(tmp_path) - document["ancillary_components"] = [ - { - "id": "codex", - "adapter": "ancillary", - "configuration": {}, - "environment": {"CODEX_HOME": str(tmp_path / "codex-home")}, - } - ] - runtime = RuntimePlan.from_mapping(document) - - assert run(runtime) == 42 - - properties_path = tmp_path / "idea.properties" - assert properties_path.read_text(encoding="utf-8").startswith( - f"idea.config.path={tmp_path / 'config'}\n" - ) - (supervisor,) = captured_supervisor.instances - (child,) = supervisor.children - assert child.name == "jetbrains" - assert child.foreground is True - assert child.command == ("/opt/jetbrains/pycharm/bin/pycharm.sh", "/workspace/project") - assert os.environ["PYCHARM_PROPERTIES"] == str(properties_path) - assert os.environ["CODEX_HOME"] == str(tmp_path / "codex-home") - - -def test_entrypoint_dispatches_vscode_adapter_components( - tmp_path: Path, captured_supervisor: type[SupervisorCapture] -) -> None: - runtime = RuntimePlan.from_mapping( - { - "version": 1, - "project_path": "/workspace/project", - "home": str(tmp_path / "home"), - "identity": {"uid": 1000, "gid": 1001, "user": "developer"}, - "state_slots": [ - {"name": "codium/user-data", "path": str(tmp_path / "user-data")}, - {"name": "codium/extensions", "path": str(tmp_path / "extensions")}, - ], - "component": { - "id": "codium", - "adapter": "vscode", - "configuration": { - "installation_path": "/opt/codium", - "launcher": "codium", - "additional_arguments": ["--no-sandbox"], - "state_slot_mapping": { - "user-data": "user-data", - "extensions": "extensions", - }, - }, - }, - } - ) - - assert run(runtime) == 42 - - (supervisor,) = captured_supervisor.instances - (child,) = supervisor.children - assert child.name == "codium" - assert child.foreground is True - assert child.command == ( - "/opt/codium/codium", - f"--user-data-dir={tmp_path / 'user-data'}", - f"--extensions-dir={tmp_path / 'extensions'}", - "--no-sandbox", - "/workspace/project", - ) - - -def test_entrypoint_rejects_unknown_adapters(tmp_path: Path) -> None: - document = runtime_document(tmp_path) - document["component"]["adapter"] = "fixture" # type: ignore[index] - - with pytest.raises(RuntimePlanError, match="unsupported component adapter"): - run(RuntimePlan.from_mapping(document)) - - -def test_entrypoint_headless_job_takes_the_foreground_slot( - tmp_path: Path, captured_supervisor: type[SupervisorCapture] -) -> None: - runtime = RuntimePlan.from_mapping(runtime_document(tmp_path)) - - assert run(runtime, job=("pytest", "-q")) == 42 - - (supervisor,) = captured_supervisor.instances - (child,) = supervisor.children - assert child.name == "job" - assert child.foreground is True - assert child.command == ("pytest", "-q") - assert child.working_directory == "/workspace/project" - # Headless preparation is the same as interactive minus the GUI child. - assert (tmp_path / "idea.properties").is_file() - - -def test_entrypoint_main_accepts_forwarded_arguments(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: - assert main(["--help"]) == 0 - assert "usage: devcapsule runtime RUNTIME_PLAN.json" in capsys.readouterr().out - - assert main([]) == 2 - assert "usage: devcapsule runtime RUNTIME_PLAN.json" in capsys.readouterr().err - - assert main([str(tmp_path / "missing.json")]) == 2 - assert "cannot read runtime plan" in capsys.readouterr().err - - assert main([str(tmp_path / "missing.json"), "--", "true"]) == 2 - assert "cannot read runtime plan" in capsys.readouterr().err - - assert main([str(tmp_path / "missing.json"), "--"]) == 2 - assert "usage: devcapsule runtime RUNTIME_PLAN.json" in capsys.readouterr().err - - -def test_contract_round_trips_the_logs_section(tmp_path: Path) -> None: - from devcapsule.container_runtime.contract import LogsPlan - - document = runtime_document(tmp_path) - document["logs"] = {"directory": "/var/log/devcapsule"} - plan = RuntimePlan.from_mapping(document) - assert plan.logs == LogsPlan("/var/log/devcapsule") - assert plan.to_mapping()["logs"] == {"directory": "/var/log/devcapsule"} - assert RuntimePlan.from_mapping(plan.to_mapping()) == plan - assert RuntimePlan.from_mapping(runtime_document(tmp_path)).logs is None - assert "logs" not in RuntimePlan.from_mapping(runtime_document(tmp_path)).to_mapping() - assert RuntimePlan.from_mapping({**document, "logs": None}).logs is None - assert plan.with_logs(LogsPlan("/elsewhere")).logs == LogsPlan("/elsewhere") - - -@pytest.mark.parametrize("logs_value, message", [ - ("text", "logs must be an object"), - ({"directory": "/var/log/devcapsule", "extra": 1}, "logs must not carry extra"), - ({"directory": "relative"}, "logs.directory must be an absolute normalized container path"), - ({"directory": "/var/../log"}, "logs.directory must be an absolute normalized container path"), - ({}, "logs.directory must be"), -]) -def test_contract_rejects_malformed_logs(tmp_path: Path, logs_value: object, message: str) -> None: - with pytest.raises(RuntimePlanError, match=message): - RuntimePlan.from_mapping({**runtime_document(tmp_path), "logs": logs_value}) - - -def test_entrypoint_gives_every_child_its_own_log_file_when_the_plan_says_where( - tmp_path: Path, captured_supervisor: type[SupervisorCapture] -) -> None: - from devcapsule import logs - - document = runtime_document(tmp_path) - document["logs"] = {"directory": str(tmp_path / "logs")} - try: - assert run(RuntimePlan.from_mapping(document)) == 42 - (supervisor,) = captured_supervisor.instances - assert [child.log_path for child in supervisor.children] == [str(tmp_path / "logs" / "devcapsule-jetbrains.log")] - assert supervisor.log_owner == (1000, 1001) - assert (tmp_path / "logs" / "devcapsule-supervisor.log").is_file() - assert run(RuntimePlan.from_mapping(document), job=("pytest",)) == 42 - assert [child.log_path for child in captured_supervisor.instances[-1].children] == [str(tmp_path / "logs" / "devcapsule-job.log")] - - captured_supervisor.instances.clear() - assert run(RuntimePlan.from_mapping(runtime_document(tmp_path))) == 42 - (plain,) = captured_supervisor.instances - assert [child.log_path for child in plain.children] == [None] - assert plain.log_owner == (1000, 1001) - finally: - logs.reset() - - -def test_contract_carries_the_rotation_both_or_neither(tmp_path: Path) -> None: - from devcapsule.container_runtime.contract import LogsPlan - - document = runtime_document(tmp_path) - document["logs"] = {"directory": "/var/log/devcapsule", "segment_bytes": 8388608, "rotations": 4} - plan = RuntimePlan.from_mapping(document) - assert plan.logs == LogsPlan("/var/log/devcapsule", 8388608, 4) and plan.logs.rotates - assert plan.to_mapping()["logs"] == document["logs"] - assert RuntimePlan.from_mapping(plan.to_mapping()) == plan - assert not LogsPlan("/var/log/devcapsule").rotates - assert LogsPlan.from_mapping({"directory": "/var/log/devcapsule", "segment_bytes": 0, "rotations": 0}, "logs") == LogsPlan("/var/log/devcapsule") - for logs_value, message in ( - ({"directory": "/var/log/devcapsule", "segment_bytes": 0}, "go together"), - ({"directory": "/var/log/devcapsule", "rotations": 0}, "go together"), - ({"directory": "/var/log/devcapsule", "segment_bytes": 1}, "go together"), - ({"directory": "/var/log/devcapsule", "rotations": 1}, "go together"), - ({"directory": "/var/log/devcapsule", "segment_bytes": -1, "rotations": 1}, "segment_bytes must be a non-negative integer"), - ({"directory": "/var/log/devcapsule", "segment_bytes": 1, "rotations": True}, "rotations must be a non-negative integer"), - ({"directory": "/var/log/devcapsule", "segment_bytes": "8M", "rotations": 1}, "segment_bytes must be a non-negative integer"), - ): - with pytest.raises(RuntimePlanError, match=message): - RuntimePlan.from_mapping({**runtime_document(tmp_path), "logs": logs_value}) - - -def test_entrypoint_passes_the_plans_rotation_to_every_writer_and_defaults_without_it( - tmp_path: Path, captured_supervisor: type[SupervisorCapture] -) -> None: - from devcapsule import logs - from devcapsule.container_runtime.entrypoint import log_rotation - - document = runtime_document(tmp_path) - document["logs"] = {"directory": str(tmp_path / "logs"), "segment_bytes": 2048, "rotations": 3} - try: - assert run(RuntimePlan.from_mapping(document)) == 42 - supervisor = captured_supervisor.instances[-1] - assert [child.name for child in supervisor.children] == ["jetbrains"] - assert (supervisor.segment_bytes, supervisor.rotations) == (2048, 3) - handler = next(h for h in logging.getLogger().handlers if isinstance(h, logs._SessionFileHandler)) - assert handler._file is not None and handler._file.path == tmp_path / "logs" / "devcapsule-supervisor.log" - assert (handler._file._segment, handler._file._rotations) == (2048, 3) - - document["logs"] = {"directory": str(tmp_path / "plain")} - assert run(RuntimePlan.from_mapping(document)) == 42 - supervisor = captured_supervisor.instances[-1] - assert (supervisor.segment_bytes, supervisor.rotations) == (logs.MAXIMUM_SEGMENT_BYTES, logs.ROTATIONS) - assert log_rotation(RuntimePlan.from_mapping(runtime_document(tmp_path))) == (logs.MAXIMUM_SEGMENT_BYTES, logs.ROTATIONS) - finally: - logs.reset() diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_version.py b/devcapsule-src/tests/unit/devcapsule/commands/test_version.py deleted file mode 100644 index a1e1e971..00000000 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_version.py +++ /dev/null @@ -1,53 +0,0 @@ -"""Unit tests of ``devcapsule/commands/version.py``: JSON and human-readable build identity output.""" - -from __future__ import annotations - -import json - -import pytest - -from devcapsule.build_info import BuildInfo -from devcapsule.commands import version -from devcapsule.commands.version import VersionCommand - - -SAMPLE_BUILD = BuildInfo( - schema_version=2, - version="1.2.3", - source_repository="https://github.com/example/devcapsule", - source_revision="d" * 40, - source_url=f"https://github.com/example/devcapsule/commit/{'d' * 40}", - build_mnemonic="v1.2.3", -) - - -@pytest.fixture -def running_sample_build(monkeypatch: pytest.MonkeyPatch) -> None: - """Make ``SAMPLE_BUILD`` the build the command finds itself running.""" - monkeypatch.setattr(version, "current_build_info", lambda: SAMPLE_BUILD) - - -def test_version_json_emits_machine_readable_build_info( - capsys: pytest.CaptureFixture[str], running_sample_build: None, -) -> None: - """``version --json`` prints the running build's ``BuildInfo`` mapping as JSON on stdout and returns 0.""" - status = VersionCommand.invoke("devcapsule version", ["--json"]) - - assert status == 0 - assert json.loads(capsys.readouterr().out) == SAMPLE_BUILD.to_mapping() - - -def test_version_text_prints_mnemonic_package_version_and_source_identity( - capsys: pytest.CaptureFixture[str], running_sample_build: None, -) -> None: - """``version`` without ``--json`` prints the running build's mnemonic, package version, repository, revision, and URL.""" - status = VersionCommand.invoke("devcapsule version", []) - - assert status == 0 - lines = capsys.readouterr().out.splitlines() - assert lines == [ - "DevCapsule v1.2.3 (package 1.2.3)", - "Source repository: https://github.com/example/devcapsule", - f"Source revision: {'d' * 40}", - f"Source URL: https://github.com/example/devcapsule/commit/{'d' * 40}", - ] diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/components/__init__.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/components/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/components/test_jetbrains.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/components/test_jetbrains.py new file mode 100644 index 00000000..0ae52dd3 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/components/test_jetbrains.py @@ -0,0 +1,92 @@ +"""Unit tests of ``devcapsule/container_runtime/components/jetbrains.py``: the properties and the command of a JetBrains launch.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule.container_runtime.components.jetbrains import plan +from devcapsule.container_runtime.contract import RuntimePlan, RuntimePlanError + + +def runtime_document(tmp_path: Path) -> dict[str, object]: + """A runtime plan document for a JetBrains component whose four state slots lie under ``tmp_path``.""" + return { + "version": 1, + "project_path": "/workspace/project", + "home": str(tmp_path / "home"), + "identity": {"uid": 1000, "gid": 1001, "user": "developer"}, + "state_slots": [ + {"name": "jetbrains/config", "path": str(tmp_path / "config")}, + {"name": "jetbrains/system", "path": str(tmp_path / "system")}, + {"name": "jetbrains/plugins", "path": str(tmp_path / "plugins")}, + {"name": "jetbrains/log", "path": str(tmp_path / "log")}, + ], + "component": { + "id": "jetbrains", + "adapter": "jetbrains", + "configuration": { + "installation_path": "/opt/jetbrains/pycharm", + "launcher": "bin/pycharm.sh", + "properties_path": str(tmp_path / "idea.properties"), + "properties_environment_variable": "PYCHARM_PROPERTIES", + "state_slot_mapping": { + "config": "config", + "system": "system", + "plugins": "plugins", + "log": "log", + }, + }, + }, + } + + +def configuration_of(document: dict[str, object]) -> dict[str, object]: + component = document["component"] + assert isinstance(component, dict) + configuration = component["configuration"] + assert isinstance(configuration, dict) + return configuration + + +def test_plan_points_the_ide_at_its_state_slots_and_starts_it_on_the_project(tmp_path: Path) -> None: + """``plan`` writes one ``idea..path`` property per mapped slot, names the properties file and its variable, and runs the launcher on the project.""" + launch = plan(RuntimePlan.from_mapping(runtime_document(tmp_path))) + + assert launch.command == ("/opt/jetbrains/pycharm/bin/pycharm.sh", "/workspace/project") + assert launch.properties_path == str(tmp_path / "idea.properties") + assert launch.properties_environment_variable == "PYCHARM_PROPERTIES" + assert launch.properties.splitlines() == [ + f"idea.config.path={tmp_path / 'config'}", + f"idea.system.path={tmp_path / 'system'}", + f"idea.plugins.path={tmp_path / 'plugins'}", + f"idea.log.path={tmp_path / 'log'}", + ] + + +def test_plan_appends_the_components_additional_properties(tmp_path: Path) -> None: + """Each additional property of the configuration follows the four managed paths as ``name=value``, in name order.""" + document = runtime_document(tmp_path) + configuration_of(document)["additional_properties"] = { + "ide.no.platform.update": "true", + "ide.browser.jcef.sandbox.enable": "false", + } + + launch = plan(RuntimePlan.from_mapping(document)) + + assert launch.properties.splitlines()[4:] == [ + "ide.browser.jcef.sandbox.enable=false", + "ide.no.platform.update=true", + ] + + +def test_plan_refuses_a_mapping_to_a_slot_the_plan_does_not_declare(tmp_path: Path) -> None: + """A ``state_slot_mapping`` entry that names no declared state slot raises ``RuntimePlanError`` naming the mapping.""" + document = runtime_document(tmp_path) + mapping = configuration_of(document)["state_slot_mapping"] + assert isinstance(mapping, dict) + mapping["log"] = "missing" + + with pytest.raises(RuntimePlanError, match="log mapping"): + plan(RuntimePlan.from_mapping(document)) diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py index 5383830f..e6e11f2a 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py @@ -1,4 +1,4 @@ -"""Unit tests of ``devcapsule/container_runtime/console.py``: package precedence and supervised child construction.""" +"""Unit tests of ``devcapsule/container_runtime/console.py``: package precedence, the supervised child and its readiness probe.""" from __future__ import annotations @@ -8,7 +8,6 @@ import pytest from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime import console from devcapsule.container_runtime.console import ( CONSOLE_CHILD, CONSOLE_PYTHON, @@ -16,8 +15,8 @@ CONSOLE_ROOT, LAUNCHER_CONSOLE_SOURCE, RUNTIME_CLI, - console_child, - console_package_path, + ConsoleInstallation, + probe_address, ) from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan from devcapsule.images.tooling import WEBCONSOLE_ROOT, WEBCONSOLE_VENV_PYTHON @@ -37,32 +36,23 @@ def runtime_plan(tmp_path: Path, *, console: ConsolePlan | None) -> RuntimePlan: return plan if console is None else plan.with_console(console) -def launcher_bundle(path: Path) -> Path: - pkg = path / "devcapsule_webconsole" - pkg.mkdir(parents=True) - (pkg / "__init__.py").write_text("", encoding="utf-8") - return path +def base_installation(tmp_path: Path) -> ConsoleInstallation: + """An installation as a base image alone provides it: an interpreter file, and no launcher package. - -@pytest.fixture -def base_python(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: - """Set the image paths to an empty interpreter file and an absent package. - - Child construction only checks that the interpreter file exists; these - tests never execute it. + The interpreter is an empty file. ``child`` only checks that it exists; + no test here executes it. """ python = tmp_path / "base-python" python.touch() - monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) - monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) - return python + return ConsoleInstallation(python, tmp_path / "launcher-webconsole") -def install_launcher_package(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: - """Put the launcher's console package at ``LAUNCHER_CONSOLE_SOURCE``, as materialization does, and return its directory.""" - bundled = launcher_bundle(tmp_path / "launcher-webconsole") - monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(bundled)) - return bundled +def with_launcher_package(installation: ConsoleInstallation) -> ConsoleInstallation: + """Put the console package at the installation's launcher source, as materialization does.""" + package = installation.launcher_source / "devcapsule_webconsole" + package.mkdir(parents=True) + (package / "__init__.py").write_text("", encoding="utf-8") + return installation def test_runtime_and_base_recipe_agree_on_console_paths() -> None: @@ -73,35 +63,38 @@ def test_runtime_and_base_recipe_agree_on_console_paths() -> None: assert RUNTIME_CLI == ENTRYPOINT_CONTRACT[0] -def test_console_package_path_prefers_the_plans_checkout_source(tmp_path: Path) -> None: +def test_of_image_names_the_images_interpreter_and_launcher_package() -> None: + """``ConsoleInstallation.of_image`` is the installation at ``CONSOLE_PYTHON`` and ``LAUNCHER_CONSOLE_SOURCE``.""" + assert ConsoleInstallation.of_image() == ConsoleInstallation( + Path("/opt/devcapsule-webconsole/venv/bin/python"), Path("/opt/devcapsule/webconsole"), + ) + + +def test_package_path_prefers_the_plans_checkout_source(tmp_path: Path) -> None: """A non-empty ``console.source_path`` wins over an installed launcher package.""" - bundled = launcher_bundle(tmp_path / "launcher-webconsole") + installation = with_launcher_package(base_installation(tmp_path)) - assert console_package_path(CHECKOUT_SOURCE, bundled) == CHECKOUT_SOURCE + assert installation.package_path(CHECKOUT_SOURCE) == CHECKOUT_SOURCE -def test_console_package_path_selects_the_launcher_package_when_installed(tmp_path: Path) -> None: +def test_package_path_selects_the_launcher_package_when_installed(tmp_path: Path) -> None: """Without a checkout source, the launcher package directory is selected when it holds the package.""" - bundled = launcher_bundle(tmp_path / "launcher-webconsole") + installation = with_launcher_package(base_installation(tmp_path)) - assert console_package_path("", bundled) == str(bundled) + assert installation.package_path("") == str(installation.launcher_source) -def test_console_package_path_is_empty_when_only_the_base_copy_exists(tmp_path: Path) -> None: +def test_package_path_is_empty_when_only_the_base_copy_exists(tmp_path: Path) -> None: """Without a checkout source or an installed launcher package, the empty result leaves the base copy to the import.""" - absent = tmp_path / "launcher-webconsole" - - assert console_package_path("", absent) == "" + assert base_installation(tmp_path).package_path("") == "" -def test_console_child_runs_the_launcher_package_on_the_base_interpreter( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, base_python: Path, -) -> None: +def test_child_runs_the_launcher_package_on_the_base_interpreter(tmp_path: Path) -> None: """With an empty ``console.source_path`` and an installed launcher package, ``PYTHONPATH`` selects that package.""" - bundled = install_launcher_package(tmp_path, monkeypatch) + installation = with_launcher_package(base_installation(tmp_path)) plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) - child = console_child(plan, lambda command: ("as-user", *command)) + child = installation.child(plan, lambda command: ("as-user", *command)) assert child is not None assert child.name == CONSOLE_CHILD @@ -109,8 +102,8 @@ def test_console_child_runs_the_launcher_package_on_the_base_interpreter( assert child.command == ( "as-user", "env", - f"PYTHONPATH={bundled}", - str(base_python), + f"PYTHONPATH={installation.launcher_source}", + str(installation.python), "-m", "devcapsule_webconsole", "--project", @@ -128,18 +121,19 @@ def test_console_child_runs_the_launcher_package_on_the_base_interpreter( assert child.ready_timeout_seconds == CONSOLE_READY_TIMEOUT_SECONDS -def test_console_child_runs_the_base_copy_without_a_launcher_package( - tmp_path: Path, capsys: pytest.CaptureFixture[str], base_python: Path, +def test_child_runs_the_base_copy_without_a_launcher_package( + tmp_path: Path, capsys: pytest.CaptureFixture[str], ) -> None: """With neither a checkout source nor a launcher package, the command carries no ``PYTHONPATH`` and nothing is announced.""" + installation = base_installation(tmp_path) plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) - child = console_child(plan, lambda command: ("as-user", *command)) + child = installation.child(plan, lambda command: ("as-user", *command)) assert child is not None assert child.command == ( "as-user", - str(base_python), + str(installation.python), "-m", "devcapsule_webconsole", "--project", @@ -156,98 +150,86 @@ def test_console_child_runs_the_base_copy_without_a_launcher_package( assert capsys.readouterr().err == "" -def test_console_child_runs_the_mounted_checkout_source_and_says_so( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], base_python: Path, +def test_child_runs_the_mounted_checkout_source_and_says_so( + tmp_path: Path, capsys: pytest.CaptureFixture[str], ) -> None: """With ``console.source_path`` set beside a launcher package, ``PYTHONPATH`` selects the checkout and stderr announces it.""" - install_launcher_package(tmp_path, monkeypatch) + installation = with_launcher_package(base_installation(tmp_path)) plan = runtime_plan( tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token", source_path=CHECKOUT_SOURCE), ) - child = console_child(plan, lambda command: command) + child = installation.child(plan, lambda command: command) assert child is not None - assert child.command[:3] == ("env", f"PYTHONPATH={CHECKOUT_SOURCE}", str(base_python)) + assert child.command[:3] == ("env", f"PYTHONPATH={CHECKOUT_SOURCE}", str(installation.python)) assert f"running the mounted checkout's source at {CHECKOUT_SOURCE}" in capsys.readouterr().err +def test_child_is_none_when_plan_omits_console(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: + """Without a ``console`` section in ``RuntimePlan``, ``child`` returns ``None`` silently.""" + child = base_installation(tmp_path).child(runtime_plan(tmp_path, console=None), lambda command: command) + + assert child is None + assert capsys.readouterr().err == "" + + +def test_child_warns_and_returns_none_when_interpreter_is_absent( + tmp_path: Path, capsys: pytest.CaptureFixture[str], +) -> None: + """On an image without the console interpreter, ``child`` prints a degradation notice and returns ``None``.""" + installation = ConsoleInstallation(tmp_path / "absent-python", tmp_path / "launcher-webconsole") + plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) + + child = installation.child(plan, lambda command: command) + + assert child is None + assert "this base has no web console (base recipe 10 adds it" in capsys.readouterr().err + + @pytest.mark.parametrize( - ("listen", "expected_probe"), + ("listen", "expected"), [ ("0.0.0.0", "127.0.0.1"), ("::", "::1"), ("127.0.0.1", "127.0.0.1"), ("::1", "::1"), + ("192.0.2.7", "192.0.2.7"), ], ) -def test_console_readiness_probes_loopback_of_listener_address_family( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, base_python: Path, listen: str, expected_probe: str, +def test_probe_address_is_the_loopback_of_a_wildcard_listener_and_the_address_of_any_other( + listen: str, expected: str, ) -> None: - """``child.ready`` opens one connection to the loopback of the listener's family, waits 0.2 s at most, and closes it.""" - events: list[object] = [] - - class Connection: - def __enter__(self) -> "Connection": - return self - - def __exit__(self, *_exception: object) -> None: - events.append("closed") + """``probe_address`` maps each wildcard to the loopback of its family and leaves a named address as it is.""" + assert probe_address(listen) == expected - def accept(address: tuple[str, int], timeout: float | None = None) -> Connection: - events.append((address, timeout)) - return Connection() - plan = runtime_plan(tmp_path, console=ConsolePlan(listen, 45678, "/run/devcapsule-console-token")) - child = console_child(plan, lambda command: command) - assert child is not None and child.ready is not None +def test_child_is_ready_once_its_port_accepts_a_connection(tmp_path: Path) -> None: + """For a console planned on every IPv4 interface, ``child.ready`` is true while a listener on loopback holds its port.""" + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener: + listener.bind(("127.0.0.1", 0)) + listener.listen() + port = listener.getsockname()[1] + plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", port, "/run/devcapsule-console-token")) + child = base_installation(tmp_path).child(plan, lambda command: command) + assert child is not None and child.ready is not None - with monkeypatch.context() as network: - network.setattr(socket, "create_connection", accept) ready = child.ready() assert ready is True - assert events == [((expected_probe, 45678), 0.2), "closed"] - - -def test_console_readiness_returns_false_when_probe_connection_fails( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, base_python: Path, -) -> None: - """``child.ready`` returns ``False`` when nothing accepts the connection.""" - def refuse(address: tuple[str, int], timeout: float | None = None) -> socket.socket: - raise ConnectionRefusedError("connection refused") - plan = runtime_plan(tmp_path, console=ConsolePlan("127.0.0.1", 45678, "/run/devcapsule-console-token")) - child = console_child(plan, lambda command: command) - assert child is not None and child.ready is not None +def test_child_is_not_ready_while_nothing_listens_on_its_port(tmp_path: Path) -> None: + """``child.ready`` is false when the planned port refuses the connection.""" + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as reserved: + # Bound and never listening: the port refuses, and no other process can take it meanwhile. + reserved.bind(("127.0.0.1", 0)) + port = reserved.getsockname()[1] + plan = runtime_plan(tmp_path, console=ConsolePlan("127.0.0.1", port, "/run/devcapsule-console-token")) + child = base_installation(tmp_path).child(plan, lambda command: command) + assert child is not None and child.ready is not None - with monkeypatch.context() as network: - network.setattr(socket, "create_connection", refuse) ready = child.ready() assert ready is False - - -def test_console_child_is_none_when_plan_omits_console( - tmp_path: Path, capsys: pytest.CaptureFixture[str], -) -> None: - """Without a ``console`` section in ``RuntimePlan``, ``console_child`` returns ``None`` silently.""" - child = console_child(runtime_plan(tmp_path, console=None), lambda command: command) - - assert child is None - assert capsys.readouterr().err == "" - - -def test_console_child_warns_and_returns_none_when_interpreter_is_absent( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], -) -> None: - """When the base image lacks ``CONSOLE_PYTHON``, ``console_child`` prints a degradation notice and returns ``None``.""" - monkeypatch.setattr(console, "CONSOLE_PYTHON", str(tmp_path / "absent")) - plan = runtime_plan(tmp_path, console=ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token")) - - child = console_child(plan, lambda command: command) - - assert child is None - assert "this base has no web console (base recipe 10 adds it" in capsys.readouterr().err diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py index 4e108fdc..11833088 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py @@ -1,18 +1,59 @@ -"""Unit tests of ``devcapsule/container_runtime/contract.py``: the ``console`` section of ``RuntimePlan``.""" +"""Unit tests of ``devcapsule/container_runtime/contract.py``: component templates, and the runtime plan with its ``console`` and ``logs`` sections.""" from __future__ import annotations +import json from pathlib import Path import re +from typing import Callable import pytest from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan, RuntimePlanError +from devcapsule.container_runtime.contract import ( + ComponentRuntimeTemplate, + ConsolePlan, + Identity, + LogsPlan, + RuntimePlan, + RuntimePlanError, +) CONSOLE = {"listen_address": "0.0.0.0", "port": 6081, "token_path": "/run/devcapsule-console-token"} +def state_slot(name: str, container_path: str, kind: str, **more: object) -> dict[str, object]: + """One state slot of a component template, with every field the contract requires.""" + return { + "name": name, + "container_path": container_path, + "kind": kind, + "sensitivity": "ordinary", + "default_scope": "checkout", + "storage": "directory", + "concurrent": False, + "owner": "runtime-user", + "permissions": "0700", + "reconstructable": kind == "cache", + "deletion_effect": f"Removes the tool's {name}.", + **more, + } + + +def tool_template(*slots: dict[str, object]) -> dict[str, object]: + """A component template document for a component named ``tool`` that persists its home and ``slots``.""" + return { + "version": 1, + "component": { + "id": "tool", + "adapter": "fixture", + "configuration": {}, + "environment": {"TOOL_OPTIONS": "-quiet"}, + "persistence": {"home": "required", "xdg": "home-relative", "state_slots": list(slots)}, + }, + } + + def base_runtime_document(tmp_path: Path) -> dict[str, object]: """Construct a valid ``RuntimePlan`` mapping rooted under ``tmp_path``.""" plan = RuntimePlan.for_component( @@ -99,3 +140,203 @@ def test_runtime_plan_accepts_boundary_tcp_ports(tmp_path: Path, port: int) -> N """``RuntimePlan.from_mapping`` accepts valid TCP port boundaries 1 and 65535.""" plan = RuntimePlan.from_mapping({**base_runtime_document(tmp_path), "console": {**CONSOLE, "port": port}}) assert plan.console is not None and plan.console.port == port + + +def test_runtime_plan_parses_a_versioned_document(tmp_path: Path) -> None: + """``RuntimePlan.from_json`` reads the identity, the component and the state slots of a version 1 document.""" + document = base_runtime_document(tmp_path) + + plan = RuntimePlan.from_json(json.dumps(document)) + + assert plan.identity == Identity(1000, 1000, "developer") + assert plan.home == str(tmp_path / "home") + assert plan.component.adapter == "jetbrains" + assert plan.slots_by_name()["pycharm/config"] == "/ide-config" + + +def test_component_template_parses_its_persistence_declaration() -> None: + """``ComponentRuntimeTemplate.from_json`` reads the home, the XDG layout and each state slot, and prefixes a slot's name with the component's.""" + document = tool_template(state_slot("config", "/tool-config", "durable")) + + template = ComponentRuntimeTemplate.from_json(json.dumps(document)) + + assert template.persistence.home == "required" + assert template.persistence.xdg == "home-relative" + assert [(slot.name, slot.kind) for slot in template.persistence.state_slots] == [("config", "durable")] + assert template.logical_slot_name("config") == "tool/config" + + +def test_for_component_places_each_declared_slot_at_its_container_path() -> None: + """``RuntimePlan.for_component`` names each slot ``/`` at the path the template declares, a home overlay included.""" + template = ComponentRuntimeTemplate.from_mapping(tool_template( + state_slot("config", "/tool-config", "durable"), + state_slot("cache", "/home/devcapsule/.cache", "cache", home_overlay=True), + )) + + plan = RuntimePlan.for_component( + template, project_path="/workspace/project", home="/home/devcapsule", identity=Identity(1000, 1000), + ) + + assert plan.slots_by_name() == {"tool/config": "/tool-config", "tool/cache": "/home/devcapsule/.cache"} + + +def test_for_component_carries_the_components_environment() -> None: + """``RuntimePlan.for_component`` gives the plan's component the variables its template declares.""" + template = ComponentRuntimeTemplate.from_mapping(tool_template()) + + plan = RuntimePlan.for_component( + template, project_path="/workspace/project", home="/home/devcapsule", identity=Identity(1000, 1000), + ) + + assert plan.component.environment == {"TOOL_OPTIONS": "-quiet"} + assert plan.component_environment() == {"TOOL_OPTIONS": "-quiet"} + + +def test_for_component_gives_a_home_only_component_no_state_slot() -> None: + """A template that declares a home and no state slot yields a plan with no state slot.""" + template = ComponentRuntimeTemplate.from_mapping(tool_template()) + + plan = RuntimePlan.for_component( + template, project_path="/workspace/project", home="/home/devcapsule", identity=Identity(1000, 1000), + ) + + assert plan.state_slots == () + + +def test_component_template_requires_a_slot_under_the_home_to_declare_home_overlay() -> None: + """A state slot whose path lies under the home and omits ``home_overlay`` is refused.""" + document = tool_template(state_slot("cache", "/home/devcapsule/.cache", "cache")) + + with pytest.raises(RuntimePlanError, match="must declare home_overlay"): + ComponentRuntimeTemplate.from_mapping(document) + + +def unsupported_version(document: dict[str, object]) -> None: + document["version"] = 2 + + +def boolean_uid(document: dict[str, object]) -> None: + document["identity"] = {"uid": True, "gid": 1} + + +def duplicate_slot(document: dict[str, object]) -> None: + document["state_slots"] = [{"name": "same", "path": "/a"}, {"name": "same", "path": "/b"}] + + +def unsafe_component_id(document: dict[str, object]) -> None: + component = document["component"] + assert isinstance(component, dict) + component["id"] = "Tool/unsafe" + + +@pytest.mark.parametrize( + ("damage", "message"), + [ + (unsupported_version, "unsupported runtime plan version"), + (boolean_uid, "identity.uid"), + (duplicate_slot, "duplicate state slot"), + (unsafe_component_id, "component.id"), + ], +) +def test_runtime_plan_rejects_a_document_it_cannot_trust( + tmp_path: Path, damage: Callable[[dict[str, object]], None], message: str, +) -> None: + """An unknown version, a boolean uid, a repeated slot name or an unsafe component id each raise ``RuntimePlanError`` naming the fault.""" + document = base_runtime_document(tmp_path) + damage(document) + + with pytest.raises(RuntimePlanError, match=message): + RuntimePlan.from_mapping(document) + + +def test_runtime_plan_round_trips_the_logs_section(tmp_path: Path) -> None: + """``RuntimePlan`` parses a ``logs`` section into a ``LogsPlan`` and serializes it back unchanged.""" + document = {**base_runtime_document(tmp_path), "logs": {"directory": "/var/log/devcapsule"}} + + plan = RuntimePlan.from_mapping(document) + + assert plan.logs == LogsPlan("/var/log/devcapsule") + assert plan.to_mapping()["logs"] == {"directory": "/var/log/devcapsule"} + assert RuntimePlan.from_mapping(plan.to_mapping()) == plan + + +def test_runtime_plan_omits_logs_when_absent_or_none(tmp_path: Path) -> None: + """``RuntimePlan`` treats an omitted or ``None`` ``logs`` entry as ``None`` and omits it from ``to_mapping``.""" + document = base_runtime_document(tmp_path) + + absent = RuntimePlan.from_mapping(document) + explicit_none = RuntimePlan.from_mapping({**document, "logs": None}) + + assert absent.logs is None + assert explicit_none.logs is None + assert "logs" not in absent.to_mapping() + + +def test_with_logs_replaces_the_plans_logs_section(tmp_path: Path) -> None: + """``RuntimePlan.with_logs`` returns a plan carrying the supplied ``LogsPlan``.""" + plan = RuntimePlan.from_mapping({**base_runtime_document(tmp_path), "logs": {"directory": "/var/log/devcapsule"}}) + + updated = plan.with_logs(LogsPlan("/elsewhere")) + + assert updated.logs == LogsPlan("/elsewhere") + + +@pytest.mark.parametrize( + ("logs_section", "message"), + [ + ("text", "logs must be an object"), + ({"directory": "/var/log/devcapsule", "extra": 1}, "logs must not carry extra"), + ({"directory": "relative"}, "logs.directory must be an absolute normalized container path"), + ({"directory": "/var/../log"}, "logs.directory must be an absolute normalized container path"), + ({}, "logs.directory must be"), + ], +) +def test_runtime_plan_rejects_a_malformed_logs_section(tmp_path: Path, logs_section: object, message: str) -> None: + """A ``logs`` section that is no object, carries an unknown key, or names no absolute normalized directory is refused.""" + with pytest.raises(RuntimePlanError, match=message): + RuntimePlan.from_mapping({**base_runtime_document(tmp_path), "logs": logs_section}) + + +def test_runtime_plan_round_trips_the_rotation_of_its_logs(tmp_path: Path) -> None: + """A ``logs`` section with a segment size and a rotation count parses into a rotating ``LogsPlan`` and serializes back unchanged.""" + logs_section = {"directory": "/var/log/devcapsule", "segment_bytes": 8388608, "rotations": 4} + + plan = RuntimePlan.from_mapping({**base_runtime_document(tmp_path), "logs": logs_section}) + + assert plan.logs == LogsPlan("/var/log/devcapsule", 8388608, 4) + assert plan.logs is not None and plan.logs.rotates + assert plan.to_mapping()["logs"] == logs_section + + +def test_logs_plan_without_a_rotation_does_not_rotate() -> None: + """A ``LogsPlan`` that names only a directory has ``rotates`` false.""" + assert not LogsPlan("/var/log/devcapsule").rotates + + +def test_logs_plan_reads_a_zero_rotation_as_none() -> None: + """A segment size and a rotation count that are both zero parse to the plan that names only the directory.""" + parsed = LogsPlan.from_mapping({"directory": "/var/log/devcapsule", "segment_bytes": 0, "rotations": 0}, "logs") + + assert parsed == LogsPlan("/var/log/devcapsule") + + +@pytest.mark.parametrize( + ("rotation", "message"), + [ + ({"segment_bytes": 0}, "go together"), + ({"rotations": 0}, "go together"), + ({"segment_bytes": 1}, "go together"), + ({"rotations": 1}, "go together"), + ({"segment_bytes": -1, "rotations": 1}, "segment_bytes must be a non-negative integer"), + ({"segment_bytes": 1, "rotations": True}, "rotations must be a non-negative integer"), + ({"segment_bytes": "8M", "rotations": 1}, "segment_bytes must be a non-negative integer"), + ], +) +def test_runtime_plan_rejects_a_rotation_that_is_half_given_or_not_a_count( + tmp_path: Path, rotation: dict[str, object], message: str, +) -> None: + """A segment size without a rotation count, or the reverse, and a value that is no non-negative integer, are each refused.""" + logs_section = {"directory": "/var/log/devcapsule", **rotation} + + with pytest.raises(RuntimePlanError, match=message): + RuntimePlan.from_mapping({**base_runtime_document(tmp_path), "logs": logs_section}) diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py index 4c35b739..f342e265 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_entrypoint.py @@ -1,178 +1,50 @@ -"""Unit tests of ``devcapsule/container_runtime/entrypoint.py``: the children ``run`` supervises and the environment it gives them.""" +"""Unit tests of ``devcapsule/container_runtime/entrypoint.py``: the command line of the runtime. + +``run`` is the layer that reads the process and acts on the host; what it +decides is ``Session``'s, tested in ``test_session.py``, and what it does is +exercised by ``tests/integration/test_runtime_entrypoint_cli.py``. +""" from __future__ import annotations -from collections.abc import Iterator -from contextlib import contextmanager -from dataclasses import dataclass, field -import os from pathlib import Path import pytest -from devcapsule import logs -from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime import console, entrypoint, filesystem -from devcapsule.container_runtime.console import CONSOLE_CHILD, CommandWrapper -from devcapsule.container_runtime.contract import ( - CONTAINED_DISPLAY_TRANSPORT, - ConsolePlan, - DisplayPlan, - Identity, - RuntimePlan, -) -from devcapsule.container_runtime.display import ContainedDisplay, NOVNC_CHILD, XVNC_CHILD -from devcapsule.container_runtime.entrypoint import run -from devcapsule.container_runtime.supervisor import SupervisedChild - -SUPERVISOR_STATUS = 42 - - -@dataclass -class SessionHost: - """What ``run`` reads from and leaves on the host, as one test built and observes it.""" - - environ: dict[str, str] = field(default_factory=dict) - supervised: list[tuple[SupervisedChild, ...]] = field(default_factory=list) - environment_at_start: dict[str, str] = field(default_factory=dict) - - @contextmanager - def process(self) -> Iterator[None]: - """Replace process inputs only during the action, before pytest resumes.""" - with pytest.MonkeyPatch.context() as process: - process.setattr(os, "environ", self.environ) - process.setattr(os, "geteuid", lambda: 1000) - yield - - -def fake_display(_plan: RuntimePlan, _runtime_dir: str, as_user: CommandWrapper) -> ContainedDisplay: - """Stand-in for ``prepare_contained_display``: two infrastructure children and their environment, no X server.""" - return ContainedDisplay( - children=( - SupervisedChild(name=XVNC_CHILD, command=as_user(("Xvnc",))), - SupervisedChild(name=NOVNC_CHILD, command=as_user(("websockify",))), - ), - environment={"DISPLAY": ":99", "XAUTHORITY": "/tmp/Xauthority"}, - display_number=99, - xauthority_path="/tmp/Xauthority", - rfb_socket_path="/tmp/rfb.sock", - openbox_configuration_path="/tmp/openbox.xml", - panel_configuration_path="/tmp/tint2rc", - ) - - -@pytest.fixture -def host(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> SessionHost: - """A host built for one ``run``. +from devcapsule.container_runtime.entrypoint import USAGE, main - Within ``host.process()``, the environment is an empty mapping and the - caller is not root. The image paths lie under ``tmp_path``: a runtime - root, an empty interpreter file, and an absent launcher package. The display, the - supervisor and the log setup are stand-ins, so no program starts and the - root logger stays as it was. - """ - session = SessionHost() - class RecordingSupervisor: - def __init__(self, children: tuple[SupervisedChild, ...], **_settings: object) -> None: - session.supervised.append(children) - session.environment_at_start = dict(os.environ) +def test_main_prints_the_usage_for_help(capsys: pytest.CaptureFixture[str]) -> None: + """``main(["--help"])`` prints the usage on stdout and returns 0.""" + status = main(["--help"]) - def run(self) -> int: - return SUPERVISOR_STATUS + assert status == 0 + assert capsys.readouterr().out == USAGE + "\n" - python = tmp_path / "base-python" - python.touch() - monkeypatch.setattr(filesystem, "RUNTIME_ROOT", str(tmp_path / "runtime")) - monkeypatch.setattr(console, "CONSOLE_PYTHON", str(python)) - monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) - monkeypatch.setattr(entrypoint, "prepare_contained_display", fake_display) - monkeypatch.setattr(entrypoint, "Supervisor", RecordingSupervisor) - monkeypatch.setattr(logs, "configure", lambda *_arguments, **_settings: None) - return session - -def make_plan(tmp_path: Path, *, with_display: bool) -> RuntimePlan: - """Construct a ``RuntimePlan`` with a console whose project, home, state slots, and properties file all live under ``tmp_path``.""" - base = RuntimePlan.for_component( - pycharm_runtime_template(), - project_path=str(tmp_path / "project"), - home=str(tmp_path / "home"), - identity=Identity(1000, 1000, "developer"), - ).with_console(ConsolePlan("0.0.0.0", 6081, str(tmp_path / "console-token"))) - document = base.to_mapping() - document["state_slots"] = [ - {"name": slot.name, "path": str(tmp_path / "slots" / slot.name.replace("/", "-"))} - for slot in base.state_slots - ] - component = document["component"] - assert isinstance(component, dict) - configuration = component["configuration"] - assert isinstance(configuration, dict) - configuration["properties_path"] = str(tmp_path / "jetbrains.properties") - if with_display: - document["display"] = DisplayPlan( - transport=CONTAINED_DISPLAY_TRANSPORT, - listen_address="127.0.0.1", - port=6080, - token_path=str(tmp_path / "display-token"), - ).to_mapping() - return RuntimePlan.from_mapping(document) - - -def test_run_places_console_after_contained_display_and_before_foreground_surface( - tmp_path: Path, host: SessionHost, +@pytest.mark.parametrize( + "arguments", + [[], ["plan.json", "--"], ["plan.json", "other.json"]], + ids=["no plan", "separator without a job", "two plans"], +) +def test_main_refuses_a_command_line_that_names_no_single_plan_or_an_empty_job( + capsys: pytest.CaptureFixture[str], arguments: list[str], ) -> None: - """With a contained display and console, ``run`` orders display children, ``console``, and foreground IDE.""" - plan = make_plan(tmp_path, with_display=True) - with host.process(): - status = run(plan) - - assert status == SUPERVISOR_STATUS - (children,) = host.supervised - assert [child.name for child in children] == [XVNC_CHILD, NOVNC_CHILD, CONSOLE_CHILD, "pycharm"] - assert all(not child.foreground for child in children[:-1]) - assert children[-1].foreground is True - + """Without exactly one plan, or with ``--`` and no command after it, ``main`` prints the usage on stderr and returns 2.""" + status = main(arguments) -def test_run_places_console_before_foreground_surface_without_display(tmp_path: Path, host: SessionHost) -> None: - """Without a contained display, ``run`` starts ``console`` in background and the surface in foreground.""" - plan = make_plan(tmp_path, with_display=False) - with host.process(): - status = run(plan) + assert status == 2 + output = capsys.readouterr() + assert output.err == USAGE + "\n" + assert output.out == "" - assert status == SUPERVISOR_STATUS - (children,) = host.supervised - assert [child.name for child in children] == [CONSOLE_CHILD, "pycharm"] - assert children[0].foreground is False and children[1].foreground is True +@pytest.mark.parametrize("job", [[], ["--", "true"]], ids=["interactive", "headless"]) +def test_main_reports_a_plan_it_cannot_read( + tmp_path: Path, capsys: pytest.CaptureFixture[str], job: list[str], +) -> None: + """For a plan file that does not exist, ``main`` names the plan error on stderr and returns 2, with or without a job.""" + status = main([str(tmp_path / "missing.json"), *job]) -def test_run_suppresses_contained_display_and_keeps_console_in_job_mode(tmp_path: Path, host: SessionHost) -> None: - """In headless ``job`` mode, ``run`` omits display children even if declared and supervises ``[console, job]``.""" - plan = make_plan(tmp_path, with_display=True) - with host.process(): - status = run(plan, job=("pytest", "-q")) - - assert status == SUPERVISOR_STATUS - (children,) = host.supervised - assert [child.name for child in children] == [CONSOLE_CHILD, "job"] - assert children[0].foreground is False and children[1].foreground is True - assert children[1].command == ("pytest", "-q") - assert children[1].working_directory == str(tmp_path / "project") - - -def test_run_gives_the_session_its_environment_before_the_children_start(tmp_path: Path, host: SessionHost) -> None: - """Before supervision, ``run`` sets session paths and display variables, supplies graphics defaults, and preserves graphics overrides.""" - plan = make_plan(tmp_path, with_display=True) - host.environ["LIBGL_ALWAYS_SOFTWARE"] = "0" - with host.process(): - run(plan) - - assert host.environment_at_start["HOME"] == str(tmp_path / "home") - assert host.environment_at_start["XDG_RUNTIME_DIR"] == str(tmp_path / "runtime" / "devcapsule-runtime-1000") - assert host.environment_at_start["DISPLAY"] == ":99" - assert host.environment_at_start["XAUTHORITY"] == "/tmp/Xauthority" - assert host.environment_at_start["PYCHARM_PROPERTIES"] == str(tmp_path / "jetbrains.properties") - assert host.environment_at_start["NO_AT_BRIDGE"] == "1" - assert host.environment_at_start["LIBGL_ALWAYS_SOFTWARE"] == "0" - assert (tmp_path / "jetbrains.properties").is_file() + assert status == 2 + assert "devcapsule runtime plan error: cannot read runtime plan" in capsys.readouterr().err diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py index 04a44d98..81ed6fd9 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py @@ -2,15 +2,18 @@ from __future__ import annotations -import os from pathlib import Path import stat -import pytest - from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.container_runtime.contract import Identity, RuntimePlan -from devcapsule.container_runtime.filesystem import FilesystemPlan, plan_filesystem, prepare_filesystem +from devcapsule.container_runtime.filesystem import ( + FilesystemPlan, + create_directories, + plan_filesystem, + prepare_filesystem, +) +from devcapsule.container_runtime.identity import CapsuleUser DEVELOPER = Identity(1000, 1001, "developer") @@ -41,57 +44,59 @@ def filesystem_under(root: Path) -> FilesystemPlan: ) -def record_ownership_changes(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Path, int, int]]: - """Replace ``os.chown`` for the test and return the list its calls are appended to.""" - changes: list[tuple[Path, int, int]] = [] - monkeypatch.setattr(os, "chown", lambda path, uid, gid: changes.append((Path(path), uid, gid))) - return changes - - def test_plan_filesystem_derives_the_session_directories_from_the_home_the_user_and_the_slots( tmp_path: Path, ) -> None: - """``plan_filesystem`` names the runtime directory after the uid under /tmp and lists it, the home and every state slot.""" + """``plan_filesystem`` puts the XDG directories under the home, names the runtime directory after the uid under /tmp, and lists them with every state slot.""" runtime = sandboxed_plan(tmp_path) plan = plan_filesystem(runtime) runtime_directory = "/tmp/devcapsule-runtime-1000" assert plan.environment["HOME"] == str(tmp_path / "home") + assert plan.environment["XDG_CONFIG_HOME"] == str(tmp_path / "home" / ".config") assert plan.environment["XDG_RUNTIME_DIR"] == runtime_directory - assert {str(tmp_path / "home"), runtime_directory} <= set(plan.directories) + assert {str(tmp_path / "home"), str(tmp_path / "home" / ".config"), runtime_directory} <= set(plan.directories) assert {slot.path for slot in runtime.state_slots} <= set(plan.directories) -def test_prepare_filesystem_creates_every_directory_and_keeps_ssh_and_runtime_private( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, -) -> None: - """For a caller that is not root, ``prepare_filesystem`` creates each directory, sets ``0700`` on ``.ssh`` and the runtime directory, and changes no owner.""" +def test_create_directories_creates_every_directory_and_keeps_ssh_and_runtime_private(tmp_path: Path) -> None: + """``create_directories`` creates each directory of the plan and sets ``0700`` on ``.ssh`` and the runtime directory.""" filesystem = filesystem_under(tmp_path) - with monkeypatch.context() as process: - process.setattr(os, "geteuid", lambda: 1000) - changes = record_ownership_changes(process) - prepare_filesystem(filesystem, DEVELOPER) + + create_directories(filesystem) assert all(Path(directory).is_dir() for directory in filesystem.directories) assert stat.S_IMODE((tmp_path / "home" / ".ssh").stat().st_mode) == 0o700 assert stat.S_IMODE(Path(filesystem.environment["XDG_RUNTIME_DIR"]).stat().st_mode) == 0o700 - assert changes == [] -def test_prepare_filesystem_gives_the_capsule_user_only_the_directories_it_created_when_root( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, -) -> None: - """For root, ``prepare_filesystem`` hands each directory it created to the capsule user, outermost first, and leaves an existing one alone.""" +def test_create_directories_returns_only_what_it_created_a_parent_before_its_child(tmp_path: Path) -> None: + """``create_directories`` returns each directory it made, missing parents included and first, and leaves out one that existed.""" filesystem = filesystem_under(tmp_path) (tmp_path / "home").mkdir() - with monkeypatch.context() as process: - process.setattr(os, "geteuid", lambda: 0) - changes = record_ownership_changes(process) - prepare_filesystem(filesystem, DEVELOPER) - - assert changes == [ - (tmp_path / "home" / ".ssh", 1000, 1001), - (tmp_path / "runtime", 1000, 1001), - (tmp_path / "runtime" / "devcapsule-runtime-1000", 1000, 1001), - ] + + created = create_directories(filesystem) + + assert created == ( + tmp_path / "home" / ".ssh", + tmp_path / "runtime", + tmp_path / "runtime" / "devcapsule-runtime-1000", + ) + + +def test_create_directories_returns_nothing_when_every_directory_exists(tmp_path: Path) -> None: + """Run again on a prepared filesystem, ``create_directories`` creates nothing and says so.""" + filesystem = filesystem_under(tmp_path) + create_directories(filesystem) + + assert create_directories(filesystem) == () + + +def test_prepare_filesystem_creates_the_directories_for_a_caller_that_is_not_root(tmp_path: Path) -> None: + """For a caller that is not root, ``prepare_filesystem`` creates the plan's directories without failing on an owner it may not set.""" + filesystem = filesystem_under(tmp_path) + + prepare_filesystem(filesystem, CapsuleUser(DEVELOPER, caller_uid=1000)) + + assert all(Path(directory).is_dir() for directory in filesystem.directories) diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_graphics.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_graphics.py new file mode 100644 index 00000000..35f5ac71 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_graphics.py @@ -0,0 +1,28 @@ +"""Unit tests of ``devcapsule/container_runtime/graphics.py``: the graphics defaults of a GUI capsule.""" + +from __future__ import annotations + +from devcapsule.container_runtime.graphics import DEFAULTS, environment + + +def test_environment_is_the_defaults_for_a_process_that_sets_none() -> None: + """With no graphics variable set, ``environment`` is every default: no accessibility bridge, software rendering through llvmpipe, no DRI3.""" + assert environment({}) == { + "NO_AT_BRIDGE": "1", + "LIBGL_ALWAYS_SOFTWARE": "1", + "MESA_LOADER_DRIVER_OVERRIDE": "llvmpipe", + "LIBGL_DRI3_DISABLE": "1", + } + + +def test_environment_preserves_a_value_the_process_already_sets() -> None: + """A graphics variable already set keeps its value; the others take their defaults.""" + result = environment({"LIBGL_ALWAYS_SOFTWARE": "0"}) + + assert result["LIBGL_ALWAYS_SOFTWARE"] == "0" + assert result["NO_AT_BRIDGE"] == DEFAULTS["NO_AT_BRIDGE"] + + +def test_environment_names_only_the_graphics_variables() -> None: + """A variable that is no graphics default is not in the result.""" + assert "PATH" not in environment({"PATH": "/usr/bin"}) diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py index dce1fd69..bf81ea8f 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py @@ -1,40 +1,47 @@ -"""Unit tests of ``devcapsule/container_runtime/identity.py``: the privilege drop planned for a supervised child.""" +"""Unit tests of ``devcapsule/container_runtime/identity.py``: what the capsule user is given when root prepares the session.""" from __future__ import annotations -import os +from pathlib import Path import pytest from devcapsule.container_runtime.contract import Identity -from devcapsule.container_runtime.identity import foreground_command +from devcapsule.container_runtime.identity import CapsuleUser DEVELOPER = Identity(1000, 1001, "developer") +PREPARED_BY_ROOT = CapsuleUser(DEVELOPER, caller_uid=0) +PREPARED_BY_THE_USER = CapsuleUser(DEVELOPER, caller_uid=1000) -def test_foreground_command_drops_to_the_capsule_user_when_the_caller_is_root( - monkeypatch: pytest.MonkeyPatch, -) -> None: - """Called as root, ``foreground_command`` prefixes the command with ``gosu`` and the capsule user's ``uid:gid``.""" - with monkeypatch.context() as process: - process.setattr(os, "geteuid", lambda: 0) - command = foreground_command(("ide", "--wait"), DEVELOPER) +def test_command_drops_to_the_capsule_user_when_the_caller_is_root() -> None: + """For a root caller, ``command`` prefixes the command with ``gosu`` and the capsule user's ``uid:gid``.""" + assert PREPARED_BY_ROOT.command(("ide", "--wait")) == ("gosu", "1000:1001", "ide", "--wait") - assert command == ("gosu", "1000:1001", "ide", "--wait") +def test_command_leaves_the_command_alone_when_the_caller_is_not_root() -> None: + """For any caller but root, ``command`` returns the command unchanged.""" + assert PREPARED_BY_THE_USER.command(("ide", "--wait")) == ("ide", "--wait") -def test_foreground_command_leaves_the_command_alone_when_the_caller_is_not_root( - monkeypatch: pytest.MonkeyPatch, -) -> None: - """Called as any user but root, ``foreground_command`` returns the command unchanged.""" - with monkeypatch.context() as process: - process.setattr(os, "geteuid", lambda: 1000) - command = foreground_command(("ide", "--wait"), DEVELOPER) - assert command == ("ide", "--wait") - - -def test_foreground_command_refuses_an_empty_command() -> None: +@pytest.mark.parametrize("user", [PREPARED_BY_ROOT, PREPARED_BY_THE_USER]) +def test_command_refuses_an_empty_command(user: CapsuleUser) -> None: """An empty command raises ``ValueError``, whoever the caller is.""" with pytest.raises(ValueError, match="must not be empty"): - foreground_command((), DEVELOPER) + user.command(()) + + +def test_owner_changes_give_each_created_path_to_the_capsule_user_when_the_caller_is_root() -> None: + """For a root caller, ``owner_changes`` names the capsule user's uid and gid for every path, in the given order.""" + created = (Path("/home/developer/.ssh"), Path("/run/user"), Path("/run/user/1000")) + + assert PREPARED_BY_ROOT.owner_changes(created) == ( + (Path("/home/developer/.ssh"), 1000, 1001), + (Path("/run/user"), 1000, 1001), + (Path("/run/user/1000"), 1000, 1001), + ) + + +def test_owner_changes_are_none_when_the_caller_is_not_root() -> None: + """For any caller but root, ``owner_changes`` is empty: what that caller creates is its own.""" + assert PREPARED_BY_THE_USER.owner_changes((Path("/home/developer/.ssh"),)) == () diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py new file mode 100644 index 00000000..0ec2af88 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py @@ -0,0 +1,434 @@ +"""Unit tests of ``devcapsule/container_runtime/session.py``: what one session prepares, sets and supervises.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule import logs +from devcapsule.components.eclipse import DEFINITION as ECLIPSE +from devcapsule.container_runtime.components import eclipse +from devcapsule.container_runtime.console import CONSOLE_CHILD, ConsoleInstallation +from devcapsule.container_runtime.contract import ( + ConsolePlan, + DisplayPlan, + Identity, + RuntimePlan, + RuntimePlanError, +) +from devcapsule.container_runtime.identity import CapsuleUser +from devcapsule.container_runtime.session import JOB_CHILD, Session +from devcapsule.container_runtime.supervisor import SupervisedChild + +DEVELOPER = Identity(1000, 1001, "developer") + +DISPLAY_CHILDREN = ( + SupervisedChild(name="xvnc", command=("Xvnc", ":99")), + SupervisedChild(name="novnc", command=("websockify", "6080")), +) +"""Two children as a prepared display hands them over; a session only places them.""" + +IDE_COMMAND = ("/opt/jetbrains/pycharm/bin/pycharm.sh", "/workspace/project") + + +def jetbrains_document(tmp_path: Path) -> dict[str, object]: + """A runtime plan document for a JetBrains surface whose home, slots and properties file lie under ``tmp_path``.""" + return { + "version": 1, + "project_path": "/workspace/project", + "home": str(tmp_path / "home"), + "identity": {"uid": 1000, "gid": 1001, "user": "developer"}, + "state_slots": [ + {"name": "jetbrains/config", "path": str(tmp_path / "config")}, + {"name": "jetbrains/system", "path": str(tmp_path / "system")}, + {"name": "jetbrains/plugins", "path": str(tmp_path / "plugins")}, + {"name": "jetbrains/log", "path": str(tmp_path / "log")}, + ], + "component": { + "id": "jetbrains", + "adapter": "jetbrains", + "configuration": { + "installation_path": "/opt/jetbrains/pycharm", + "launcher": "bin/pycharm.sh", + "properties_path": str(tmp_path / "idea.properties"), + "properties_environment_variable": "PYCHARM_PROPERTIES", + "state_slot_mapping": { + "config": "config", + "system": "system", + "plugins": "plugins", + "log": "log", + }, + }, + }, + } + + +def vscode_document(tmp_path: Path) -> dict[str, object]: + """A runtime plan document for a VS Code-family surface whose home and slots lie under ``tmp_path``.""" + return { + "version": 1, + "project_path": "/workspace/project", + "home": str(tmp_path / "home"), + "identity": {"uid": 1000, "gid": 1001, "user": "developer"}, + "state_slots": [ + {"name": "codium/user-data", "path": str(tmp_path / "user-data")}, + {"name": "codium/extensions", "path": str(tmp_path / "extensions")}, + ], + "component": { + "id": "codium", + "adapter": "vscode", + "configuration": { + "installation_path": "/opt/codium", + "launcher": "codium", + "additional_arguments": ["--no-sandbox"], + "state_slot_mapping": {"user-data": "user-data", "extensions": "extensions"}, + }, + }, + } + + +def image_with_console(tmp_path: Path) -> ConsoleInstallation: + """An image whose console interpreter exists, as an empty file nothing executes, and with no launcher package.""" + python = tmp_path / "console-python" + python.touch() + return ConsoleInstallation(python, tmp_path / "launcher-webconsole") + + +def image_without_console(tmp_path: Path) -> ConsoleInstallation: + """An image from before the console: no interpreter and no launcher package.""" + return ConsoleInstallation(tmp_path / "absent-console-python", tmp_path / "launcher-webconsole") + + +def session_of( + document: dict[str, object], + console: ConsoleInstallation, + *, + job: tuple[str, ...] | None = None, + caller_uid: int = 1000, +) -> Session: + """The session of ``document``'s plan, prepared by ``caller_uid`` on an image with ``console``.""" + plan = RuntimePlan.from_mapping(document) + return Session(plan, job, CapsuleUser(plan.identity, caller_uid), console) + + +def with_console(document: dict[str, object]) -> dict[str, object]: + return {**document, "console": ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token").to_mapping()} + + +def with_contained_display(document: dict[str, object]) -> dict[str, object]: + return {**document, "display": DisplayPlan.contained("127.0.0.1", 6080, "/run/devcapsule-display-token").to_mapping()} + + +def test_launch_of_a_jetbrains_surface_carries_its_properties_file_and_the_variable_that_names_it( + tmp_path: Path, +) -> None: + """For a JetBrains component, ``launch`` is the IDE command, the properties text to write, and the variable naming that file.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path)) + + launch = session.launch + + properties_path = str(tmp_path / "idea.properties") + assert launch.command == IDE_COMMAND + assert list(launch.files) == [properties_path] + assert launch.files[properties_path].startswith(f"idea.config.path={tmp_path / 'config'}\n") + assert launch.environment == {"PYCHARM_PROPERTIES": properties_path} + + +def test_launch_of_a_vscode_surface_is_its_command_alone(tmp_path: Path) -> None: + """For a VS Code-family component, ``launch`` is the editor command over its slots, with no file and no variable.""" + session = session_of(vscode_document(tmp_path), image_without_console(tmp_path)) + + launch = session.launch + + assert launch.command == ( + "/opt/codium/codium", + f"--user-data-dir={tmp_path / 'user-data'}", + f"--extensions-dir={tmp_path / 'extensions'}", + "--no-sandbox", + "/workspace/project", + ) + assert launch.files == {} and launch.environment == {} + + +def test_launch_of_an_eclipse_surface_is_the_command_its_adapter_plans(tmp_path: Path) -> None: + """For an Eclipse component, ``launch`` is the command of the Eclipse adapter, with no file and no variable.""" + plan = RuntimePlan.for_component( + ECLIPSE.runtime_template(), project_path="/workspace/project", home=str(tmp_path / "home"), identity=DEVELOPER, + ) + session = Session(plan, None, CapsuleUser(DEVELOPER, 1000), image_without_console(tmp_path)) + + launch = session.launch + + assert launch.command == eclipse.plan(plan).command + assert launch.files == {} and launch.environment == {} + + +def test_launch_refuses_a_component_whose_adapter_the_runtime_does_not_know(tmp_path: Path) -> None: + """A plan whose component names an unknown adapter raises ``RuntimePlanError`` when its launch is asked for.""" + document = jetbrains_document(tmp_path) + document["component"]["adapter"] = "fixture" # type: ignore[index] + session = session_of(document, image_without_console(tmp_path)) + + with pytest.raises(RuntimePlanError, match="unsupported component adapter: fixture"): + session.launch + + +def test_environment_sets_the_session_paths_every_components_variables_and_the_surfaces_own( + tmp_path: Path, +) -> None: + """``environment`` carries the home and runtime directory, an ancillary component's variable, and the surface's properties variable.""" + document = jetbrains_document(tmp_path) + document["ancillary_components"] = [ + { + "id": "codex", + "adapter": "ancillary", + "configuration": {}, + "environment": {"CODEX_HOME": str(tmp_path / "codex-home")}, + } + ] + session = session_of(document, image_without_console(tmp_path)) + + environment = session.environment({}) + + assert environment["HOME"] == str(tmp_path / "home") + assert environment["XDG_RUNTIME_DIR"] == "/tmp/devcapsule-runtime-1000" + assert environment["CODEX_HOME"] == str(tmp_path / "codex-home") + assert environment["PYCHARM_PROPERTIES"] == str(tmp_path / "idea.properties") + + +def test_environment_supplies_the_graphics_defaults_a_process_does_not_have(tmp_path: Path) -> None: + """In a process that sets no graphics variable, ``environment`` turns the accessibility bridge off and software rendering on.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path)) + + environment = session.environment({}) + + assert environment["NO_AT_BRIDGE"] == "1" + assert environment["LIBGL_ALWAYS_SOFTWARE"] == "1" + + +def test_environment_keeps_a_graphics_setting_the_process_already_has(tmp_path: Path) -> None: + """A graphics variable of the existing environment keeps its value in what ``environment`` sets.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path)) + + environment = session.environment({"LIBGL_ALWAYS_SOFTWARE": "0"}) + + assert environment["LIBGL_ALWAYS_SOFTWARE"] == "0" + assert environment["NO_AT_BRIDGE"] == "1" + + +def test_environment_lets_a_components_variable_decide_a_graphics_setting(tmp_path: Path) -> None: + """A graphics variable a component declares wins over the default and over the existing environment.""" + document = jetbrains_document(tmp_path) + document["ancillary_components"] = [ + {"id": "gpu", "adapter": "ancillary", "configuration": {}, "environment": {"LIBGL_ALWAYS_SOFTWARE": "0"}} + ] + session = session_of(document, image_without_console(tmp_path)) + + environment = session.environment({"LIBGL_ALWAYS_SOFTWARE": "1"}) + + assert environment["LIBGL_ALWAYS_SOFTWARE"] == "0" + + +def test_environment_names_only_what_the_session_sets(tmp_path: Path) -> None: + """A variable of the existing environment that the session does not decide is not among those ``environment`` sets.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path)) + + environment = session.environment({"PATH": "/usr/bin", "LANG": "C.UTF-8"}) + + assert "PATH" not in environment and "LANG" not in environment + + +def test_an_interactive_session_shows_the_contained_display_its_plan_selects(tmp_path: Path) -> None: + """With a contained display in the plan and no job, ``shows_contained_display`` is true.""" + session = session_of(with_contained_display(jetbrains_document(tmp_path)), image_without_console(tmp_path)) + + assert session.shows_contained_display is True + + +def test_a_headless_job_shows_no_display_even_when_the_plan_selects_one(tmp_path: Path) -> None: + """With a job, ``shows_contained_display`` is false although the plan carries a contained display.""" + session = session_of( + with_contained_display(jetbrains_document(tmp_path)), image_without_console(tmp_path), job=("pytest", "-q"), + ) + + assert session.shows_contained_display is False + + +@pytest.mark.parametrize("display", [None, DisplayPlan.host_x11().to_mapping()]) +def test_a_session_shows_no_contained_display_unless_its_plan_selects_one( + tmp_path: Path, display: dict[str, object] | None, +) -> None: + """Without a display section, or with the host's X11, ``shows_contained_display`` is false.""" + document = jetbrains_document(tmp_path) + if display is not None: + document["display"] = display + session = session_of(document, image_without_console(tmp_path)) + + assert session.shows_contained_display is False + + +def test_an_interactive_jetbrains_session_holds_the_profile_lock(tmp_path: Path) -> None: + """For a JetBrains surface and no job, ``holds_profile_lock`` is true.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path)) + + assert session.holds_profile_lock is True + + +def test_a_headless_job_holds_no_profile_lock(tmp_path: Path) -> None: + """With a job, ``holds_profile_lock`` is false: no IDE opens the profile.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path), job=("pytest",)) + + assert session.holds_profile_lock is False + + +def test_a_surface_that_is_not_jetbrains_holds_no_profile_lock(tmp_path: Path) -> None: + """For a VS Code-family surface, ``holds_profile_lock`` is false.""" + session = session_of(vscode_document(tmp_path), image_without_console(tmp_path)) + + assert session.holds_profile_lock is False + + +def test_children_start_the_display_then_the_console_then_the_surface(tmp_path: Path) -> None: + """Given a display's children and a plan with a console, ``children`` orders display, ``console``, surface, the surface alone in the foreground.""" + session = session_of(with_console(jetbrains_document(tmp_path)), image_with_console(tmp_path)) + + children = session.children(DISPLAY_CHILDREN) + + assert [child.name for child in children] == ["xvnc", "novnc", CONSOLE_CHILD, "jetbrains"] + assert [child.foreground for child in children] == [False, False, False, True] + assert children[:2] == DISPLAY_CHILDREN + assert children[-1].command == IDE_COMMAND + + +def test_children_without_a_display_are_the_console_and_the_surface(tmp_path: Path) -> None: + """Given no display children, ``children`` is the background ``console`` and the foreground surface.""" + session = session_of(with_console(jetbrains_document(tmp_path)), image_with_console(tmp_path)) + + children = session.children(()) + + assert [child.name for child in children] == [CONSOLE_CHILD, "jetbrains"] + assert [child.foreground for child in children] == [False, True] + + +def test_children_of_a_headless_session_are_the_console_and_the_job_in_the_project(tmp_path: Path) -> None: + """With a job, the foreground child is named ``job``, runs the job's command, and starts in the plan's project.""" + session = session_of( + with_console(jetbrains_document(tmp_path)), image_with_console(tmp_path), job=("pytest", "-q"), + ) + + children = session.children(()) + + assert [child.name for child in children] == [CONSOLE_CHILD, JOB_CHILD] + assert children[-1].foreground is True + assert children[-1].command == ("pytest", "-q") + assert children[-1].working_directory == "/workspace/project" + + +def test_children_of_a_plan_without_a_console_are_the_surface_alone(tmp_path: Path) -> None: + """For a plan with no console section, ``children`` is the one foreground surface, on an image that has a console too.""" + session = session_of(jetbrains_document(tmp_path), image_with_console(tmp_path)) + + children = session.children(()) + + assert children == (SupervisedChild(name="jetbrains", command=IDE_COMMAND, foreground=True),) + + +def test_children_leave_the_console_out_on_an_image_that_has_none( + tmp_path: Path, capsys: pytest.CaptureFixture[str], +) -> None: + """On an image without the console interpreter, ``children`` is the surface alone and stderr says the capsule runs without a console.""" + session = session_of(with_console(jetbrains_document(tmp_path)), image_without_console(tmp_path)) + + children = session.children(()) + + assert [child.name for child in children] == ["jetbrains"] + assert "the capsule runs without one" in capsys.readouterr().err + + +def test_children_all_run_as_the_capsule_user_when_root_prepares_the_session(tmp_path: Path) -> None: + """For a root caller, the console's and the surface's commands both start with ``gosu`` and the capsule user's ``uid:gid``.""" + session = session_of(with_console(jetbrains_document(tmp_path)), image_with_console(tmp_path), caller_uid=0) + + console, surface = session.children(()) + + assert console.command[:2] == ("gosu", "1000:1001") + assert surface.command == ("gosu", "1000:1001", *IDE_COMMAND) + + +def test_a_job_runs_as_the_capsule_user_when_root_prepares_the_session(tmp_path: Path) -> None: + """For a root caller and a job, the job's command starts with ``gosu`` and the capsule user's ``uid:gid``.""" + session = session_of( + jetbrains_document(tmp_path), image_without_console(tmp_path), job=("pytest", "-q"), caller_uid=0, + ) + + (job,) = session.children(()) + + assert job.command == ("gosu", "1000:1001", "pytest", "-q") + + +def test_children_each_get_their_own_log_file_when_the_plan_says_where_logs_go(tmp_path: Path) -> None: + """With a logs directory in the plan, every child's ``log_path`` is ``devcapsule-.log`` in it.""" + document = with_console(jetbrains_document(tmp_path)) + document["logs"] = {"directory": "/var/log/devcapsule"} + session = session_of(document, image_with_console(tmp_path)) + + children = session.children(DISPLAY_CHILDREN) + + assert [child.log_path for child in children] == [ + "/var/log/devcapsule/devcapsule-xvnc.log", + "/var/log/devcapsule/devcapsule-novnc.log", + "/var/log/devcapsule/devcapsule-console.log", + "/var/log/devcapsule/devcapsule-jetbrains.log", + ] + + +def test_children_get_no_log_file_when_the_plan_has_no_logs_section(tmp_path: Path) -> None: + """Without a logs section, every child's ``log_path`` stays unset.""" + session = session_of(with_console(jetbrains_document(tmp_path)), image_with_console(tmp_path)) + + children = session.children(DISPLAY_CHILDREN) + + assert [child.log_path for child in children] == [None, None, None, None] + + +def test_the_log_files_belong_to_the_capsule_user(tmp_path: Path) -> None: + """``log_owner`` is the plan identity's uid and gid, whoever prepares the session.""" + session = session_of(jetbrains_document(tmp_path), image_without_console(tmp_path), caller_uid=0) + + assert session.log_owner == (1000, 1001) + + +def test_the_log_directory_is_the_plans_or_none(tmp_path: Path) -> None: + """``log_directory`` is the directory of the plan's logs section.""" + document = jetbrains_document(tmp_path) + document["logs"] = {"directory": "/var/log/devcapsule"} + + assert session_of(document, image_without_console(tmp_path)).log_directory == "/var/log/devcapsule" + + +def test_a_plan_without_a_logs_section_has_no_log_directory(tmp_path: Path) -> None: + """Without a logs section, ``log_directory`` is ``None``.""" + assert session_of(jetbrains_document(tmp_path), image_without_console(tmp_path)).log_directory is None + + +def test_log_rotation_is_the_plans_when_the_launcher_derived_one(tmp_path: Path) -> None: + """With a segment size and a rotation count in the plan, ``log_rotation`` is that pair.""" + document = jetbrains_document(tmp_path) + document["logs"] = {"directory": "/var/log/devcapsule", "segment_bytes": 2048, "rotations": 3} + + assert session_of(document, image_without_console(tmp_path)).log_rotation == (2048, 3) + + +@pytest.mark.parametrize("logs_section", [None, {"directory": "/var/log/devcapsule"}]) +def test_log_rotation_is_the_default_when_the_plan_carries_none( + tmp_path: Path, logs_section: dict[str, object] | None, +) -> None: + """Without a logs section, or with one that names only a directory, ``log_rotation`` is the module defaults of ``devcapsule.logs``.""" + document = jetbrains_document(tmp_path) + if logs_section is not None: + document["logs"] = logs_section + + assert session_of(document, image_without_console(tmp_path)).log_rotation == ( + logs.MAXIMUM_SEGMENT_BYTES, logs.ROTATIONS, + ) diff --git a/devcapsule-src/tests/unit/devcapsule/test_build_info.py b/devcapsule-src/tests/unit/devcapsule/test_build_info.py index aef69c96..6042f845 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_build_info.py +++ b/devcapsule-src/tests/unit/devcapsule/test_build_info.py @@ -8,34 +8,54 @@ import pytest -from devcapsule import build_info from devcapsule.build_info import ( BuildInfo, BuildInfoError, build_info_json, - current_build_info, - is_built_distribution, + build_info_text, + distribution_build_info, + embedded_build_info, read_pex_build_info, ) +SAMPLE_BUILD = BuildInfo( + schema_version=2, + version="1.2.3", + source_repository="https://github.com/example/devcapsule", + source_revision="d" * 40, + source_url=f"https://github.com/example/devcapsule/commit/{'d' * 40}", + build_mnemonic="v1.2.3", +) + + +def stamped_package(directory: Path, text: str) -> Path: + """A package directory holding ``_build_info.json`` with ``text``, as ``scripts/build-pex.sh`` leaves one.""" + directory.mkdir(parents=True) + (directory / "_build_info.json").write_text(text, encoding="utf-8") + return directory + + +def not_installed() -> str: + """Stand for installed metadata that a test expects nobody to ask for.""" + raise AssertionError("the installed version was asked for") -def test_current_build_info_reads_the_default_package_record( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, -) -> None: - """Without record paths, ``current_build_info`` reads the stamp from the devcapsule package resources.""" - package = tmp_path / "devcapsule" - package.mkdir() - stamped = BuildInfo(2, "1.2.3", "unknown", "unknown", "unknown", "v1.2.3") - (package / "_build_info.json").write_text(build_info_json(stamped), encoding="utf-8") - def package_resources(anchor: str) -> Path: - return tmp_path / anchor +def test_build_info_json_is_the_records_mapping() -> None: + """``build_info_json`` serializes every field of the record, and ``BuildInfo.from_json`` reads it back.""" + text = build_info_json(SAMPLE_BUILD) - monkeypatch.setattr(build_info, "files", package_resources) + assert json.loads(text) == SAMPLE_BUILD.to_mapping() + assert BuildInfo.from_json(text) == SAMPLE_BUILD - info = current_build_info(pyproject_path=tmp_path / "absent.toml", installed_version="9.9.9") - assert info == stamped +def test_build_info_text_shows_the_build_then_where_its_source_is() -> None: + """``build_info_text`` is four lines: the mnemonic with the package version, then repository, revision and URL.""" + assert build_info_text(SAMPLE_BUILD).splitlines() == [ + "DevCapsule v1.2.3 (package 1.2.3)", + "Source repository: https://github.com/example/devcapsule", + f"Source revision: {'d' * 40}", + f"Source URL: https://github.com/example/devcapsule/commit/{'d' * 40}", + ] def test_public_build_identity_requires_matching_github_commit_url() -> None: @@ -120,27 +140,33 @@ def test_read_pex_build_info_rejects_pex_without_embedded_record(tmp_path: Path) read_pex_build_info(pex) -def test_current_build_info_returns_stamped_record_when_present(tmp_path: Path) -> None: - """When a stamped ``_build_info.json`` candidate exists, ``current_build_info`` returns its parsed ``BuildInfo``.""" - record = tmp_path / "_build_info.json" +def test_distribution_build_info_returns_stamped_record_when_present(tmp_path: Path) -> None: + """When a package location holds a stamped ``_build_info.json``, ``distribution_build_info`` returns it, whatever pyproject says, and leaves the installed version unasked.""" expected = BuildInfo(2, "2.3.4", "https://github.com/example/devcapsule", "c" * 40, f"https://github.com/example/devcapsule/commit/{'c' * 40}", "v2.3.4") - record.write_text(build_info_json(expected), encoding="utf-8") + package = stamped_package(tmp_path / "package", build_info_json(expected)) - info = current_build_info(record_paths=(tmp_path / "missing.json", record)) + pyproject = tmp_path / "pyproject.toml" + pyproject.write_text('[project]\nname = "devcapsule"\nversion = "9.8.7"\n', encoding="utf-8") + + info = distribution_build_info( + package_locations=(tmp_path / "unstamped", package), + pyproject_path=pyproject, + installed_version=not_installed, + ) assert info == expected -def test_current_build_info_derives_source_form_from_authored_pyproject(tmp_path: Path) -> None: - """Without ``_build_info.json``, ``current_build_info`` derives ``v-local`` from ``pyproject.toml``.""" +def test_distribution_build_info_derives_source_form_from_authored_pyproject(tmp_path: Path) -> None: + """Without ``_build_info.json``, ``distribution_build_info`` derives ``v-local`` from ``pyproject.toml`` and leaves the installed version unasked.""" pyproject = tmp_path / "pyproject.toml" pyproject.write_text('[project]\nname = "devcapsule"\nversion = "9.8.7"\n', encoding="utf-8") - info = current_build_info( - record_paths=(tmp_path / "absent.json",), + info = distribution_build_info( + package_locations=(tmp_path / "unstamped",), pyproject_path=pyproject, - installed_version="0.0.1", + installed_version=not_installed, ) assert info == BuildInfo( @@ -153,12 +179,12 @@ def test_current_build_info_derives_source_form_from_authored_pyproject(tmp_path ) -def test_current_build_info_falls_back_to_installed_version_outside_checkout(tmp_path: Path) -> None: - """Without ``_build_info.json`` or ``pyproject.toml``, ``current_build_info`` uses installed package metadata.""" - info = current_build_info( - record_paths=(tmp_path / "absent.json",), +def test_distribution_build_info_falls_back_to_installed_version_outside_checkout(tmp_path: Path) -> None: + """Without ``_build_info.json`` or ``pyproject.toml``, ``distribution_build_info`` uses the installed version.""" + info = distribution_build_info( + package_locations=(tmp_path / "unstamped",), pyproject_path=tmp_path / "absent" / "pyproject.toml", - installed_version="4.5.6", + installed_version=lambda: "4.5.6", ) assert info.version == "4.5.6" @@ -166,44 +192,53 @@ def test_current_build_info_falls_back_to_installed_version_outside_checkout(tmp assert info.source_revision == "unknown" -def test_current_build_info_raises_on_malformed_build_record(tmp_path: Path) -> None: +def test_distribution_build_info_ignores_a_pyproject_of_another_project(tmp_path: Path) -> None: + """A ``pyproject.toml`` that names another project is no source checkout of this one, and the installed version answers.""" + pyproject = tmp_path / "pyproject.toml" + pyproject.write_text('[project]\nname = "another"\nversion = "9.8.7"\n', encoding="utf-8") + + info = distribution_build_info( + package_locations=(), pyproject_path=pyproject, installed_version=lambda: "4.5.6", + ) + + assert info.version == "4.5.6" + + +def test_distribution_build_info_raises_on_malformed_build_record(tmp_path: Path) -> None: """A present but malformed ``_build_info.json`` raises ``BuildInfoError`` instead of demoting to source form.""" - malformed = tmp_path / "_build_info.json" - malformed.write_text("not json", encoding="utf-8") + package = stamped_package(tmp_path / "package", "not json") + pyproject = tmp_path / "pyproject.toml" + pyproject.write_text('[project]\nname = "devcapsule"\nversion = "9.8.7"\n', encoding="utf-8") with pytest.raises(BuildInfoError, match="not valid JSON"): - current_build_info(record_paths=(malformed,)) + distribution_build_info(package_locations=(package,), pyproject_path=pyproject, installed_version=not_installed) + +def test_embedded_build_info_is_none_without_a_stamped_location(tmp_path: Path) -> None: + """When no package location holds ``_build_info.json``, ``embedded_build_info`` is ``None``: a source-form run.""" + unstamped = tmp_path / "unstamped" + unstamped.mkdir() -def test_is_built_distribution_returns_false_without_embedded_build_info(tmp_path: Path) -> None: - """Without any readable ``_build_info.json`` candidate, ``is_built_distribution`` returns ``False``.""" - assert is_built_distribution(record_paths=(tmp_path / "missing-resource.json", tmp_path / "missing-sibling.json")) is False + assert embedded_build_info((unstamped, tmp_path / "absent")) is None -def test_is_built_distribution_returns_true_with_valid_embedded_build_info(tmp_path: Path) -> None: - """A valid ``_build_info.json`` on the first candidate path marks the running process as a built distribution.""" - record = tmp_path / "_build_info.json" - info = BuildInfo(2, "0.3.1rc2", "https://github.com/example/devcapsule", "a" * 40, - f"https://github.com/example/devcapsule/commit/{'a' * 40}", "v0.3.1-rc2") - record.write_text(build_info_json(info), encoding="utf-8") +def test_embedded_build_info_reads_the_record_of_the_first_location(tmp_path: Path) -> None: + """``_build_info.json`` in the first package location is the build the distribution was stamped with.""" + package = stamped_package(tmp_path / "package", build_info_json(SAMPLE_BUILD)) - assert is_built_distribution(record_paths=(record,)) is True + assert embedded_build_info((package,)) == SAMPLE_BUILD -def test_is_built_distribution_reads_fallback_record_when_first_candidate_is_absent(tmp_path: Path) -> None: - """When the first candidate is absent, a valid fallback ``_build_info.json`` still marks a built distribution.""" - sibling = tmp_path / "_build_info.json" - info = BuildInfo(2, "0.3.1rc2", "https://github.com/example/devcapsule", "a" * 40, - f"https://github.com/example/devcapsule/commit/{'a' * 40}", "v0.3.1-rc2") - sibling.write_text(build_info_json(info), encoding="utf-8") +def test_embedded_build_info_reads_a_later_location_when_the_first_is_unstamped(tmp_path: Path) -> None: + """When the first location holds no record, the record of the next one is read.""" + package = stamped_package(tmp_path / "package", build_info_json(SAMPLE_BUILD)) - assert is_built_distribution(record_paths=(tmp_path / "missing-resource.json", sibling)) is True + assert embedded_build_info((tmp_path / "unstamped", package)) == SAMPLE_BUILD -def test_is_built_distribution_refuses_malformed_embedded_build_info(tmp_path: Path) -> None: +def test_embedded_build_info_refuses_a_malformed_record(tmp_path: Path) -> None: """A malformed ``_build_info.json`` raises ``BuildInfoError`` instead of pretending to be a source run.""" - malformed = tmp_path / "_build_info.json" - malformed.write_text("{not-json", encoding="utf-8") + package = stamped_package(tmp_path / "package", "{not-json") with pytest.raises(BuildInfoError, match="not valid JSON"): - is_built_distribution(record_paths=(malformed,)) + embedded_build_info((package,)) diff --git a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py index 2e8b979a..102e9a11 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py +++ b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py @@ -8,12 +8,11 @@ import pytest -from devcapsule import recursive_dogfood from devcapsule.compat import CliError from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.configuration.file_formats import ProjectConfigurationError -from devcapsule.console_tools import DECISIONS_MODULE, console_decisions_command, run_console_decisions -from devcapsule.container_runtime import console +from devcapsule.console_tools import DECISIONS_MODULE, DecisionTools +from devcapsule.container_runtime.console import ConsoleInstallation from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan @@ -29,57 +28,59 @@ def runtime_plan(source: str | None) -> RuntimePlan: return plan.with_console(ConsolePlan("0.0.0.0", 6081, "/run/devcapsule-console-token", source_path=source)) -def launcher_bundle(path: Path) -> Path: - pkg = path / "devcapsule_webconsole" - pkg.mkdir(parents=True) - (pkg / "__init__.py").write_text("", encoding="utf-8") - return path +def capsule_tools(tmp_path: Path, python: Path, *, launcher_package: bool = False) -> DecisionTools: + """The decision tools inside a capsule whose console interpreter is ``python``. + The runtime plan is ``tmp_path / "plan.json"``, absent until a test + writes it. The launcher's package is absent unless ``launcher_package``. + """ + launcher_source = tmp_path / "launcher-webconsole" + if launcher_package: + package = launcher_source / "devcapsule_webconsole" + package.mkdir(parents=True) + (package / "__init__.py").write_text("", encoding="utf-8") + return DecisionTools( + in_capsule=True, + console=ConsoleInstallation(python, launcher_source), + runtime_plan_path=tmp_path / "plan.json", + ) -def enter_capsule(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, console_python: Path) -> None: - """Set capsule detection and the paths that the wrapper reads by default. - The caller supplies the interpreter. The plan and launcher package are - absent, so execution uses that interpreter without a PYTHONPATH prefix. - """ - monkeypatch.setenv(recursive_dogfood.CONTAINER_NAME_ENV, "capsule-fixture") - monkeypatch.setattr(console, "CONSOLE_PYTHON", str(console_python)) - monkeypatch.setattr(console, "LAUNCHER_CONSOLE_SOURCE", str(tmp_path / "absent-launcher-webconsole")) - monkeypatch.setattr(recursive_dogfood, "RUNTIME_PLAN_PATH", tmp_path / "no-plan.json") +def interpreter_file(tmp_path: Path) -> Path: + """An empty file where the console interpreter is; ``command`` checks only that it exists.""" + python = tmp_path / "python" + python.touch() + return python -@pytest.mark.parametrize("environ", [{}, {"DEVCAPSULE_CONTAINER_NAME": ""}]) -def test_outside_capsule_refuses_and_names_host_module(tmp_path: Path, environ: dict[str, str]) -> None: - """Outside a capsule, ``console_decisions_command`` raises ``ProjectConfigurationError`` naming the host module.""" +def test_outside_capsule_refuses_and_names_host_module(tmp_path: Path) -> None: + """Outside a capsule, ``command`` raises ``ProjectConfigurationError`` naming the host module, although an interpreter exists.""" + tools = DecisionTools( + in_capsule=False, + console=ConsoleInstallation(interpreter_file(tmp_path), tmp_path / "launcher-webconsole"), + runtime_plan_path=tmp_path / "plan.json", + ) + with pytest.raises(ProjectConfigurationError, match=f"python -m {DECISIONS_MODULE}"): - console_decisions_command( - ["check", "x.json"], - environ=environ, - console_python=tmp_path / "python", - launcher_console_source=tmp_path / "absent", - ) + tools.command(["check", "x.json"]) def test_missing_console_interpreter_refuses_and_names_base_location(tmp_path: Path) -> None: - """When ``console_python`` does not exist, ``console_decisions_command`` names ``/opt/devcapsule-webconsole``.""" + """Inside a capsule whose console interpreter does not exist, ``command`` names ``/opt/devcapsule-webconsole``.""" + tools = capsule_tools(tmp_path, tmp_path / "absent") + with pytest.raises(ProjectConfigurationError, match="no web console at /opt/devcapsule-webconsole"): - console_decisions_command( - ["check", "x.json"], - environ={"DEVCAPSULE_CONTAINER_NAME": "c"}, - console_python=tmp_path / "absent", - runtime_plan_path=tmp_path / "plan.json", - launcher_console_source=tmp_path / "absent-bundle", - ) + tools.command(["check", "x.json"]) @pytest.mark.parametrize("plan_kind", ["missing", "malformed", "non-utf8", "directory", "no-console", "installed"]) def test_installed_console_runs_when_plan_has_no_usable_source_and_no_launcher_bundle( tmp_path: Path, plan_kind: str, ) -> None: - """Without a readable ``console.source_path`` or launcher package, ``console_decisions_command`` runs the base copy directly.""" - python = tmp_path / "python" - python.touch() - plan = tmp_path / "plan.json" + """Without a readable ``console.source_path`` or launcher package, ``command`` runs the base copy directly.""" + python = interpreter_file(tmp_path) + tools = capsule_tools(tmp_path, python) + plan = tools.runtime_plan_path if plan_kind == "malformed": plan.write_text("{", encoding="utf-8") elif plan_kind == "non-utf8": @@ -89,36 +90,22 @@ def test_installed_console_runs_when_plan_has_no_usable_source_and_no_launcher_b elif plan_kind in ("no-console", "installed"): plan.write_text(runtime_plan(None if plan_kind == "no-console" else "").to_json(), encoding="utf-8") - command = console_decisions_command( - ["hand-off", "d/x.json", "--token-file", "t"], - environ={"DEVCAPSULE_CONTAINER_NAME": "c"}, - console_python=python, - runtime_plan_path=plan, - launcher_console_source=tmp_path / "absent-launcher-webconsole", - ) + command = tools.command(["hand-off", "d/x.json", "--token-file", "t"]) assert command == (str(python), "-m", DECISIONS_MODULE, "hand-off", "d/x.json", "--token-file", "t") def test_decisions_command_uses_launcher_package_when_plan_sets_no_checkout_source(tmp_path: Path) -> None: - """Without ``console.source_path``, ``console_decisions_command`` puts the launcher's console package on ``PYTHONPATH``.""" - python = tmp_path / "python" - python.touch() - plan_path = tmp_path / "plan.json" - plan_path.write_text(runtime_plan("").to_json(), encoding="utf-8") - bundled = launcher_bundle(tmp_path / "launcher-webconsole") - - command = console_decisions_command( - ["check", "decision.json"], - environ={"DEVCAPSULE_CONTAINER_NAME": "capsule"}, - console_python=python, - runtime_plan_path=plan_path, - launcher_console_source=bundled, - ) + """Without ``console.source_path``, ``command`` puts the launcher's console package on ``PYTHONPATH``.""" + python = interpreter_file(tmp_path) + tools = capsule_tools(tmp_path, python, launcher_package=True) + tools.runtime_plan_path.write_text(runtime_plan("").to_json(), encoding="utf-8") + + command = tools.command(["check", "decision.json"]) assert command == ( "env", - f"PYTHONPATH={bundled}", + f"PYTHONPATH={tmp_path / 'launcher-webconsole'}", str(python), "-m", DECISIONS_MODULE, @@ -127,23 +114,14 @@ def test_decisions_command_uses_launcher_package_when_plan_sets_no_checkout_sour ) -def test_mounted_source_takes_precedence_over_launcher_package( - tmp_path: Path, -) -> None: - """``console_decisions_command`` selects the plan's checkout source ahead of the launcher package, preserving spaces.""" - python = tmp_path / "python" - python.touch() - bundled = launcher_bundle(tmp_path / "launcher-webconsole") +def test_mounted_source_takes_precedence_over_launcher_package(tmp_path: Path) -> None: + """``command`` selects the plan's checkout source ahead of the launcher package, preserving spaces.""" + python = interpreter_file(tmp_path) + tools = capsule_tools(tmp_path, python, launcher_package=True) plan = runtime_plan("/workspace/project with spaces/devcapsule-webconsole") - plan_path = tmp_path / "plan.json" - plan_path.write_text(plan.to_json(), encoding="utf-8") - command = console_decisions_command( - ["check", "x.json"], - environ={"DEVCAPSULE_CONTAINER_NAME": "c"}, - console_python=python, - runtime_plan_path=plan_path, - launcher_console_source=bundled, - ) + tools.runtime_plan_path.write_text(plan.to_json(), encoding="utf-8") + + command = tools.command(["check", "x.json"]) assert command[:2] == ( "env", @@ -153,11 +131,12 @@ def test_mounted_source_takes_precedence_over_launcher_package( @pytest.mark.parametrize("status", [0, 3]) -def test_run_console_decisions_preserves_arguments_streams_and_exit_status( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capfd: pytest.CaptureFixture[str], status: int, +def test_run_preserves_arguments_streams_and_exit_status( + tmp_path: Path, capfd: pytest.CaptureFixture[str], status: int, ) -> None: - """Inside a capsule, ``run_console_decisions`` passes argv verbatim to the base's console interpreter, streams its output, and returns its exit code.""" + """Inside a capsule, ``run`` passes argv verbatim to the console interpreter, streams its output, and returns its exit code.""" fake = tmp_path / "fake-console-python" + # ``-I`` keeps the stand-in interpreter away from the Python settings of the host's environment. fake.write_text( f"#!{sys.executable} -I\nimport json, sys\nprint(json.dumps(sys.argv[1:]))\n" f"print('console diagnostic', file=sys.stderr)\nsys.exit({status})\n", @@ -165,11 +144,8 @@ def test_run_console_decisions_preserves_arguments_streams_and_exit_status( ) fake.chmod(0o755) arguments = ["from-table", "table with spaces.md", "--id", "pass", "--title", "A title", "--context", "a\nb", "", "--"] - enter_capsule(tmp_path, monkeypatch, fake) - # The fixture interpreter ignores Python startup settings from the host. - monkeypatch.setenv("PYTHONHOME", str(tmp_path / "not-a-python-installation")) - result = run_console_decisions(arguments) + result = capsule_tools(tmp_path, fake).run(arguments) assert result == status output = capfd.readouterr() @@ -177,15 +153,12 @@ def test_run_console_decisions_preserves_arguments_streams_and_exit_status( assert output.err == "console diagnostic\n" -def test_run_console_decisions_raises_cli_error_naming_an_interpreter_that_cannot_start( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, -) -> None: - """When the base's console interpreter cannot be executed, ``run_console_decisions`` raises a ``CliError`` that names it.""" +def test_run_raises_cli_error_naming_an_interpreter_that_cannot_start(tmp_path: Path) -> None: + """When the console interpreter cannot be executed, ``run`` raises a ``CliError`` that names it.""" python = tmp_path / "not-executable" python.touch(mode=0o600) - enter_capsule(tmp_path, monkeypatch, python) with pytest.raises(CliError, match="cannot run the console's decision tools") as caught: - run_console_decisions(["check", "x.json"]) + capsule_tools(tmp_path, python).run(["check", "x.json"]) assert str(python) in str(caught.value) diff --git a/engineering-docs/decisions/product/d-0017-launcher-delivers-web-console-package.md b/engineering-docs/decisions/product/d-0017-launcher-delivers-web-console-package.md index 01f1a7f8..bd226d87 100644 --- a/engineering-docs/decisions/product/d-0017-launcher-delivers-web-console-package.md +++ b/engineering-docs/decisions/product/d-0017-launcher-delivers-web-console-package.md @@ -119,7 +119,7 @@ Adopt **Option A** (`launcher-package`) and **Option 1** (`source-or-opt-in`): 3. The base image continues to provide `/opt/devcapsule-webconsole/venv` and a baseline console copy. Inside the capsule, the runtime supervisor and `project checkout decisions` select the console package by one rule, - `console_package_path` in `devcapsule/container_runtime/console.py`, in + `ConsoleInstallation.package_path` in `devcapsule/container_runtime/console.py`, in precedence order: an explicit checkout `console.source_path`, otherwise `/opt/devcapsule/webconsole` when present, otherwise the base image's `/opt/devcapsule-webconsole` copy. Compatibility with the base interpreter From 60e455af5f7b0642c3b54a324a940419bc2c2ca3 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 01:00:59 +0000 Subject: [PATCH 09/75] Record the rewrite of PR #26: host inputs as values, no touched test patches The maintenance status gains the section of 2026-11-12: the owner's direction, what each unit became, the refurbishment of the legacy file that rule 5 required, the planted-fault account with its losses, the validation in the capsule, four judgments and three proposals. The section of 2026-11-11 is marked superseded in part. The rewrite has not been reviewed by the partner. Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 154 +++++++++++++++++- 1 file changed, 153 insertions(+), 1 deletion(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 9cc32cc8..4c39f379 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches, the rewrite not yet reviewed by the partner Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d92bdcbb0a01 @@ -16,8 +16,160 @@ Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selecti Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## PR #26 rewritten: host inputs are values, and no touched test patches — 2026-11-12 + +On 2026-11-11 the owner read the first judgment of the section below and +rejected its premise. The direction, in the owner's words: a value that an +inner module would be patched to supply, an environment variable for example, +"should have been a parameter at construction"; "only a very top layer does +the mapping", in a declarative style, with at most a small convenience method +that is obviously right; the inner module is "unaware that the value comes +from an OS env var"; a unit test "simply needs to construct regular values"; +and classes exist "to bind values that are used again and again". The owner +then asked for PR #26 to be rewritten on those lines, with lessons and rules +to follow from the result. This section records the rewrite. It supersedes +judgments 1 to 3 of the section below; the product code of that section is +replaced, not kept beside the new one. + +**Delivery.** The same branch and pull request, +`ws-maintenance/host-inputs-at-source` and +[PR #26](https://github.com/mycodespace-ai/devcapsule/pull/26). + +**The product code.** + +- `container_runtime/identity.py`: `CapsuleUser(identity, caller_uid)` + replaces `foreground_command`. `command` wraps a child's command behind + `gosu` for a root caller. `owner_changes` returns the `(path, uid, gid)` + changes that give new directories to the capsule user. Nothing in the + module reads the operating system. +- `container_runtime/filesystem.py`: `create_directories(plan)` creates the + directories and returns the ones it created. `prepare_filesystem(plan, user)` + performs the owner changes `CapsuleUser.owner_changes` decides, in a loop + with no branch. `RUNTIME_ROOT`, added on 2026-11-11 so a test could patch + it, is removed. +- `container_runtime/console.py`: `ConsoleInstallation(python, launcher_source)` + holds the two image paths; `package_path` and `child` are its methods and + replace `console_package_path` and `console_child`. `of_image()` builds the + one at the image's fixed paths. `probe_address` is a public function. +- `container_runtime/session.py`, new: `Session(plan, job, user, console)` + decides everything `run` used to decide inline: the filesystem plan, the + surface's launch with the files and variables it needs, the variables to + set given the existing ones, whether the contained display is shown, + whether the JetBrains profile lock is held, the log settings, and the + children in start order with their log files. +- `container_runtime/entrypoint.py`: `run` reads `os.geteuid()` and + `os.environ` once, builds the session, and performs its answers in + sequence. `log_rotation` and `logged_children` moved into `Session`. +- `console_tools.py`: `DecisionTools(in_capsule, console, runtime_plan_path)` + with `command` and `run` replaces the two functions and their four optional + parameters. `CheckoutDecisionsCommand.run` reads the environment variable + and names the image's paths. +- `build_info.py`: `distribution_build_info(package_locations, pyproject_path, + installed_version)` and `embedded_build_info(package_locations)` take every + location as a value; `installed_version` is a function, asked only when + needed, as before. `current_build_info()` and `is_built_distribution()` + take no argument and name the running distribution's locations. The record's + file name is inside the tested function. `build_info_text` is the text + form `version` prints. + +**The tests.** The mirror files of these units, and the three integration +files, hold no `monkeypatch` use; the files held 26 before. A test builds a +`CapsuleUser`, a `ConsoleInstallation` over files in its own directory, or a +`Session`, and asserts on what the call returns. + +- The readiness probe is tested against a real socket on loopback. The 0.2 + second timeout, which only a stand-in connection could observe, is no longer + asserted. +- `run`, `VersionCommand.run` and `CheckoutDecisionsCommand.run` have no + mirror test. Three integration files start the real programs in a process + whose environment the test builds: a headless session and an interactive + one with a stand-in program where the IDE is installed, `devcapsule version`, + and `project checkout decisions`. +- `tests/unit/devcapsule/commands/test_version.py` is deleted: its two tests + patched `current_build_info`, and the text and JSON forms are now tested on + `build_info.py`. + +**Rule 5.** `tests/test_runtime_entrypoint.py` called `foreground_command` +and `prepare_filesystem` with their old signatures and patched +`identity.os.geteuid`. The whole file is refurbished: its 22 tests are in +the mirrors of `contract`, `filesystem`, `identity`, `session`, `entrypoint`, +`graphics` and `components/jetbrains`, and the file is deleted. `graphics.py` +and `components/jetbrains.py` declare `__all__` for that. The convention +check counts 102 legacy files and 1350 legacy tests, from 103 and 1372, with +0 breaches. Two consequences outside the mirror: + +- `tests/test_contained_display.py`, legacy, imported three helpers from the + deleted file. They are now defined in it, and its fixture patches + `entrypoint.os.geteuid`. No test function of the file changed. +- `tests/conftest.py` patched `console.LAUNCHER_CONSOLE_SOURCE` for every + test. No unit test reads that constant through an entry layer any more, so + the patch is removed. + +`tests/test_vscode_component.py` and `tests/test_eclipse_component.py`, +legacy, still call `run` under their own patches and pass unchanged. + +**Evidence.** 43 faults were planted one at a time in a scratch copy: the 26 +of 2026-11-11, placed where the same decision lives now, and 17 more in the +performing layer and the session. + +| Caught by | Of the first 26 | Of all 43 | +| --- | --- | --- | +| the mirror files, which patch nothing | 19 | 26 | +| legacy unit files that reach `run` under patches | 2 | 4 | +| the integration files | 2 | 8 | +| nothing | 3 | 5 | + +The hosted pull-request gate runs the first two rows: 21 of the first 26, +where the patched tests of 2026-11-11 caught 25. The five that no test +catches: + +- the readiness probe's timeout made a hundred times longer, and removed; +- `checkout decisions` dropping its arguments, which shows only where the + image has a console; +- the uid and gid swapped in the one `os.chown` call, which runs only for root; +- the stamped record looked for outside the package, which shows only in a + built executable. + +**Validation, in the capsule.** `nox -s tests`: 17 failed, 2959 passed; the +17 are the standing ones of the blocking bug, the same test for test as +before the rewrite. `nox -s typecheck smoke pex docs-contract`: all pass, +mypy over 341 files. The integration tests that need no Docker: 116 passed, +3 skipped, 1 failed; the failure is in `test_pex_runtime.py`, which runs the +existing `dist/devcapsule-local.pex` and finds the capsule's trust already +accepted, the family of the blocking bug. Not run: `nox -s webconsole`, the +end-to-end sessions, `nox -s build` as one session. + +**Judgments taken for the owner.** + +1. A lazy input stays lazy: `installed_version` is passed as a function, so + a built executable does not read its installed metadata on every start. +2. `run` keeps its signature and stays the layer that reads the host. Two + legacy files therefore keep passing without an edit; the alternative was + to refurbish 644 more lines of unrelated component tests in this change. +3. The command classes are not given a constructor. The framework calls them + as classes; changing that is a change to every command. +4. `display.py` and `diagnose.py` still read `os.geteuid`, a fixed socket + directory and `CONSOLE_PYTHON` themselves. They were not in PR #18. + +**Proposals, not implemented.** + +- Run the integration tests that need no Docker in the hosted pull-request + gate. Three of the files are the only tests of the layer that reads the + host, and they take five seconds. +- Give the command framework a context that `cli.main` builds from the + process, so a command reads `context.environ` and a test passes one. +- Apply the same change to `display.py`, whose legacy tests patch three names. + +**Review.** The rewrite has not been reviewed by the partner. PR #27 reviewed +the code this section replaces. + +**Next action.** The owner reads PR #26; lessons and a rule for *Unit Tests* +follow from that reading, on the owner's word. + ## PR #18's test-only parameters removed; the tests set the host at its source — 2026-11-11 +Superseded in part on 2026-11-12: the product code and judgments 1 to 3 of this section are replaced by the section above. + On 2026-11-10 the owner asked for an independent assessment of [PR #18](https://github.com/mycodespace-ai/devcapsule/pull/18), then asked for its shortcomings to be fixed, by Pair Review with Codex and GPT-6 Astra From 7ed906c9155aa9cf4bebbcd47ecadb05b86d7af8 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 02:04:03 +0000 Subject: [PATCH 10/75] Workflow: Host Inputs rule, its companion, and the brief for the review of PR #26's rewrite Add the section Host Inputs to WORKFLOW-LOCAL.md, on the owner's word of 2026-11-12: only an entry layer reads the host, inner modules take values in required arguments, frozen dataclasses bind shared values, decisions return data, new and changed unit tests patch nothing, entry layers are tested as programs, and the pull request states what the hosted gate no longer catches. - WORKFLOW-LOCAL-humane.md: the companion paragraph, with the rewrite of PR #26 as the worked example and its cost in planted faults. - engineering-docs/development/unit-tests.md: the convention summary names the rule and test_session.py as the model. - engineering-docs/development/review-partner-loop.md: the brief template gains the reviewer's duty under rule 7. - evidence/2026-11-12-host-inputs-as-values/review-brief.md: the brief for the Codex + GPT-6 Astra pair, PR26.2. Evidence: nox -s docs-contract passes, 249 pages. Co-Authored-By: Claude --- WORKFLOW-LOCAL-humane.md | 51 ++++ WORKFLOW-LOCAL.md | 33 +++ .../development/review-partner-loop.md | 6 + engineering-docs/development/unit-tests.md | 7 + .../review-brief.md | 270 ++++++++++++++++++ 5 files changed, 367 insertions(+) create mode 100644 engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-12-host-inputs-as-values/review-brief.md diff --git a/WORKFLOW-LOCAL-humane.md b/WORKFLOW-LOCAL-humane.md index 7fb5308c..4fcd3906 100644 --- a/WORKFLOW-LOCAL-humane.md +++ b/WORKFLOW-LOCAL-humane.md @@ -262,6 +262,57 @@ process. Git on a scratch repository can pass both, and even then its commit dates come from the clock unless the test sets them. A Docker build passes neither. +## Host Inputs + +**Rule.** Only the top layer of a program reads the host: the environment, +the user, the clock, the network, other programs, the paths the code knows +by name. It hands what it read to the modules below as ordinary values, and +they require them. A class binds the values that are used again and again, +and its constructor only stores them. A module decides and returns what +should happen; the top layer makes it happen. A unit test therefore builds +values, calls the unit and looks at the answer, and patches nothing. The +top layer stays a few plain statements, and an integration test runs it as +the real program. The pull request says what the hosted gate stopped +catching, and the reviewer checks all of this. + +**Intended effect.** An inner module does not know that a value came from +an environment variable, so no test needs to set that variable or to +replace `os.getenv` to reach it. A test reads as a table of inputs and +outputs. It cannot leak into the next test, because it changed nothing +that the next test shares. It survives a refactoring of how the unit reads +its inputs, because the unit no longer reads them. The part of the code +that can only be tested with the real host is small enough to read in one +screen and is tested as a program. + +**Motivation.** PR #18 retired four legacy test files and, to keep its new +tests from patching the package, gave eight production signatures twenty +keyword parameters that no production caller passed. Every test passed the +parameter, so no test ran the default, which is the branch a release ships. +The first version of PR #26 removed the parameters and patched each host +input where the code read it, with `monkeypatch`, twenty-six times. The +owner rejected both on 2026-11-11: a patch changes a global for the length +of a test and ties the test to how the unit reads its input, and a +parameter with a host-reading default hides the same global behind a +signature. The direction was the one Haskell forces and Spring came to +late: a dependency is a value passed at construction, and only a very top +layer, written declaratively, maps the host to those values. When the +agent proposed to forbid classes made only to have a constructor, the +owner corrected it: Python has no functors, and a class is how values that +are used again and again get bound. The rewrite of PR #26 is the worked +example. `CapsuleUser`, `ConsoleInstallation`, `Session` and +`DecisionTools` bind the values; `entrypoint.run` reads `os.geteuid()` and +`os.environ` once and performs what the session answers; the list of owner +changes that a test used to record from a patched `os.chown` is now the +return value of `CapsuleUser.owner_changes`. The touched test files went +from twenty-six `monkeypatch` uses to none. The cost is stated because it +is real: of the twenty-six faults planted in the first version, the hosted +unit gate caught twenty-five with patches and catches twenty-one without; +integration tests that the hosted gate does not run catch two more, and +three are caught by nothing. That is why rule 7 asks for the statement and +why the entry layer must stay small. A value that is costly to read, the +installed version for instance, is passed as a function so that the top +layer does not pay for it on every start. + ## Reasoning And Code Navigation **Rule.** Start from the contract, state the uncertainty, navigate from the diff --git a/WORKFLOW-LOCAL.md b/WORKFLOW-LOCAL.md index d92bdcbb..d0a57143 100644 --- a/WORKFLOW-LOCAL.md +++ b/WORKFLOW-LOCAL.md @@ -235,6 +235,39 @@ capsule for reasons that were not bugs. 1 to 4 on every new or changed test, and to name for each what would make it fail for a reason that is not a bug. +## Host Inputs + +Owner direction, 2026-11-11, after one pull request gave tests their host +inputs through parameters that only tests passed, and the next through +patches. + +1. Only an entry layer reads the host. An entry layer is a `main` function, + a command's `run`, or the one function that such a layer calls first. + The host is all that code can read without an argument: the environment, + the caller's user, the clock, the network, another program, and a path + that the code names itself. +2. Every other module takes these as values, in required arguments. Give no + parameter a default that reads the host. Add no parameter that only a + test passes. Pass a value that is costly to read as a function without + arguments. +3. Bind the values that several operations share in a frozen dataclass. Its + constructor stores them and does nothing else. +4. Separate each decision from its effect. Write the decision as a function + of values that returns what to do. Let the entry layer do what it + returns. +5. A new or changed unit test builds values, passes them and asserts what + comes back. Do not use `monkeypatch` or `unittest.mock`. Do not assign + to an attribute of a module or a class, or to `os.environ`. A file under + `tmp_path` and a socket that the test opens on loopback are values. This + narrows *Unit Tests*, rule 2: such a test sets a host input only by + passing it. +6. Keep an entry layer a short sequence of statements that takes no + decision of its own. Test it with an integration test that starts the + real program in an environment that the test builds. +7. State in the pull request what the hosted gate does not catch after the + change. In a Pair Review Loop, the brief instructs the reviewer to + verify rules 1 to 6 on the changed code and its tests. + ## Reasoning And Code Navigation 1. Start with the behavior's contract: ownership, inputs, preconditions, diff --git a/engineering-docs/development/review-partner-loop.md b/engineering-docs/development/review-partner-loop.md index 5d73637d..556485a1 100644 --- a/engineering-docs/development/review-partner-loop.md +++ b/engineering-docs/development/review-partner-loop.md @@ -128,6 +128,12 @@ Improve it on your branch, focused on exactly three things, in this order: postcondition; its docstring states the contract. For each, name what would make it fail for a reason that is not a bug. A finding here is a finding; "confined to tests" does not dismiss it. +5. The changed code and its tests against *Host Inputs* in + `WORKFLOW-LOCAL.md`, rules 1 to 6: name every read of the host outside + an entry layer, every parameter default that reads it, every parameter + that only a test passes, every constructor that does more than store, + every decision taken inside an entry layer, and every patch in a new or + changed test. Stay inside the PR's scope: . Do not change . Do not widen ; if you believe it is wrong, diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index fa32de23..9a3f174f 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -16,6 +16,13 @@ place or shrunk one function at a time, and touching one, or adding, changing or deleting a test in a `tests/unit/` file of the same name, retires the entire legacy file into the mirror. +*Host Inputs* in the same file binds new and changed tests further: only an +entry layer reads the host, the modules below it take what it read as +required values, and a unit test builds those values and patches nothing. +`tests/unit/devcapsule/container_runtime/test_session.py` is the model: no +`monkeypatch`, and every host input a constructor argument. The entry +layers are tested as programs; see [Integration tests](integration-tests.md). + ## Running them ```text diff --git a/engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-12-host-inputs-as-values/review-brief.md b/engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-12-host-inputs-as-values/review-brief.md new file mode 100644 index 00000000..7df3b5b5 --- /dev/null +++ b/engineering-docs/wip/2026-09-18-maintenance/evidence/2026-11-12-host-inputs-as-values/review-brief.md @@ -0,0 +1,270 @@ +# Review brief for the Codex + GPT-6 Astra pair: PR26.2 on the rewrite of PR #26 with host inputs as values + +The Claude Code + Claude Fable 5.2 pair rewrote PR #26 on the branch +`ws-maintenance/host-inputs-at-source`, targeting `release-0.3.1`. Your pair +reviewed the first version as PR #27 (PR26.1), which was merged. The owner +then rejected that design. Commit `60cab937` replaces it, and the next +commits add the rule the owner asked for, *Host Inputs* in +`WORKFLOW-LOCAL.md`. No review of the rewrite exists. Your job is one +improvement pull request, PR26.2, against +`ws-maintenance/host-inputs-at-source`. + +## Your checkout + +You are in the git worktree at `/home/devcapsule/worktrees/maintenance-review`, +on the branch `ws-maintenance/host-inputs-at-source-review-2`, branched from +`ws-maintenance/host-inputs-at-source`. Work only there. Do not touch the +implementor's checkout at `/workspace/301e4208ef81-ChatGPT_Codex`, and run no +test there. + +Read first, in this order: + +1. `AGENTS.md`, `WORKFLOW.md` topic 9.11, `WORKFLOW-LOCAL.md` (*Unit Tests* + rules 1 to 7, *Host Inputs* rules 1 to 7, *Pair Review Loop In This + Checkout*, *Commit Authorship*), `WORKFLOW-LOCAL-humane.md` (*Unit Tests* + and *Host Inputs*). +2. `engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md`, the + section "PR #26 rewritten: host inputs are values, and no touched test + patches — 2026-11-12". It holds the direction, the evidence table of 43 + planted faults, the four judgments taken for the owner and the proposals + not implemented. +3. `engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md`. + It explains the 17 unit tests that fail in this capsule on every branch. +4. `devcapsule-src/devcapsule/container_runtime/session.py` and + `entrypoint.py`. Their module docstrings are the contract of the largest + change. + +## GitHub CLI + +In every shell that uses `gh`, first execute: + + . /opt/xtras/miniconda3/etc/profile.d/conda.sh && conda activate gh + +Then `gh` is logged in to github.com as the owner's account. Pass +`-R mycodespace-ai/devcapsule` to every `gh` command. Do not edit `.bashrc` +or any shell profile. + +## Validation environment + +Your worktree's `devcapsule-src/.venv` exists. Run everything from +`devcapsule-src`. These are the commands, verbatim: + + DEVCAPSULE_DIFF_BASE=origin/release-0.3.1 .venv/bin/python -m nox -s typecheck + .venv/bin/python -m pytest --no-cov -q tests/unit/devcapsule/container_runtime tests/unit/devcapsule/test_console_tools.py tests/unit/devcapsule/test_build_info.py + .venv/bin/python -m pytest --no-cov -q -m integration tests/integration/test_console_decisions_cli.py tests/integration/test_version_cli.py tests/integration/test_runtime_entrypoint_cli.py + .venv/bin/python -m pytest --no-cov -q tests/test_contained_display.py tests/test_eclipse_component.py tests/test_vscode_component.py tests/test_runtime_diagnose.py + DEVCAPSULE_DIFF_BASE=origin/release-0.3.1 .venv/bin/python -m nox -s tests + +Facts of this capsule that you must know before you read a result: + +- `nox -s tests` ends with 17 failed here, on this branch and on + `release-0.3.1` alike. The bug record of item 3 names the six files and the + counts. A failure outside that list is a finding. Because of them + `nox -s build` cannot pass in this capsule; do not run it. The hosted run + is the authority for the whole unit suite. +- The hosted pull-request gate runs the unit suite only. It does not run a + test marked `integration`. The three integration files of this change run + in this capsule, by the third command, and in the release workflow. +- One unit test downloads 1.5 GB into its scratch under `/tmp`, a 2 GB + tmpfs. Run the unit session once, as the last command. Before it, run + `df -h /tmp`, and delete only the `/tmp/pytest-of-*/pytest-` directories + that your own earlier runs left. Use the default scratch: no `--basetemp`, + no `/opt/devcapsule-gate`, nothing under `/home/devcapsule`. +- Run commands in the foreground and one at a time. Two pytest sessions at + once collide in `/tmp`. +- You are inside a capsule: `DEVCAPSULE_CONTAINER_NAME` is set, + `/opt/devcapsule-webconsole`, `/etc/devcapsule/home` and `/ide-config` + exist. The hosted runner has none of them. A test that passes here for + that reason is the defect class this slice exists to remove. +- When you plant a fault, set `PYTHONDONTWRITEBYTECODE=1`. Without it a + same-size edit restored within a second leaves the faulty bytecode live. + +Read the hosted check of the head before you start and again before your +final report: + + gh pr checks 26 -R mycodespace-ai/devcapsule + +State its result in your pull request body. If it is red or pending when you +finish, say so in the first line of the body. + +Do not build images, start capsules or run the end-to-end sessions. + +## The task + +Review the diff of PR #26 against its base: + + gh pr diff 26 -R mycodespace-ai/devcapsule + +`git diff e401b825 HEAD` shows the rewrite against the version you reviewed. +The code of before PR #18 is at `b84b06e9^1`; `git show b84b06e9^1:` +shows any file as 0.3.0 shipped it. + +What the change does. The first version patched each host input where the +code read it. The rewrite removes the reads from the inner modules: + +- `container_runtime/identity.py`: `CapsuleUser(identity, caller_uid)`, with + `command` and `owner_changes`. +- `container_runtime/filesystem.py`: `create_directories` returns what it + created; `prepare_filesystem(plan, user)` performs the owner changes. +- `container_runtime/console.py`: `ConsoleInstallation(python, + launcher_source)`, with `of_image`, `package_path` and `child`; public + `probe_address`. +- `container_runtime/session.py`, new: `Session(plan, job, user, console)` + decides the filesystem plan, the launch, the environment, the display, + the profile lock, the log settings and the children. +- `container_runtime/entrypoint.py`: `run` reads `os.geteuid()` and + `os.environ`, builds the session and performs its answers. +- `console_tools.py`: `DecisionTools(in_capsule, console, runtime_plan_path)`; + `commands/project.py` builds it from the environment. +- `build_info.py`: `distribution_build_info` and `embedded_build_info` take + their locations as values; `build_info_text`; `commands/version.py` prints. +- The legacy file `tests/test_runtime_entrypoint.py` is refurbished whole + into mirror files and deleted. The mirror files and three integration + files hold no `monkeypatch` use. + +Improve it on your branch, focused on these five things, in this order. + +1. **Correctness of the new and modified lines.** + - Is a session the session of 0.3.0 in behaviour? Compare `entrypoint.run` + and `Session` with `b84b06e9^1:devcapsule-src/devcapsule/container_runtime/entrypoint.py`. + Account for every difference in the order of effects: the log + configuration, the directories and their owners, each update of + `os.environ`, the launch files, the display, the profile lock, the + supervisor. + - `Session.environment(existing)` merges the planned variables and the + graphics defaults. Does a variable the process already has still win or + lose exactly as before? Does the display's environment still arrive + after it? + - `Session` and its neighbours are frozen dataclasses with + `cached_property`. Is that sound here: no `slots`, no hash or equality + surprise, no cached value that should have been recomputed? + - `filesystem.RUNTIME_ROOT` is gone and the runtime directory is a literal + again. Is the path a real session gets the path of 0.3.0? + - `tests/conftest.py` no longer patches `console.LAUNCHER_CONSOLE_SOURCE`. + Can any test, legacy ones included, now reach this capsule's real + `/opt/devcapsule/webconsole` or `/opt/devcapsule-webconsole`? + - Does any caller still import a removed name: `foreground_command`, + `console_child`, `console_package_path`, `RUNTIME_ROOT`, `log_rotation` + or `logged_children` of `entrypoint`, `console_decisions_command`, + `run_console_decisions`? Look in `devcapsule/`, `scripts/`, + `noxfile.py`, `devcapsule-webconsole/`, `engineering-docs/` and every + test. + - Does `devcapsule version` print what 0.3.0 printed, with and without + `--json`, from a source checkout and from a built executable? +2. **Clarity of the new and modified lines.** The standard is "obviously no + deficiencies". Read `Session` as a stranger would: is every property's + name the question `run` asks, and is `run` a sequence a reader can check + against the module docstring line by line? +3. **Test coverage of the new and modified lines.** Plant faults of your own + in the touched production code and report which test catches each, and in + which tier: mirror, legacy unit, integration, none. Do not only repeat + the 43 of the status section. Five recorded faults are caught by nothing: + the readiness probe's timeout, twice; `checkout decisions` dropping its + arguments; the uid and gid swapped in the one `os.chown` call; the build + record looked for outside the package. Close each one you can close + without a patch and without a test-only parameter. Say for each of the + others why it cannot be closed that way. Every test must fail if the line + it covers is broken. Do not pad. +4. **Every new or changed test against *Unit Tests* in `WORKFLOW-LOCAL.md`.** + It lives in the mirror and names its unit; it establishes its own + precondition, calls one public operation and asserts a promised + postcondition; its docstring states the contract. For each, name what + would make it fail for a reason that is not a bug. Group tests that share + one pattern, and name every distinct cause. Ask in particular: + - The three integration files start real programs. Would any give another + result as root, on macOS, on the hosted runner of the release workflow, + outside a capsule, on a slow machine, or when two run at once? Name + every wait, port, signal and fixed path they depend on. + - The readiness tests open real sockets on loopback. Can another process + change their result? + - Which refactoring of a unit, with its behaviour unchanged, would turn a + mirror test red? + A finding here is a finding; "confined to tests" does not dismiss it. +5. **The changed code and its tests against *Host Inputs* in + `WORKFLOW-LOCAL.md`, rules 1 to 6.** The rule was written after the code. + Hold the code to it without mercy. Name every read of the host outside an + entry layer, every parameter default that reads it, every parameter that + only a test passes, every constructor that does more than store, every + decision taken inside an entry layer, and every patch in a new or changed + test. These deviations are known; judge each, and find the others: + - `build_info.current_build_info()` and `is_built_distribution()` take no + argument and read the package's own location. + - `ConsoleInstallation.of_image()` names two paths of the image. + - `entrypoint.run` branches twice on an answer of the session. + - The command classes read `os.environ` in `run`; the framework gives + them no constructor. + - The fixture of the legacy file `tests/test_contained_display.py` patches + `entrypoint.os.geteuid`. Its test functions did not change. + - `display.py` and `diagnose.py` read the host themselves. They are + outside this change. + Then review the rule itself, as an agent that must follow it tomorrow + with no other context. For each of the seven rules, say whether you + could act on it alone, and name each case in this code base where two + careful agents would read it differently. Put this under "On the rule" + in the pull request body. Do not edit the rule. + +Stay inside the scope: the modules listed above, their mirror tests, the +three integration files `tests/integration/test_console_decisions_cli.py`, +`test_version_cli.py` and `test_runtime_entrypoint_cli.py`, and the helpers +of `tests/test_contained_display.py`. Do not retire another legacy file. Do +not change `display.py`, `diagnose.py`, the command framework or the hosted +workflows. Do not change `WORKFLOW.md`, `WORKFLOW-LOCAL.md` or their +companions. Your own tests follow *Host Inputs* rule 5: no `monkeypatch`, +no `unittest.mock`, no assignment to a module or class attribute. + +The direction itself, host inputs as values and no patch, is the owner's +decision. If you believe a patch or a parameter was the better design at +one place, argue it under "Proposals not implemented" and do not put it +back. + +## What you must not do + +- Do not edit `CURRENT-STATUS.md` files, `intake-dispositions.md` or the + `evidence/` directory. Do not run `devcapsule workflow publish` or + `devcapsule0 workflow publish`. +- Do not commit the `website` submodule pointer, `.idea/` files, + `.devcapsule/` files, `*.egg-info`, `.nox/`, `dist/` or `__pycache__`. + Stage explicit paths; never `git add -A` or `git commit -a`. +- Do not merge anything. Do not push to `main`, `release-0.3.1`, + `ws-maintenance/host-inputs-at-source` or any branch other than + `ws-maintenance/host-inputs-at-source-review-2`. +- Do not rebase or force-push. Do not build images or run capsules. + +## Deliverable + +1. Commits on `ws-maintenance/host-inputs-at-source-review-2`. Keep the + human's author identity, `Costin Cozianu `; check it + with `git var GIT_AUTHOR_IDENT`. Each message names the component and the + evidence and ends, after a blank line, with your trailer as *Commit + Authorship* prescribes, for example + `Co-authored-by: GPT-6 Astra Codex `; read your + session's model identity and do not copy the example blindly. +2. Push the branch with + `git push -u origin ws-maintenance/host-inputs-at-source-review-2` and + open one pull request with + `gh pr create -R mycodespace-ai/devcapsule --base ws-maintenance/host-inputs-at-source --head ws-maintenance/host-inputs-at-source-review-2`. + Title: `Correctness, clarity and coverage review of the rewrite of #26 (PR26.2)`. + The body lists: + - the hosted check's result for the head you reviewed; + - each finding as: what was wrong or unclear, where, what you changed, how + a test proves it; + - your planted faults, each with the tier that catches it; + - per *Unit Tests* rule 7, for the new and changed tests, what would make + each fail for a reason that is not a bug; + - "Host Inputs, rule by rule": each deviation, judged; + - "On the rule"; + - "Considered and left alone, because"; + - "Proposals not implemented"; + - the result of each validation command, with counts, and what you did + not run. + If you change no file, still report: open no pull request, and print the + same sections as your final message. +3. Print the pull request's URL as the last line of your output, or `NO PR` + if you opened none. + +Write the body and your report at about 80% ASD-STE100: one fact per +sentence, about twenty words, active voice. Back every claim about behaviour +with a test or a command you ran. + +If you cannot proceed, because of a blocker like network or credentials, +stop and say exactly what blocked you. Do not work around a blocker. From 04770142f735d6b47cc78aacafdbf03d8c436661 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 02:34:10 +0000 Subject: [PATCH 11/75] Runtime: restore launch effect order and prove host-input boundaries Set launch variables only after writing launch files, as in 0.3.0. Use independent version and runtime-plan fixtures. Cover real ownership and decision argument forwarding, and state integration prerequisites. Twelve planted faults produced ten detected failures and two timeout gaps. Validation: 341 files typechecked; 157 mirror, 25 integration, and 69 legacy checks passed. The full unit run passed 2961 tests with the 17 known mounted-settings failures and no additional failures. Co-authored-by: GPT-6 Astra Codex --- .../container_runtime/entrypoint.py | 8 +- .../devcapsule/container_runtime/session.py | 16 ++-- .../integration/test_console_decisions_cli.py | 30 +++--- .../test_runtime_entrypoint_cli.py | 93 +++++++++++++++++-- .../tests/integration/test_version_cli.py | 79 +++++++++++----- .../container_runtime/test_console.py | 8 ++ .../container_runtime/test_contract.py | 21 +++-- .../container_runtime/test_session.py | 18 +++- 8 files changed, 205 insertions(+), 68 deletions(-) diff --git a/devcapsule-src/devcapsule/container_runtime/entrypoint.py b/devcapsule-src/devcapsule/container_runtime/entrypoint.py index 54b125bd..a0b0d26b 100644 --- a/devcapsule-src/devcapsule/container_runtime/entrypoint.py +++ b/devcapsule-src/devcapsule/container_runtime/entrypoint.py @@ -11,8 +11,11 @@ the plan carries a console section, the web console runs beside either; see ``console.py``. -What a session needs and which children it runs is decided in ``session.py``, -from values alone. This module reads the host and performs those decisions. +``session.py`` plans the session from its inputs, with console discovery +delegated to the installation. This module configures logs, prepares and owns +directories, sets session variables, writes launch files, then sets launch +variables. It prepares the display and sets its variables last. It assembles +children, takes the selected profile lock, and runs the supervisor. """ from __future__ import annotations @@ -69,6 +72,7 @@ def run(plan: RuntimePlan, job: tuple[str, ...] | None = None) -> int: os.environ.update(session.environment(os.environ)) for path, text in session.launch.files.items(): Path(path).write_text(text, encoding="utf-8") + os.environ.update(session.launch.environment) display_children: tuple[SupervisedChild, ...] = () if session.shows_contained_display: display = prepare_contained_display( diff --git a/devcapsule-src/devcapsule/container_runtime/session.py b/devcapsule-src/devcapsule/container_runtime/session.py index 53aff08c..a06d75d9 100644 --- a/devcapsule-src/devcapsule/container_runtime/session.py +++ b/devcapsule-src/devcapsule/container_runtime/session.py @@ -4,10 +4,9 @@ what it answers: the directories and variables the session needs, the files its surface reads, and the children to supervise in their start order. -Nothing here reads the process environment or the caller's uid, and nothing -here starts a program or writes a file. The one look at the host is -:meth:`Session.children` asking the console installation it was given whether -the image has a console. +Nothing here reads the process environment or the caller's uid, starts a +program or writes a file. ``children`` delegates console discovery to the +given installation. That operation checks its paths and can print a notice. """ from __future__ import annotations @@ -83,17 +82,16 @@ def launch(self) -> SurfaceLaunch: raise RuntimePlanError(f"unsupported component adapter: {adapter}") def environment(self, existing: Mapping[str, str]) -> dict[str, str]: - """The variables to set before any child starts, in a process that has ``existing``. + """The variables to set before preparing the surface, given ``existing``. - They are the session's paths, every component's variables and the - surface's own, a later one winning a name; then each graphics default - that neither ``existing`` nor those already decide. + The session's paths precede the components' variables. Graphics + defaults fill only unset names. The entrypoint sets ``launch.environment`` + separately, after writing the surface's files, as in 0.3.0. """ planned = { **self.filesystem.environment, **self.plan.component_environment(), - **self.launch.environment, } return {**planned, **graphics_environment({**existing, **planned})} diff --git a/devcapsule-src/tests/integration/test_console_decisions_cli.py b/devcapsule-src/tests/integration/test_console_decisions_cli.py index 96232cf6..0efe2465 100644 --- a/devcapsule-src/tests/integration/test_console_decisions_cli.py +++ b/devcapsule-src/tests/integration/test_console_decisions_cli.py @@ -2,9 +2,9 @@ What the command does inside a capsule depends on two fixed paths of the image, the console interpreter and the runtime plan, which a test cannot -build. ``tests/unit/devcapsule/test_console_tools.py`` covers those -decisions from values, and ``tests/e2e/test_console_answers.py`` runs the -command in a real capsule. +build. The forwarding case requires an installed console and skips when +one is absent. It checks a file under its own scratch and does not send +a decision or contact the console server. """ from __future__ import annotations @@ -16,6 +16,8 @@ import pytest +from devcapsule.container_runtime.console import ConsoleInstallation + pytestmark = pytest.mark.integration @@ -29,7 +31,7 @@ def checkout_decisions( ``container_name`` is given; nothing of the caller's environment. """ environment = { - "PATH": os.defpath, + "PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1", "HOME": str(tmp_path / "home"), "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "config"), } @@ -67,14 +69,16 @@ def test_cli_reports_outside_capsule_refusal_with_usage_exit_code( assert "runs inside a capsule" in completed.stderr -def test_cli_does_not_give_the_hosts_refusal_inside_a_capsule(tmp_path: Path) -> None: - """With a container name in the environment, the command gets past the refusal that belongs to a host. +def test_cli_forwards_the_check_subcommand_and_its_path(tmp_path: Path) -> None: + """With an installed console, the real command checks the named file and reports its invalid JSON.""" + if not ConsoleInstallation.of_image().python.is_file(): + pytest.skip("argument forwarding requires the image's console interpreter") + decision = tmp_path / "forwarded-argument.json" + decision.write_text("not JSON", encoding="utf-8") - What it does next depends on the image: without a console it names the - missing base, with one it runs the console's own ``check``. Either way - ``x.json`` is not checked, so it fails, and not with the host's words. - """ - completed = checkout_decisions(tmp_path, "check", "x.json", container_name="capsule-fixture") + completed = checkout_decisions(tmp_path, "check", str(decision), container_name="capsule-fixture") - assert completed.returncode != 0 - assert "runs inside a capsule" not in completed.stderr + assert completed.returncode == 2 + assert completed.stdout == "" + assert "forwarded-argument.json" in completed.stderr + assert "JSON" in completed.stderr diff --git a/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py index 2c369b27..7a090e14 100644 --- a/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py +++ b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py @@ -1,9 +1,9 @@ """Integration tests of the runtime entrypoint: real sessions, in a process whose environment the test builds. ``run`` is the layer that reads the process and acts on the host. These -tests start it as the program it is, with a plan whose every path lies under -the test's directory and a stand-in program where the IDE or the job would -be, and observe what that program was given and what the session left. +tests start it with private home, slot, log and launch paths, and a stand-in +IDE or job. The runtime directory remains the product's shared +``/tmp/devcapsule-runtime-``. These tests never remove that directory. """ from __future__ import annotations @@ -13,6 +13,7 @@ import os from pathlib import Path import stat +import signal import subprocess import sys from typing import Sequence @@ -70,7 +71,7 @@ def write_plan(tmp_path: Path, logs: dict[str, object]) -> Path: "version": 1, "project_path": str(tmp_path / "project"), "home": str(tmp_path / "home"), - "identity": {"uid": os.getuid(), "gid": os.getgid(), "user": "developer"}, + "identity": {"uid": os.geteuid(), "gid": os.getegid(), "user": "developer"}, "state_slots": [{"name": f"jetbrains/{name}", "path": str(tmp_path / "slots" / name)} for name in SLOTS], "component": { "id": "jetbrains", @@ -95,12 +96,14 @@ def run_entrypoint(tmp_path: Path, plan: Path, job: Sequence[str]) -> subprocess The process starts in ``tmp_path`` with a search path and one graphics setting, and nothing else of the caller's environment. """ - if os.getuid() == 0: + if not hasattr(signal, "sigwaitinfo") or not hasattr(signal, "sigtimedwait"): + pytest.skip("the capsule supervisor requires POSIX sigwaitinfo and sigtimedwait") + if os.geteuid() == 0: pytest.skip("root starts each child through gosu, which a test host need not have") return subprocess.run( [sys.executable, "-m", "devcapsule.container_runtime.entrypoint", str(plan), *(("--", *job) if job else ())], cwd=tmp_path, - env={"PATH": os.defpath, "LIBGL_ALWAYS_SOFTWARE": "0"}, + env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1", "LIBGL_ALWAYS_SOFTWARE": "0"}, capture_output=True, text=True, timeout=120, check=False, ) @@ -138,7 +141,7 @@ def test_the_job_runs_in_the_project_with_the_sessions_environment(tmp_path: Pat """The job starts in the plan's project and finds the session's home, runtime directory and properties variable in its environment.""" assert headless.directory == str(tmp_path / "project") assert headless.environment["HOME"] == str(tmp_path / "home") - assert headless.environment["XDG_RUNTIME_DIR"] == f"/tmp/devcapsule-runtime-{os.getuid()}" + assert headless.environment["XDG_RUNTIME_DIR"] == f"/tmp/devcapsule-runtime-{os.geteuid()}" assert headless.environment["PYCHARM_PROPERTIES"] == str(tmp_path / "idea.properties") @@ -194,3 +197,79 @@ def test_an_interactive_jetbrains_session_takes_the_profile_lock(tmp_path: Path, def test_a_headless_session_takes_no_profile_lock(tmp_path: Path, headless: FinishedSession) -> None: """With a job in place of the IDE, the session leaves no lock file in the profile.""" assert not (tmp_path / "slots" / "config" / ".devcapsule-session.lock").exists() + + +@pytest.mark.parametrize("failure", ["properties-is-directory", "unknown-adapter"]) +def test_session_variables_precede_launch_failure_but_launch_variables_do_not( + tmp_path: Path, failure: str, +) -> None: + """A failed launch leaves session variables set and preserves the previous properties variable, as in 0.3.0.""" + plan = write_plan(tmp_path, {"directory": str(tmp_path / "logs")}) + if failure == "properties-is-directory": + (tmp_path / "idea.properties").mkdir() + else: + document = json.loads(plan.read_text(encoding="utf-8")) + document["component"]["adapter"] = "unknown" + plan.write_text(json.dumps(document), encoding="utf-8") + program = """ +import json, os, sys +from devcapsule.container_runtime.contract import RuntimePlan, RuntimePlanError +from devcapsule.container_runtime.entrypoint import run +try: + run(RuntimePlan.from_file(sys.argv[1])) +except (OSError, RuntimePlanError): + print(json.dumps({key: os.environ.get(key) for key in + ('HOME', 'NO_AT_BRIDGE', 'PYCHARM_PROPERTIES')})) +else: + sys.exit('the launch unexpectedly succeeded') +""" + + completed = subprocess.run( + [sys.executable, "-c", program, str(plan)], cwd=tmp_path, + env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1", "HOME": "previous-home", "PYCHARM_PROPERTIES": "previous-properties"}, + capture_output=True, text=True, timeout=120, check=False, + ) + + assert completed.returncode == 0, completed.stderr + assert json.loads(completed.stdout) == { + "HOME": str(tmp_path / "home"), "NO_AT_BRIDGE": "1", "PYCHARM_PROPERTIES": "previous-properties", + } + + +def test_filesystem_applies_distinct_user_and_group_ids_to_new_directories(tmp_path: Path) -> None: + """The real chown gives new directories the requested uid and gid and leaves existing directory ownership intact.""" + uid = os.geteuid() + groups = [gid for gid in os.getgroups() if gid != uid] + if uid == 0: + gid = 1 + elif groups: + gid = groups[0] + else: + pytest.skip("distinct uid/gid ownership needs root or a supplementary group different from the uid") + existing = tmp_path.stat() + program = """ +import sys +from pathlib import Path +from devcapsule.container_runtime.contract import Identity +from devcapsule.container_runtime.filesystem import FilesystemPlan, prepare_filesystem +from devcapsule.container_runtime.identity import CapsuleUser +root = Path(sys.argv[1]) +plan = FilesystemPlan( + (str(root), str(root / 'home' / '.ssh'), str(root / 'runtime')), + {'HOME': str(root / 'home'), 'XDG_RUNTIME_DIR': str(root / 'runtime')}, +) +prepare_filesystem(plan, CapsuleUser(Identity(int(sys.argv[2]), int(sys.argv[3])), 0)) +""" + + completed = subprocess.run( + [sys.executable, "-c", program, str(tmp_path), str(uid), str(gid)], + cwd=tmp_path, env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1"}, + capture_output=True, text=True, timeout=120, check=False, + ) + + assert completed.returncode == 0, completed.stderr + for path in (tmp_path / "home", tmp_path / "home" / ".ssh", tmp_path / "runtime"): + actual = path.stat() + assert (actual.st_uid, actual.st_gid) == (uid, gid) + after = tmp_path.stat() + assert (after.st_uid, after.st_gid) == (existing.st_uid, existing.st_gid) diff --git a/devcapsule-src/tests/integration/test_version_cli.py b/devcapsule-src/tests/integration/test_version_cli.py index b0b7d7fc..d2f68845 100644 --- a/devcapsule-src/tests/integration/test_version_cli.py +++ b/devcapsule-src/tests/integration/test_version_cli.py @@ -1,45 +1,76 @@ -"""Integration tests of ``devcapsule version``: the real command line, in a process whose environment the test builds.""" +"""Run the version command from private source and stamped package layouts.""" from __future__ import annotations +import json import os from pathlib import Path +import shutil import subprocess import sys import pytest -from devcapsule.build_info import build_info_json, build_info_text, current_build_info - pytestmark = pytest.mark.integration -def version(tmp_path: Path, *arguments: str) -> subprocess.CompletedProcess[str]: - """Run ``devcapsule version`` in a new process with a search path, a home and a configuration home under ``tmp_path``.""" - environment = { - "PATH": os.defpath, - "HOME": str(tmp_path / "home"), - "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "config"), - } - return subprocess.run( - [sys.executable, "-m", "devcapsule", "version", *arguments], - cwd=tmp_path, env=environment, capture_output=True, text=True, timeout=120, check=False, +@pytest.fixture +def distribution(tmp_path: Path) -> Path: + """Copy the package without caches and give this source checkout its own authored version.""" + source = Path(__file__).resolve().parents[2] / "devcapsule" + shutil.copytree(source, tmp_path / "devcapsule", ignore=shutil.ignore_patterns("__pycache__", "_build_info.json")) + (tmp_path / "pyproject.toml").write_text( + '[project]\nname = "devcapsule"\nversion = "9.8.7"\n', encoding="utf-8", ) + return tmp_path -def test_version_json_prints_the_build_info_of_the_distribution_it_runs_from(tmp_path: Path) -> None: - """``version --json`` prints, as one JSON line, the build information of the distribution this test imports too.""" - completed = version(tmp_path, "--json") +def version(distribution: Path, *arguments: str) -> subprocess.CompletedProcess[str]: + """Start the real CLI with the private distribution first on its import path and a fresh environment.""" + return subprocess.run( + [sys.executable, "-m", "devcapsule", "version", *arguments], + cwd=distribution, + env={"PATH": os.defpath, "HOME": str(distribution / "home"), + "DEVCAPSULE_CONFIG_HOME": str(distribution / "config"), "PYTHONDONTWRITEBYTECODE": "1"}, + capture_output=True, text=True, timeout=120, check=False, + ) - assert completed.returncode == 0 - assert completed.stdout == build_info_json(current_build_info()) + "\n" - assert completed.stderr == "" +@pytest.mark.parametrize("stamped", [False, True], ids=["source", "stamped-package"]) +@pytest.mark.parametrize("as_json", [False, True], ids=["text", "json"]) +def test_version_reports_the_running_distributions_record( + distribution: Path, stamped: bool, as_json: bool, +) -> None: + """Version prints the authored source identity or the package's stamp, in the requested format with one final newline.""" + expected = { + "schema_version": 2, + "version": "9.8.7", + "build_mnemonic": "v9.8.7-local", + "source_repository": "unknown", + "source_revision": "unknown", + "source_url": "unknown", + } + if stamped: + expected.update({ + "version": "1.2.3", "build_mnemonic": "v1.2.3", + "source_repository": "https://github.com/example/fixture", + "source_revision": "a" * 40, + "source_url": "https://github.com/example/fixture/commit/" + "a" * 40, + }) + (distribution / "devcapsule" / "_build_info.json").write_text(json.dumps(expected), encoding="utf-8") + # A record beside the package must never take precedence over the package's own record or source identity. + (distribution / "_build_info.json").write_text('{"wrong-location": true}', encoding="utf-8") -def test_version_prints_the_build_info_as_text_without_the_flag(tmp_path: Path) -> None: - """``version`` prints the same build information as the four lines a person reads.""" - completed = version(tmp_path) + completed = version(distribution, *(("--json",) if as_json else ())) - assert completed.returncode == 0 - assert completed.stdout == build_info_text(current_build_info()) + "\n" + assert completed.returncode == 0, completed.stderr + if as_json: + assert completed.stdout == json.dumps(expected, sort_keys=True, separators=(",", ":")) + "\n" + else: + assert completed.stdout == ( + f"DevCapsule {expected['build_mnemonic']} (package {expected['version']})\n" + f"Source repository: {expected['source_repository']}\n" + f"Source revision: {expected['source_revision']}\n" + f"Source URL: {expected['source_url']}\n" + ) assert completed.stderr == "" diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py index e6e11f2a..16630570 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py @@ -233,3 +233,11 @@ def test_child_is_not_ready_while_nothing_listens_on_its_port(tmp_path: Path) -> ready = child.ready() assert ready is False + + +def test_package_path_ignores_a_directory_named_like_the_package_initializer(tmp_path: Path) -> None: + """A directory named __init__.py is not an installed launcher package; the base remains selected.""" + installation = base_installation(tmp_path) + (installation.launcher_source / "devcapsule_webconsole" / "__init__.py").mkdir(parents=True) + + assert installation.package_path("") == "" diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py index 11833088..d8531239 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py @@ -9,7 +9,6 @@ import pytest -from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.container_runtime.contract import ( ComponentRuntimeTemplate, ConsolePlan, @@ -56,13 +55,14 @@ def tool_template(*slots: dict[str, object]) -> dict[str, object]: def base_runtime_document(tmp_path: Path) -> dict[str, object]: """Construct a valid ``RuntimePlan`` mapping rooted under ``tmp_path``.""" - plan = RuntimePlan.for_component( - pycharm_runtime_template(), - project_path="/workspace/project", - home=str(tmp_path / "home"), - identity=Identity(1000, 1000, "developer"), - ) - return plan.to_mapping() + return { + "version": 1, + "project_path": "/workspace/project", + "home": str(tmp_path / "home"), + "identity": {"uid": 1000, "gid": 1000, "user": "developer"}, + "component": {"id": "fixture", "adapter": "fixture", "configuration": {}}, + "state_slots": [{"name": "fixture/config", "path": str(tmp_path / "config")}], + } def test_runtime_plan_round_trips_console_section_with_and_without_source_path(tmp_path: Path) -> None: @@ -150,8 +150,9 @@ def test_runtime_plan_parses_a_versioned_document(tmp_path: Path) -> None: assert plan.identity == Identity(1000, 1000, "developer") assert plan.home == str(tmp_path / "home") - assert plan.component.adapter == "jetbrains" - assert plan.slots_by_name()["pycharm/config"] == "/ide-config" + assert plan.component.adapter == "fixture" + assert plan.state_slots[0].name == "fixture/config" + assert plan.state_slots[0].path == str(tmp_path / "config") def test_component_template_parses_its_persistence_declaration() -> None: diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py index 0ec2af88..8dca04b0 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py @@ -174,10 +174,10 @@ def test_launch_refuses_a_component_whose_adapter_the_runtime_does_not_know(tmp_ session.launch -def test_environment_sets_the_session_paths_every_components_variables_and_the_surfaces_own( +def test_environment_sets_session_paths_and_component_variables_before_the_launch( tmp_path: Path, ) -> None: - """``environment`` carries the home and runtime directory, an ancillary component's variable, and the surface's properties variable.""" + """``environment`` sets session paths and component variables; launch variables wait until their files are written.""" document = jetbrains_document(tmp_path) document["ancillary_components"] = [ { @@ -194,7 +194,7 @@ def test_environment_sets_the_session_paths_every_components_variables_and_the_s assert environment["HOME"] == str(tmp_path / "home") assert environment["XDG_RUNTIME_DIR"] == "/tmp/devcapsule-runtime-1000" assert environment["CODEX_HOME"] == str(tmp_path / "codex-home") - assert environment["PYCHARM_PROPERTIES"] == str(tmp_path / "idea.properties") + assert "PYCHARM_PROPERTIES" not in environment def test_environment_supplies_the_graphics_defaults_a_process_does_not_have(tmp_path: Path) -> None: @@ -432,3 +432,15 @@ def test_log_rotation_is_the_default_when_the_plan_carries_none( assert session_of(document, image_without_console(tmp_path)).log_rotation == ( logs.MAXIMUM_SEGMENT_BYTES, logs.ROTATIONS, ) + + +def test_environment_gives_component_paths_precedence_over_session_and_process_paths(tmp_path: Path) -> None: + """Component variables override both the planned home and the caller's home; empty graphics values stay explicit.""" + document = jetbrains_document(tmp_path) + document["component"]["environment"] = {"HOME": "/component-home"} # type: ignore[index] + session = session_of(document, image_without_console(tmp_path)) + + environment = session.environment({"HOME": "/caller-home", "LIBGL_ALWAYS_SOFTWARE": ""}) + + assert environment["HOME"] == "/component-home" + assert environment["LIBGL_ALWAYS_SOFTWARE"] == "" From 314cbe4db63f39986467939548febdfc5ba71ff2 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 02:52:58 +0000 Subject: [PATCH 12/75] Record the Host Inputs rule and the partner's review of PR #26's rewrite Maintenance status: a new section with the rule, what PR #28 changed, the one remaining difference from 0.3.0, the deviations from the rule in the merged code, and the seven places where the reviewer found the rule open to two readings, for the owner's ruling. Loop record: the 2026-11-12 row. Evidence: nox -s tests on 83d238b8 in the capsule, 17 failed (the standing ones), 2961 passed; convention check 102 legacy files, 1350 legacy tests, 53 conforming, 0 breaches. Co-Authored-By: Claude --- .../development/review-partner-loop.md | 1 + .../2026-09-18-maintenance/CURRENT-STATUS.md | 113 +++++++++++++++++- 2 files changed, 109 insertions(+), 5 deletions(-) diff --git a/engineering-docs/development/review-partner-loop.md b/engineering-docs/development/review-partner-loop.md index 556485a1..61e7a9c9 100644 --- a/engineering-docs/development/review-partner-loop.md +++ b/engineering-docs/development/review-partner-loop.md @@ -305,6 +305,7 @@ when the workstream pauses, and say so in its open threads. | Date | Workstream | Implementor | Review partner | Slices and reviews | Outcome | |---|---|---|---|---|---| +| 2026-11-12 | maintenance, the rewrite of PR #26 with host inputs as values and no patch in a touched test (`0.3.1`) | Claude Code, Claude Fable 5.2 pair | Codex, gpt-6-astra (high) pair | #26/#28 | accepted at `04770142` without a round, merged at `83d238b8`; the first loop whose brief holds the code to *Host Inputs* and asks the reviewer to review the rule itself, as an agent that must follow it with no other context; the reviewer restored 0.3.0's order of launch file and launch variable, replaced two integration oracles that repeated the implementation, proved the real owner change by passing the caller's uid as a value, and closed three of the implementor's five uncaught faults with integration tests and no patch; its "On the rule" table named seven places where two agents would read the rule differently, recorded in the `maintenance` status for the owner's ruling; 12 planted faults of its own, 4 caught by mirror tests, 1 by a legacy unit test, 5 by integration tests, 2 by nothing; the capsule's 17 standing failures unchanged; brief committed under `evidence/2026-11-12-host-inputs-as-values/review-brief.md` | | 2026-11-11 | maintenance, PR #18's test-only parameters removed and the tests set the host at its source (follow-up to #18, `0.3.1`) | Claude Code, Claude Fable 5.2 pair | Codex, gpt-6-astra (high) pair | #26/#27 | accepted at `1b5d3fc7` without a round, merged at `60ad2c5a`; the first loop whose brief asks for the hosted check's result and names the capsule's standing unit failures, and whose review started only on a green hosted run; the reviewer corrected a docstring that claimed more than the launcher enforces, ended each process-wide test patch with its action, read the session environment when the supervisor is made, replaced an expected value derived from the constant under test, and added a test of the default build-record lookup that the implementor had recorded as impossible; 13 planted faults of its own and 25 of the implementor's 26 caught by the unit files, the last by the integration file; GitHub runs no check on a pull request into a slice branch, so the hosted run of #26 after the merge is the one that counts; the capsule's 17 standing failures keep `nox -s build` from passing as one session, its parts were run one by one; four proposals recorded in the `maintenance` status; brief committed under `evidence/2026-11-11-host-inputs-at-source/review-brief.md` | | 2026-11-08 / 2026-11-09 | maintenance, launcher-delivered web console (`D-0017`, 0.3.1 candidate 2 blocker, stacked on #18) | Antigravity, Gemini 4 Argon (High) pair | Claude Code, Claude Fable 5.1 pair | #16/#17 | accepted at `e23e22c7` without a round, merged at `9919f4ce`, and rebased onto PR #18 (`ws-maintenance/webconsole-legacy-tests`) per owner decision `stacked-delivery-branch = force-push-pr-16`; the reviewer removed the dead per-start `import psutil` subprocess probe (`WEBCONSOLE_RECIPE` 11 settles compatibility on the host) and unified console package precedence in `console_package_path`, fixed `extract_webconsole_bundle` to mask `external_attr >> 16` with `S_IFMT` so typeless regular zip entries (`ZipFile.writestr`) extract, pinned `match=` on every bundle refusal test (99% bundle coverage), tightened `DEVCAPSULE_DEV_WEBCONSOLE` to `1`/`true`/`0`/`false`, and aligned `D-0017` and the bug record; stacked gate 2904 unit tests, 40 integration (3 skipped), 458 webconsole, 332 mypy files, 104 legacy / 44 conforming files with 0 breaches, 249 contract pages, plus live base-Python HTTP check; remaining unimplemented proposals recorded in `maintenance` status; brief committed under `evidence/2026-11-08-webconsole-delivery/review-brief.md` | | 2026-11-09 | maintenance, whole-file legacy test retirement and 4-file refurbishment (`0.3.1` prerequisite) | Antigravity, Gemini 4 Argon (High) pair | Claude Code, Claude Fable 5.1 pair | #18/#19 | accepted at `4aac5dfc` without a round, merged at `a1aad17f`; completed `__all__` in `console.py`, `entrypoint.py` and `materialization.py`, dropped a dead `subprocess` import in `project.py`, stated basename pairing and mirror test deletion refusal across rule 5, the companion, the developer guide and the checker with 4 new checker tests, proved `entrypoint.run` writes session variables only into the supplied `environ`, and restored interpreter-path matching in `test_console_tools.py`; hosted CI on `e301367d` caught `/ide-config` state-slot paths in `test_entrypoint.py` (masked inside the PyCharm capsule), resolved by confining `make_plan` to `tmp_path` and injecting `runtime_root`, `caller_uid`, and `configure_logs` across `filesystem.py`, `identity.py`, and `entrypoint.run` (`test_filesystem.py` added, implementing PR #19's third proposal with zero global state); gate 2842 unit, 36 integration (1 skipped), 458 webconsole, 330 mypy files, 104 legacy / 43 conforming files with 0 breaches, 249 contract pages; two remaining proposals recorded in `maintenance` status; brief committed under `evidence/2026-11-08-webconsole-legacy-tests/review-brief.md` | diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 4c39f379..a80a26c9 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches, the rewrite not yet reviewed by the partner +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d92bdcbb0a01 @@ -16,6 +16,108 @@ Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selecti Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## The rule *Host Inputs*, and the partner's review of the rewrite — 2026-11-12 + +After reading the report of the section below, the owner asked for "a very +simple set of rules that reflect what you did", and then for the Codex +review. + +**The rule.** Commit `7ed906c9` adds the section *Host Inputs* to +`WORKFLOW-LOCAL.md`, seven rules: only an entry layer reads the host; every +other module takes what it read as required values; a frozen dataclass binds +shared values and its constructor only stores; a decision returns what to do +and the entry layer does it; a new or changed unit test builds values and +patches nothing; an entry layer is a short sequence tested as a program; the +pull request states what the hosted gate no longer catches, and the reviewer +verifies rules 1 to 6. The companion paragraph, a pointer in the unit test +guide and the reviewer's duty in the brief template are in the same commit. +The section is separate from *Unit Tests* because four of its rules bind +product code and the numbers of *Unit Tests* are cited in many records. + +**The review.** Codex + GPT-6 Astra, high effort, on +`ws-maintenance/host-inputs-at-source-review-2`, brief under +`evidence/2026-11-12-host-inputs-as-values/review-brief.md`. It opened +[PR #28](https://github.com/mycodespace-ai/devcapsule/pull/28) with one +commit, `04770142`. Accepted without a round and merged at `83d238b8`. What +it changed: + +- `run` set the surface's launch variable before its properties file was + written; 0.3.0 wrote the file first, and set the session variables before + it planned the launch. `Session.environment` no longer carries the launch + variables; `run` sets them after the files. A new integration test proves + both failure cases in a real process. +- The two version integration tests computed their expected output with the + code under test. They now copy the package into scratch, give it an + authored version and a stamp, and assert text and JSON written out in the + test. This closes the fault of the record looked for outside the package. +- The decisions integration test accepted any failure. It now requires the + console's diagnostic to name a file the test wrote, which closes the fault + of the dropped arguments. It skips where the image has no console. +- A new integration test runs the real `os.chown` with a uid and a gid that + differ, by passing 0 as the caller's uid and a supplementary group of the + runner. It closes the fault of the swapped uid and gid. +- A fixture of `test_contract.py` no longer inherits PyCharm's `/ide-config`. + Two mirror tests cover a directory named `__init__.py` and the precedence + of a component's variables. The integration helpers skip where the + supervisor's signal calls are absent and never write bytecode. + +Of the five faults that no test caught, three are now caught by integration +tests. The probe's timeout, twice, stays uncaught; the reviewer argues that a +test of it would depend on the clock, and proposes none. Of its own twelve +planted faults, four are caught by mirror tests, one by a legacy unit test, +five by integration tests, two by nothing. I planted the swapped owner +change and the dropped arguments again in the review worktree; each new test +failed on its fault and passed after the restore. + +**What the review leaves for the owner.** + +1. One difference from 0.3.0 remains. The rewrite creates every directory, + sets the private modes and then changes the owners. 0.3.0 changed the + owners directory by directory, then set the modes. The final state is the + same; the state after a start that fails between the two is not. +2. Deviations from the rule in the code as merged, each named in PR #28's + body: `ConsoleInstallation.child` checks a path, prints a notice and + returns a callback that opens a socket; `DecisionTools.run` starts a + program with the inherited environment; `prepare_filesystem` performs + `os.chown` below the entry layer; `current_build_info()` and + `is_built_distribution()` find the package without an argument; `run` + branches twice on an answer of the session; the helper of the legacy + `tests/test_contained_display.py` still patches; the autouse fixtures of + `tests/conftest.py` still patch for every test. +3. Where the reviewer found the rule open to two readings: + - Rule 1: whether reading a file or a socket at a path or address that was + passed in is a read of the host. Rule 5 calls such a file a value; rule + 1's "only" can be read to forbid it. + - Rule 1: "the one function that such a layer calls first" does not + settle `main` to `run`, or `VersionCommand.run` to `current_build_info`. + - Rules 2 and 3: whether a factory with no argument that names fixed + paths, `ConsoleInstallation.of_image`, is allowed. + - Rule 4: whether a helper below the entry layer may perform an effect + that a decision returned. + - Rule 5: whether a changed helper of an unchanged legacy test, or an + inherited autouse fixture, makes a test "changed". + - Rule 6: whether applying a returned boolean with `if` is a decision of + the entry layer. + - Rule 7: which evidence states "what the hosted gate does not catch": a + list of tests not run, or planted faults. +4. The reviewer's proposals: run the three integration files in the hosted + pull-request gate and count skips apart from passes; give release + acceptance an environment with a console so the forwarding test does not + skip there; keep a version check on the built executable itself; retire + the display fixture and split four contract tests that make two calls. + +**Validation on the merged branch, `83d238b8`, in the capsule.** +`nox -s tests`: 17 failed, 2961 passed; the 17 are the standing ones, by file +and count. The convention check: 102 legacy files, 1350 legacy tests, 53 +conforming files, 0 breaches. In the review worktree: 157 mirror tests, 25 +integration tests with no skip, 69 legacy tests of the neighbours, mypy over +341 files, all pass. Not run: `nox -s webconsole`, the end-to-end sessions, +`nox -s build` as one session, a built executable. + +**Next action.** The owner reads PR #26 and rules on the open readings of +the rule; the rule's text changes only on that ruling. The review worktree +`~/worktrees/maintenance-review` is kept until then. + ## PR #26 rewritten: host inputs are values, and no touched test patches — 2026-11-12 On 2026-11-11 the owner read the first judgment of the section below and @@ -160,11 +262,12 @@ end-to-end sessions, `nox -s build` as one session. process, so a command reads `context.environ` and a test passes one. - Apply the same change to `display.py`, whose legacy tests patch three names. -**Review.** The rewrite has not been reviewed by the partner. PR #27 reviewed -the code this section replaces. +**Review.** PR #27 reviewed the code this section replaces. The partner +reviewed the rewrite as PR #28; see the section above, which also corrects +this one: the launch variable is no longer part of `Session.environment`, and +three of the five uncaught faults are now caught. -**Next action.** The owner reads PR #26; lessons and a rule for *Unit Tests* -follow from that reading, on the owner's word. +**Next action.** See the section above. ## PR #18's test-only parameters removed; the tests set the host at its source — 2026-11-11 From 81f3267f21e02b4ffb5e75bae56f87c52dfbb991 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 02:53:14 +0000 Subject: [PATCH 13/75] Maintenance status: the definition stamp after the Host Inputs rule Written by devcapsule0 workflow publish, coordination 1ff67b626553. Co-Authored-By: Claude --- engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index a80a26c9..52598bed 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -6,7 +6,7 @@ Start date: 2026-09-18 State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next -Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d92bdcbb0a01 +Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d0a571433a6c Integration target: `main` From f461fded35a8bbf1e328e178c0d430cca0054628 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 10:06:42 +0000 Subject: [PATCH 14/75] Tests: a unit test uses no network, and only test_cli.py invokes the command line Unit Tests rules 8 and 9, on the owner's word of 2026-11-12, each held by machine. - scripts/validate_unittests_follow_conventions.py: a fourth check. A test file that is not legacy is refused when it imports devcapsule.cli or devcapsule.__main__, directly or through a module under tests; so is a conftest.py. tests/command_line_debt.txt lists the eight mirror files that do today; the check refuses a stale line and an added line. - tests/conftest.py: NetworkGuard, on the interpreter's audit hook. While a unit test runs, a connect or send to another machine and a lookup of anything but this machine fail the test before anything is sent, and the session fails with a list of the attempts. Loopback stays open; heavier suites are not held to it. - WORKFLOW-LOCAL.md, its companion and the unit test guide state the rules. Evidence: 27 planted faults, 23 caught by the unit tests, 4 by tests/integration/test_network_guard.py, none uncaught. In the capsule, nox -s typecheck passes over 342 files; nox -s tests ends with the 17 standing failures and 3008 passed in 170 s, where it took 815 s: the one test that downloaded 1.5 GB is now stopped at its name lookup. Co-Authored-By: Claude --- WORKFLOW-LOCAL-humane.md | 30 ++- WORKFLOW-LOCAL.md | 17 +- .../validate_unittests_follow_conventions.py | 172 +++++++++++++++++- devcapsule-src/tests/command_line_debt.txt | 16 ++ devcapsule-src/tests/conftest.py | 141 +++++++++++++- .../tests/integration/test_network_guard.py | 96 ++++++++++ ...t_validate_unittests_follow_conventions.py | 143 +++++++++++++++ .../tests/unit/tests/test_conftest.py | 108 ++++++++++- engineering-docs/development/unit-tests.md | 13 ++ 9 files changed, 718 insertions(+), 18 deletions(-) create mode 100644 devcapsule-src/tests/command_line_debt.txt create mode 100644 devcapsule-src/tests/integration/test_network_guard.py diff --git a/WORKFLOW-LOCAL-humane.md b/WORKFLOW-LOCAL-humane.md index 4fcd3906..9839554d 100644 --- a/WORKFLOW-LOCAL-humane.md +++ b/WORKFLOW-LOCAL-humane.md @@ -206,7 +206,11 @@ running that program is the unit's job, and then with inputs the test chose. What the test can work out in its own process, a digest of a file it just wrote for instance, it works out there. A test that needs a program for what the program does is an integration test and runs on -demand. +demand. Only the mirror test of `cli.py` runs the command line inside the +test process; every other test either tests the module that does a +command's work or starts the program as an integration test. A unit test +uses no network: it talks to no machine but its own and asks no name +server. **Intended effect.** A reader sees which unit a test tests from its path and what it tests from its first line. A test fails only when the unit @@ -262,6 +266,30 @@ process. Git on a scratch repository can pass both, and even then its commit dates come from the clock unless the test sets them. A Docker build passes neither. +The rules on the command line and on the network were added on 2026-11-12, +from one test. `test_offered_agent_still_needs_consent_and_can_be_omitted` +calls `cli.main` four times and expects the second call to stop for consent +to a vendor's channel. In the owner's capsule the consent was already given, +through the mounted settings, so the command went on as it does in +production and downloaded 1.5 GB of vendor software, in every run of the +unit suite. A run with the network refused took 78 seconds where the +ordinary one took thirteen and a half minutes, and that test was the only +one in the suite that tried to connect. The owner's ruling: unless a test is +in `test_cli.py`, it has no business invoking the command line. `cli.main` +is the top of the product; it loads the developer's settings before it +dispatches, and everything the product can do is reachable from it, so a +test that calls it is held offline only by where its author expected the +flow to stop. 32 of the 102 legacy files and 8 files under the mirror did so on that +day. The legacy files meet the rule when they are retired; the 8 are listed +as a debt that the gate lets shrink and never grow. The check follows a +test's imports through the helpers under `tests`, because a helper that +calls `cli.main` is how a test would otherwise keep doing it with a clean +import list. The network rule is held at run time, by the interpreter's +audit hook, since no reading of a test's source can tell what the code it +calls will open. Loopback stays open because a test may serve itself. Both +checks are what a compiler would have refused in a language that tracks +effects; in Python the gate has to. + ## Host Inputs **Rule.** Only the top layer of a program reads the host: the environment, diff --git a/WORKFLOW-LOCAL.md b/WORKFLOW-LOCAL.md index d0a57143..4e9a93c9 100644 --- a/WORKFLOW-LOCAL.md +++ b/WORKFLOW-LOCAL.md @@ -227,13 +227,26 @@ capsule for reasons that were not bugs. file. Fix or replace a legacy test that a legitimate change breaks; never mark it expected to fail or deselect it. Add no marker other than `legacy` to a legacy file. -6. The gate holds rules 1, 3 and 5: `scripts/validate_unittests_follow_conventions.py` runs in +6. The gate holds rules 1, 3, 5 and 8: `scripts/validate_unittests_follow_conventions.py` runs in the `tests` and `build` sessions and in `tests.yml`, comparing legacy files with the pull request's base. Its summary line counts the legacy - files and tests; the count goes down and never up. + files and tests, and the files in command-line debt; the counts go down + and never up. The suite holds rule 9: `tests/conftest.py` fails the test + that breaks it, and then the session. 7. In a Pair Review Loop, the brief instructs the reviewer to verify rules 1 to 4 on every new or changed test, and to name for each what would make it fail for a reason that is not a bug. +8. Owner direction, 2026-11-12. Only `tests/unit/devcapsule/test_cli.py` + invokes the command line in its own process. No other test file imports + `devcapsule.cli` or `devcapsule.__main__`, or a module under `tests` that + does. Test a command on the module that does its work, or in an + integration test that starts the program. A legacy file is exempt until + it is retired. A file listed in + `devcapsule-src/tests/command_line_debt.txt` is exempt until it is fixed. + Delete a file's line when you fix it. Add no line. +9. Owner direction, 2026-11-12. A unit test uses no network. It reaches no + machine but its own and asks no name server. A loopback address is its + own machine. ## Host Inputs diff --git a/devcapsule-src/scripts/validate_unittests_follow_conventions.py b/devcapsule-src/scripts/validate_unittests_follow_conventions.py index 58ed1022..81e8ab96 100644 --- a/devcapsule-src/scripts/validate_unittests_follow_conventions.py +++ b/devcapsule-src/scripts/validate_unittests_follow_conventions.py @@ -21,6 +21,13 @@ while a flat legacy unit-test file ``tests/test_.py`` still exists is also refused, the two paired by file name alone; refurbish the entire legacy file into the mirror and delete it. +4. **The command line.** Only ``tests/unit/devcapsule/test_cli.py`` imports + ``devcapsule.cli`` or ``devcapsule.__main__``. Every other file that is + not legacy is refused when it imports one of them, or a module under + ``tests`` that does, however many imports away. A ``conftest.py`` is + refused too, since its fixtures reach tests without an import. The files + listed in ``tests/command_line_debt.txt`` did so when the rule was + written; the list may lose lines and never gains one. The base revision is ``--base``, else ``DEVCAPSULE_DIFF_BASE``, else ``origin/main``, compared at its merge base with ``HEAD``. The exit status @@ -34,6 +41,7 @@ import os import subprocess import sys +from collections.abc import Iterable, Sequence from dataclasses import dataclass, field from pathlib import Path @@ -53,6 +61,25 @@ UNIT_MIRROR = Path("tests") / "unit" """The directory that mirrors ``devcapsule-src`` for unit tests.""" +COMMAND_LINE = frozenset({"devcapsule.cli", "devcapsule.__main__"}) +"""The modules that are the product's command line. + +A test that imports one can run any command in its own process, and a command +does all the product does: it reads the developer's settings and can reach the +network. On 2026-11-12 one such "unit" test downloaded 1.5 GB. +""" + +COMMAND_LINE_MIRROR = UNIT_MIRROR / "devcapsule" / "test_cli.py" +"""The one test file that may import the command line: the mirror of ``devcapsule/cli.py``.""" + +COMMAND_LINE_DEBT = Path("tests") / "command_line_debt.txt" +"""The list of the files that reached the command line when rule 4 was written. + +It is data of the repository, not of this script, so that the script checks +any repository it is pointed at. One path per line, relative to +``devcapsule-src``; a ``#`` starts a comment. +""" + _EXCLUDED_PARTS = frozenset({"resources"}) @@ -68,6 +95,14 @@ class TestModule: """Qualified test function name to its source, decorators included, lines right-stripped.""" undocumented: tuple[tuple[str, int], ...] = () """Test functions without a docstring, with the line of their ``def``.""" + imports: frozenset[str] = frozenset() + """Every module the file imports, by dotted name, wherever the import stands. + + ``from a import b`` is recorded as ``a`` and as ``a.b``: only the importer + knows whether ``b`` is a module, and rule 4 must not depend on it. A call + given the command line's name as a string, as ``importlib.import_module`` + takes it, is recorded as an import of it. + """ @property def legacy(self) -> bool: @@ -86,7 +121,40 @@ def parse_module(path: Path, source: str) -> TestModule: functions[qualified] = "\n".join(line.rstrip() for line in lines[start - 1:end]) if not ast.get_docstring(node): undocumented.append((qualified, node.lineno)) - return TestModule(path, frozenset(_module_markers(tree)), functions, tuple(undocumented)) + return TestModule(path, frozenset(_module_markers(tree)), functions, tuple(undocumented), _imports(tree, path)) + + +def _module_name(path: Path) -> str: + """The dotted name Python imports a file by: ``tests/a/b.py`` is ``tests.a.b``, ``tests/a/__init__.py`` is ``tests.a``.""" + parts = path.with_suffix("").parts + return ".".join(parts[:-1] if parts[-1] == "__init__" else parts) + + +def _imports(tree: ast.Module, path: Path) -> frozenset[str]: + """The dotted names of the modules a file imports; see ``TestModule.imports``.""" + package = _module_name(path).split(".") + if path.name != "__init__.py": + package = package[:-1] + names: set[str] = set() + # ast.walk visits every node, so an import inside a function is found like one at the top. + for node in ast.walk(tree): + if isinstance(node, ast.Import): + names.update(alias.name for alias in node.names) + elif isinstance(node, ast.ImportFrom): + # ``from . import x`` has level 1 and starts at the file's own package; each further dot climbs one package. + origin = package[:len(package) - node.level + 1] if node.level else [] + source = ".".join([*origin, *([node.module] if node.module else [])]) + names.add(source) + names.update(f"{source}.{alias.name}" for alias in node.names) + elif isinstance(node, ast.Call): + # ``importlib.import_module("devcapsule.cli")`` imports the command line without an import statement: + # a call that is handed its name as a string counts. The name in any other place, an expected value + # for instance, does not. + names.update( + argument.value for argument in node.args + if isinstance(argument, ast.Constant) and isinstance(argument.value, str) and argument.value in COMMAND_LINE + ) + return frozenset(names) def _test_functions(tree: ast.Module) -> list[tuple[str, ast.FunctionDef | ast.AsyncFunctionDef]]: @@ -146,12 +214,23 @@ def mirrored_module(test_path: Path, project_root: Path) -> Path | None: return None -def check(modules: list[TestModule], base: dict[Path, TestModule | None], project_root: Path) -> list[str]: +def check( + modules: list[TestModule], + base: dict[Path, TestModule | None], + project_root: Path, + support: Sequence[TestModule] = (), + debt: frozenset[Path] = frozenset(), +) -> list[str]: """All breaches, one line each, for the given files against their base versions. ``base`` maps each checked file's path to its parsed base version, or to None when the base revision does not have the file. + + ``support`` is every other Python file under ``tests``: helpers and + ``conftest.py`` files. Rule 4 reads their imports and nothing else of them. + ``debt`` is the paths rule 4 exempts while they still breach it. """ + carriers = _command_line_carriers([*modules, *support]) flat_legacy_by_name: dict[str, list[Path]] = {} for module in modules: if _is_flat_legacy_unit_file(module): @@ -170,9 +249,58 @@ def check(modules: list[TestModule], base: dict[Path, TestModule | None], projec )) for name, line in module.undocumented: breaches.append(f"{module.path}:{line}: {name} has no docstring stating its contract") + breaches.extend(_check_command_line(module, carriers, debt)) + for helper in support: + # A fixture defined in a conftest reaches every test below it with no import in the test to see. + if helper.path.name == "conftest.py": + breaches.extend(_check_command_line(helper, carriers, debt)) + # A listed path that is gone, or that names a legacy file, was judged by nothing above, so its line is stale. + for path in sorted(debt - {module.path for module in modules if not module.legacy} - {helper.path for helper in support}): + breaches.append(f"{path}: listed in {COMMAND_LINE_DEBT} but not a file rule 4 checks; delete its line") return breaches +def _command_line_carriers(files: Iterable[TestModule]) -> frozenset[str]: + """The modules under ``tests`` through which a test reaches the command line. + + A helper that calls ``cli.main`` gives the command line to every test that + imports the helper. So a carrier is a file that imports the command line, + or imports a carrier, and importing a carrier counts as importing the + command line itself. + """ + imports = {_module_name(file.path): file.imports for file in files} + carriers: set[str] = set() + grew = True + while grew: # A carrier can be several imports from the command line; stop when a pass finds no new one. + grew = False + for name, imported in imports.items(): + if name not in carriers and imported & (COMMAND_LINE | carriers): + carriers.add(name) + grew = True + return frozenset(carriers) + + +def _check_command_line(module: TestModule, carriers: frozenset[str], debt: frozenset[Path]) -> list[str]: + """The breach of rule 4 by one file that is not legacy, or nothing. + + A file reaches the command line when it imports it, or imports a carrier. + """ + if module.path == COMMAND_LINE_MIRROR: + return [] + reached = sorted(module.imports & (COMMAND_LINE | carriers)) + if module.path in debt: + # The list only shrinks: a listed file that no longer needs its line must lose it in the same change. + if reached: + return [] + return [f"{module.path}: no longer reaches the command line; delete its line from {COMMAND_LINE_DEBT}"] + if not reached: + return [] + return [ + f"{module.path}: imports {reached[0]}, which is or reaches the command line; only {COMMAND_LINE_MIRROR} " + "invokes it. Test the module that does the work, or start the program in an integration test" + ] + + def _is_flat_legacy_unit_file(module: TestModule) -> bool: return ( module.legacy @@ -242,19 +370,38 @@ def _test_files(project_root: Path) -> list[Path]: ) +def _support_files(project_root: Path) -> list[Path]: + """Every Python file under ``tests`` that is not a test file: helpers, ``conftest.py``, ``__init__.py``.""" + return sorted( + path.relative_to(project_root) + for path in (project_root / "tests").rglob("*.py") + if not path.name.startswith("test_") and not _EXCLUDED_PARTS & set(path.parts) + ) + + +def _debt(text: str) -> frozenset[Path]: + """The paths a debt list names: one per line, comments and blank lines aside.""" + lines = (line.split("#", 1)[0].strip() for line in text.splitlines()) + return frozenset(Path(line) for line in lines if line) + + def _git(project_root: Path, *arguments: str) -> str: return subprocess.run(["git", *arguments], cwd=project_root, check=True, capture_output=True, text=True).stdout -def _base_version(project_root: Path, merge_base: str, path: Path) -> TestModule | None: +def _base_text(project_root: Path, merge_base: str, path: Path) -> str | None: + """A file's text at the base revision, or None when the base does not have it.""" prefix = _git(project_root, "rev-parse", "--show-prefix").strip() completed = subprocess.run( ["git", "show", f"{merge_base}:{prefix}{path.as_posix()}"], cwd=project_root, capture_output=True, text=True, ) - if completed.returncode != 0: - return None - return parse_module(path, completed.stdout) + return completed.stdout if completed.returncode == 0 else None + + +def _base_version(project_root: Path, merge_base: str, path: Path) -> TestModule | None: + text = _base_text(project_root, merge_base, path) + return None if text is None else parse_module(path, text) def main(argv: list[str] | None = None) -> int: @@ -276,12 +423,21 @@ def main(argv: list[str] | None = None) -> int: if module.legacy or (module.path.is_relative_to(UNIT_MIRROR) and module.path.name in flat_legacy_names) ] base = {module.path: _base_version(root, merge_base, module.path) for module in needs_base} - breaches = check(modules, base, root) + support = [parse_module(path, (root / path).read_text(encoding="utf-8")) for path in _support_files(root)] + debt_file = root / COMMAND_LINE_DEBT + debt = _debt(debt_file.read_text(encoding="utf-8")) if debt_file.is_file() else frozenset() + breaches = check(modules, base, root, support, debt) + # The debt list never grows. A base without the list is the change that introduces it, which review reads whole. + base_debt = _base_text(root, merge_base, COMMAND_LINE_DEBT) + if base_debt is not None: + for path in sorted(debt - _debt(base_debt)): + breaches.append(f"{COMMAND_LINE_DEBT}: {path} was added; the list loses lines and never gains one") for breach in breaches: print(breach, file=sys.stderr) legacy = [module for module in modules if module.legacy] print(f"test conventions: {len(legacy)} legacy files holding {sum(len(m.functions) for m in legacy)} legacy tests; " - f"{len(modules) - len(legacy)} files follow the convention; {len(breaches)} breaches") + f"{len(modules) - len(legacy)} files follow the convention; {len(breaches)} breaches; " + f"{len(debt)} files in command-line debt") return 1 if breaches else 0 diff --git a/devcapsule-src/tests/command_line_debt.txt b/devcapsule-src/tests/command_line_debt.txt new file mode 100644 index 00000000..aa49c10e --- /dev/null +++ b/devcapsule-src/tests/command_line_debt.txt @@ -0,0 +1,16 @@ +# Test files that reach the product's command line, devcapsule.cli, from their own process. +# +# Unit Tests, rule 8, in WORKFLOW-LOCAL.md: only tests/unit/devcapsule/test_cli.py may. +# These files did when the rule was written, 2026-11-12. To fix one, rewrite its +# tests on the module that does the work, or as integration tests that start the +# program; then delete its line. scripts/validate_unittests_follow_conventions.py +# refuses a line whose file no longer needs it, and refuses a new line. + +tests/unit/devcapsule/commands/test_images.py +tests/unit/devcapsule/configuration/test_owner_commands.py +tests/unit/devcapsule/configuration/test_storage.py +tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py +tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py +tests/unit/devcapsule/legacy_refactoring/test_console_channel.py +tests/unit/devcapsule/legacy_refactoring/test_project_init.py +tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/devcapsule-src/tests/conftest.py b/devcapsule-src/tests/conftest.py index 100d6586..644ee43f 100644 --- a/devcapsule-src/tests/conftest.py +++ b/devcapsule-src/tests/conftest.py @@ -1,9 +1,11 @@ from __future__ import annotations from collections.abc import Iterable, Iterator +import ipaddress import os from pathlib import Path import shutil +import socket import sys import tempfile from typing import Any, Protocol @@ -17,10 +19,12 @@ def pytest_configure(config: pytest.Config) -> None: - """Start the repository-input guard, and give a macOS run a short temporary root. + """Start the two guards, and give a macOS run a short temporary root. - The guard fails a test that opens or lists a repository path the hosted - Python job is not routed by; see ``RepositoryInputGuard``. + The repository-input guard fails a test that opens or lists a repository + path the hosted Python job is not routed by; see ``RepositoryInputGuard``. + The network guard fails a unit test that reaches another host or asks a + name server; see ``NetworkGuard``. macOS limits a Unix socket path to 104 bytes, and its per-user temporary directory under /var/folders leaves too little of that for the sockets @@ -31,6 +35,7 @@ def pytest_configure(config: pytest.Config) -> None: if PYTHON_ROUTE_INPUTS.parent.is_dir(): guard = RepositoryInputGuard(REPOSITORY_ROOT, load_python_route_inputs(PYTHON_ROUTE_INPUTS)) config.stash[_INPUT_GUARD] = install_repository_input_guard(guard) + config.stash[_NETWORK_GUARD] = install_network_guard(NetworkGuard()) if sys.platform == "darwin" and not config.option.basetemp: config.option.basetemp = tempfile.mkdtemp(prefix="dcpt-", dir="/tmp") config.stash[_SHORT_BASETEMP] = Path(config.option.basetemp) @@ -38,26 +43,34 @@ def pytest_configure(config: pytest.Config) -> None: _SHORT_BASETEMP = pytest.StashKey[Path]() _INPUT_GUARD = pytest.StashKey["RepositoryInputGuard"]() +_NETWORK_GUARD = pytest.StashKey["NetworkGuard"]() @pytest.hookimpl(hookwrapper=True) def pytest_runtest_protocol(item: pytest.Item) -> Iterator[None]: - """Tell the repository-input guard which test reads, and whether its outcome counts.""" + """Tell each guard which test runs: whether its outcome counts, and whether it is a unit test.""" guard = item.config.stash.get(_INPUT_GUARD, None) + network = item.config.stash.get(_NETWORK_GUARD, None) if guard is not None: guard.attend(item.nodeid, counted=outcome_counts(item, HEAVIER_SUITE_MARKERS)) + # A test of a heavier suite may use the network: an integration test builds an executable, an end-to-end test pulls an image. + if network is not None and not any(item.get_closest_marker(marker) for marker in HEAVIER_SUITE_MARKERS): + network.attend(item.nodeid) yield if guard is not None: guard.leave() + if network is not None: + network.leave() def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None: - """Fail a session with repository-input breaches, and remove the short temporary root of a passed one. + """Fail a session with breaches of either guard, and remove the short temporary root of a passed one. A breach fails its test where it happens. This is the second hold: a breach recorded although no test failed, because something caught the - failure, still ends the session with a failing status. + failure or it happened in another thread, still ends the session with a + failing status. pytest prunes its own default roots, but not one it was given, so a root per session would otherwise outlive every run and fill the disk; a failed @@ -72,6 +85,14 @@ def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None: print(f" {path} read by {reader}") if exitstatus == pytest.ExitCode.OK: session.exitstatus = exitstatus = pytest.ExitCode.TESTS_FAILED + network = session.config.stash.get(_NETWORK_GUARD, None) + attempts = network.breaches if network is not None else [] + if attempts: + print("\nUnit tests that tried to use the network (Unit Tests, rule 9, in WORKFLOW-LOCAL.md):") + for test, attempt in sorted(set(attempts)): + print(f" {attempt} by {test}") + if exitstatus == pytest.ExitCode.OK: + session.exitstatus = exitstatus = pytest.ExitCode.TESTS_FAILED created = session.config.stash.get(_SHORT_BASETEMP, None) if created is not None and exitstatus == 0: shutil.rmtree(created, ignore_errors=True) @@ -332,3 +353,111 @@ def install_repository_input_guard(guard: RepositoryInputGuard) -> RepositoryInp _installed_guard = guard sys.addaudithook(guard.audit) return _installed_guard + + +# The network guard. +# +# A unit test's outcome is a function of the inputs it constructs, and nothing +# on the network is one of them (Unit Tests, rules 2 and 9, in +# WORKFLOW-LOCAL.md). The suite had no hold on that: on 2026-11-12 one test, +# its consent already given in the developer's settings, went on to download +# 1.5 GB of vendor software in every run inside a capsule. +# +# The guard refuses two things while a unit test runs: sending to an address +# that is not this machine's own, and asking for a name or an address to be +# resolved. Loopback stays open, since a test may serve itself on 127.0.0.1. +# +# What the guard cannot see: the network use of a program a test starts, +# unless that program is this Python with this guard. + +_REACH_EVENTS = frozenset({"socket.connect", "socket.sendto", "socket.sendmsg"}) +"""Audit events of a socket about to reach a peer. Their arguments are ``(socket, address)``.""" + +_LOOKUP_EVENTS = frozenset({"socket.getaddrinfo", "socket.gethostbyname", "socket.gethostbyaddr"}) +"""Audit events of a question to the resolver. Their first argument is the host asked about.""" + +_INTERNET_FAMILIES = frozenset({socket.AF_INET, socket.AF_INET6}) +"""The socket families that can leave the machine. A Unix socket is a path on this machine and passes.""" + + +def is_this_machine(host: object) -> bool: + """Whether ``host``, as a socket call was given it, can only mean the machine the test runs on. + + True for no host at all, which a listener passes to mean every local + address; for ``localhost``; and for a loopback or unspecified address such + as ``127.0.0.1``, ``::1`` or ``0.0.0.0``. False for every other address + and for every other name, the machine's own host name included: resolving + a name is a question to a name server. + """ + if host is None: + return True + name = os.fsdecode(host) if isinstance(host, (str, bytes)) else str(host) + if name in ("", "localhost"): + return True + try: + address = ipaddress.ip_address(name) + except ValueError: # Not an address, so a name. + return False + return address.is_loopback or address.is_unspecified + + +class NetworkGuard: + """The rule for the unit suite: a unit test reaches no machine but its own and asks no name server.""" + + def __init__(self) -> None: + self._test: str | None = None + self.breaches: list[tuple[str, str]] = [] + """Every refused attempt, as ``(test, what it tried)``.""" + + def attend(self, test: str) -> None: + """Hold the test with this node id to the rule from now on.""" + self._test = test + + def leave(self) -> None: + """Hold nothing from now on: between tests, and during the tests of heavier suites, the guard stands down.""" + self._test = None + + def attempt(self, event: str, arguments: tuple[Any, ...]) -> str | None: + """What an audit event tries on the network, in words, or ``None`` when it stays on this machine.""" + if event in _LOOKUP_EVENTS and arguments and not is_this_machine(arguments[0]): + return f"look up {arguments[0]!r}" + if event not in _REACH_EVENTS or len(arguments) < 2: + return None + peer, address = arguments[0], arguments[1] + # An internet address is ``(host, port, ...)``. ``sendmsg`` on a connected socket passes no address at all. + if getattr(peer, "family", None) not in _INTERNET_FAMILIES or not isinstance(address, tuple) or not address: + return None + return None if is_this_machine(address[0]) else f"reach {address[0]!r}" + + def audit(self, event: str, arguments: tuple[Any, ...]) -> None: + """The interpreter's audit hook: fail a unit test's attempt to use the network, before it happens. + + The failure is ``pytest.fail``'s, an exception no ``except Exception`` + in the code under test can swallow, so nothing is sent. + """ + if self._test is None: + return + attempt = self.attempt(event, arguments) + if attempt is None: + return + self.breaches.append((self._test, attempt)) + pytest.fail( + f"{self._test} tries to {attempt}. A unit test uses no network (Unit Tests, rule 9, in " + "WORKFLOW-LOCAL.md): pass the unit what it would have fetched, or make this an integration test." + ) + + +_installed_network_guard: NetworkGuard | None = None + + +def install_network_guard(guard: NetworkGuard) -> NetworkGuard: + """Watch this process's sockets with ``guard`` and return the guard in force. + + As for the repository-input guard, the first one installed stays for the + life of the process, because an audit hook cannot be removed. + """ + global _installed_network_guard + if _installed_network_guard is None: + _installed_network_guard = guard + sys.addaudithook(guard.audit) + return _installed_network_guard diff --git a/devcapsule-src/tests/integration/test_network_guard.py b/devcapsule-src/tests/integration/test_network_guard.py new file mode 100644 index 00000000..652a3f31 --- /dev/null +++ b/devcapsule-src/tests/integration/test_network_guard.py @@ -0,0 +1,96 @@ +"""Integration tests of the network guard in ``tests/conftest.py``: a real pytest session held to it. + +``tests/unit/tests/test_conftest.py`` tests the guard's judgment from values. +These tests prove the wiring: that the interpreter's audit hook is installed, +that the guard attends unit tests and no others, and that a session with a +breach fails. Each runs pytest as a program on a suite it writes, with a copy +of the real ``conftest.py``. + +Nothing here uses the network. The inner tests name 192.0.2.1, an address +reserved for documentation, and are stopped before anything is sent. The +lookups of that address are of a literal, which no name server is asked about +even where the guard stands down. +""" +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +import pytest + +pytestmark = pytest.mark.integration + +CONFTEST = Path(__file__).resolve().parents[1] / "conftest.py" + + +def run_suite(tmp_path: Path, tests: str) -> subprocess.CompletedProcess[str]: + """Run pytest on one test file with the given source, under a copy of the real conftest. + + The suite lies two directories deep so that the copy finds no repository + above it and starts the network guard alone. The process gets a search + path and a home under ``tmp_path``, and nothing else of the caller's + environment. + """ + suite = tmp_path / "checkout" / "package" / "tests" + suite.mkdir(parents=True) + (suite / "conftest.py").write_text(CONFTEST.read_text(encoding="utf-8"), encoding="utf-8") + (suite / "pytest.ini").write_text("[pytest]\nmarkers =\n integration: a heavier suite\n", encoding="utf-8") + (suite / "test_inner.py").write_text(tests, encoding="utf-8") + return subprocess.run( + [sys.executable, "-m", "pytest", "-p", "no:cacheprovider", "-m", "", "-q", str(suite)], + cwd=suite, + env={"PATH": os.defpath, "HOME": str(tmp_path / "home"), "PYTHONDONTWRITEBYTECODE": "1"}, + capture_output=True, text=True, timeout=120, check=False, + ) + + +def test_a_session_fails_the_unit_tests_that_use_the_network_and_no_others(tmp_path: Path) -> None: + """A unit test that connects to another machine fails, and so does one that swallows the failure of a + lookup; a loopback lookup passes, and a test marked ``integration`` is not held to the rule.""" + completed = run_suite(tmp_path, ''' +import socket +import pytest + +def test_connects_to_another_machine(): + with socket.socket() as peer: + peer.settimeout(0.5) + peer.connect(("192.0.2.1", 9)) + +def test_swallows_a_refused_lookup(): + try: + socket.getaddrinfo("192.0.2.1", 9) + except Exception: + pass + +def test_looks_up_this_machine(): + assert socket.getaddrinfo("127.0.0.1", 9) + +@pytest.mark.integration +def test_of_a_heavier_suite_looks_up_another_machine(): + assert socket.getaddrinfo("192.0.2.1", 9) +''') + + assert completed.returncode == 1, completed.stdout + completed.stderr + assert "2 failed, 2 passed" in completed.stdout + assert "test_connects_to_another_machine tries to reach '192.0.2.1'" in completed.stdout + assert "test_swallows_a_refused_lookup tries to look up '192.0.2.1'" in completed.stdout + + +def test_a_session_fails_for_a_network_attempt_that_failed_no_test(tmp_path: Path) -> None: + """An attempt made in another thread fails no test; the session still ends with a failing status and names the test.""" + completed = run_suite(tmp_path, ''' +import socket +import threading + +def test_looks_up_in_a_thread(): + worker = threading.Thread(target=socket.getaddrinfo, args=("192.0.2.1", 9)) + worker.start() + worker.join() +''') + + assert completed.returncode == 1, completed.stdout + completed.stderr + assert "1 passed" in completed.stdout + assert "Unit tests that tried to use the network" in completed.stdout + assert "look up '192.0.2.1' by test_inner.py::test_looks_up_in_a_thread" in completed.stdout diff --git a/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py b/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py index 8a7fa0ab..902c2da0 100644 --- a/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py +++ b/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py @@ -333,3 +333,146 @@ def test_main_fails_when_the_base_cannot_be_resolved(tmp_path: Path, capsys: pyt _git(root, "commit", "-q", "--allow-empty", "-m", "base") assert conventions.main(["--base", "nowhere", "--project-root", str(root)]) == 1 assert "cannot resolve base 'nowhere'" in capsys.readouterr().err + + +# Rule 4, the command line. ``_mirror`` gives each case a mirror file that the +# other rules accept, so that a breach reported here is rule 4's. + +DEBT_LIST = "tests/command_line_debt.txt" + + +def _mirror(root: Path, name: str, source: str) -> Any: + """A documented test file ``tests/unit/devcapsule/test_.py`` with the given imports, and the module it mirrors.""" + (root / "devcapsule").mkdir(exist_ok=True) + (root / "devcapsule" / f"{name}.py").write_text("") + return _module(f"tests/unit/devcapsule/test_{name}.py", source + DOCUMENTED) + + +@pytest.mark.parametrize(("source", "imported"), [ + ("import a.b\n", {"a.b"}), + ("from a import b\n", {"a", "a.b"}), + ("from a.b import c as d\n", {"a.b", "a.b.c"}), + ("def helper():\n import a.b\n", {"a.b"}), + ("from . import b\n", {"tests.unit", "tests.unit.b"}), + ("from ..c import d\n", {"tests.c", "tests.c.d"}), + ("import importlib\nmodule = importlib.import_module('devcapsule.cli')\n", {"importlib", "devcapsule.cli"}), + ("EXPECTED = {'devcapsule.cli'}\n", set()), +]) +def test_a_files_imports_are_recorded_in_every_form(source: str, imported: set[str]) -> None: + """``parse_module`` records an import statement at any depth, both readings of ``from a import b``, a relative + import by its full name, and a call handed the command line's name as a string, as ``importlib`` takes it; + the same string outside a call is no import.""" + assert _module("tests/unit/test_a.py", source).imports == imported + + +@pytest.mark.parametrize("source", [ + "from devcapsule import cli\n", + "import devcapsule.cli\n", + "from devcapsule.cli import main\n", + "from devcapsule.__main__ import main\n", + "def run():\n from devcapsule import cli\n", +]) +def test_a_file_that_imports_the_command_line_is_a_breach(tmp_path: Path, source: str) -> None: + """A mirror file that imports ``devcapsule.cli`` or ``devcapsule.__main__``, in any form, is one breach + naming the file and the one file that may.""" + breaches = conventions.check([_mirror(tmp_path, "thing", source)], {}, tmp_path) + assert len(breaches) == 1 + assert breaches[0].startswith("tests/unit/devcapsule/test_thing.py: imports devcapsule.") + assert "only tests/unit/devcapsule/test_cli.py invokes it" in breaches[0] + + +def test_the_mirror_of_the_command_line_and_a_legacy_file_may_import_it(tmp_path: Path) -> None: + """``tests/unit/devcapsule/test_cli.py`` and an unchanged legacy file import ``devcapsule.cli`` without a breach.""" + mirror = _mirror(tmp_path, "cli", "from devcapsule import cli\n") + legacy = _module("tests/test_old.py", "import pytest\nfrom devcapsule import cli\npytestmark = pytest.mark.legacy\n" + UNDOCUMENTED) + assert conventions.check([mirror, legacy], {legacy.path: legacy}, tmp_path) == [] + + +def test_a_heavier_suites_file_that_imports_the_command_line_is_a_breach(tmp_path: Path) -> None: + """An integration file is held to the rule as well: it starts the program, it does not import it.""" + module = _module("tests/integration/test_flow.py", "import pytest\nfrom devcapsule import cli\npytestmark = pytest.mark.integration\n" + DOCUMENTED) + breaches = conventions.check([module], {}, tmp_path) + assert len(breaches) == 1 and breaches[0].startswith("tests/integration/test_flow.py: imports devcapsule.cli") + + +def test_the_command_line_reached_through_helpers_is_a_breach(tmp_path: Path) -> None: + """A mirror file that imports a helper, which imports a second helper, which imports the command line, is a + breach naming the helper it imports; a mirror file that imports a helper outside that chain is none.""" + near = _module("tests/flows.py", "from tests import launch\n") + far = _module("tests/launch.py", "from devcapsule import cli\n") + plain = _module("tests/values.py", "import json\n") + reaching = _mirror(tmp_path, "thing", "from tests.flows import prepared\n") + clean = _mirror(tmp_path, "other", "from tests.values import sample\n") + assert conventions.check([reaching, clean], {}, tmp_path, support=[near, far, plain]) == [ + "tests/unit/devcapsule/test_thing.py: imports tests.flows, which is or reaches the command line; " + "only tests/unit/devcapsule/test_cli.py invokes it. Test the module that does the work, or start the " + "program in an integration test" + ] + + +def test_the_command_line_reached_through_a_legacy_test_file_is_a_breach(tmp_path: Path) -> None: + """A mirror file that imports a fixture from a legacy test file which imports the command line is a breach.""" + legacy = _module("tests/test_old.py", "import pytest\nfrom devcapsule import cli\npytestmark = pytest.mark.legacy\n" + UNDOCUMENTED) + mirror = _mirror(tmp_path, "thing", "from tests.test_old import project\n") + breaches = conventions.check([legacy, mirror], {legacy.path: legacy}, tmp_path) + assert len(breaches) == 1 and breaches[0].startswith("tests/unit/devcapsule/test_thing.py: imports tests.test_old,") + + +def test_a_conftest_that_reaches_the_command_line_is_a_breach(tmp_path: Path) -> None: + """A ``conftest.py`` that imports the command line is a breach although no test imports the conftest; + a helper that is not a conftest is none by itself.""" + conftest = _module("tests/unit/conftest.py", "from devcapsule import cli\n") + helper = _module("tests/launch.py", "from devcapsule import cli\n") + breaches = conventions.check([], {}, tmp_path, support=[conftest, helper]) + assert len(breaches) == 1 and breaches[0].startswith("tests/unit/conftest.py: imports devcapsule.cli") + + +def test_a_file_in_debt_is_exempt_while_it_reaches_the_command_line_and_refused_once_it_does_not(tmp_path: Path) -> None: + """A listed file that imports the command line is no breach. A listed file that does not is one, asking for + its line to be deleted, and so is a listed path that is no checked file.""" + reaching = _mirror(tmp_path, "thing", "from devcapsule import cli\n") + fixed = _mirror(tmp_path, "other", "") + debt = frozenset({reaching.path, fixed.path, Path("tests/unit/devcapsule/test_gone.py")}) + assert conventions.check([reaching, fixed], {}, tmp_path, debt=debt) == [ + f"tests/unit/devcapsule/test_other.py: no longer reaches the command line; delete its line from {DEBT_LIST}", + f"tests/unit/devcapsule/test_gone.py: listed in {DEBT_LIST} but not a file rule 4 checks; delete its line", + ] + + +def _repository_in_debt(tmp_path: Path) -> Path: + """A committed repository on ``main`` with two mirror files that import the command line, the first one listed as debt.""" + root = tmp_path / "devcapsule-src" + mirror = root / "tests" / "unit" / "devcapsule" + mirror.mkdir(parents=True) + for name in ("thing", "other"): + (root / "devcapsule" / f"{name}.py").parent.mkdir(exist_ok=True) + (root / "devcapsule" / f"{name}.py").write_text("") + (mirror / f"test_{name}.py").write_text("from devcapsule import cli\n" + DOCUMENTED) + (root / DEBT_LIST).write_text("# the debt\n\ntests/unit/devcapsule/test_thing.py # the first\n") + _git(root, "init", "-q", "-b", "main") + _git(root, "add", ".") + _git(root, "commit", "-q", "-m", "base") + _git(root, "checkout", "-q", "-b", "slice") + return root + + +def test_main_reads_the_debt_list_of_the_repository_it_checks(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: + """With one of two reaching files listed in the repository's debt list, comments aside, ``main`` exits 1, + names only the unlisted file, and counts one file in debt.""" + root = _repository_in_debt(tmp_path) + assert conventions.main(["--base", "main", "--project-root", str(root)]) == 1 + captured = capsys.readouterr() + assert "tests/unit/devcapsule/test_other.py: imports devcapsule.cli" in captured.err + assert "test_thing.py" not in captured.err + assert "1 breaches; 1 files in command-line debt" in captured.out + + +def test_main_refuses_a_line_added_to_the_debt_list(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: + """When a branch lists a second reaching file that the base's list does not have, ``main`` exits 1 and + names the added line: the list loses lines and never gains one.""" + root = _repository_in_debt(tmp_path) + with (root / DEBT_LIST).open("a") as listing: + listing.write("tests/unit/devcapsule/test_other.py\n") + assert conventions.main(["--base", "main", "--project-root", str(root)]) == 1 + captured = capsys.readouterr() + assert captured.err == f"{DEBT_LIST}: tests/unit/devcapsule/test_other.py was added; the list loses lines and never gains one\n" diff --git a/devcapsule-src/tests/unit/tests/test_conftest.py b/devcapsule-src/tests/unit/tests/test_conftest.py index f8e9d217..8ee4fb81 100644 --- a/devcapsule-src/tests/unit/tests/test_conftest.py +++ b/devcapsule-src/tests/unit/tests/test_conftest.py @@ -1,7 +1,10 @@ -"""Unit tests of ``tests/conftest.py``: the shared fixtures, the marker sets they key on, and the repository-input guard.""" +"""Unit tests of ``tests/conftest.py``: the shared fixtures, the marker sets they key on, the repository-input guard and the network guard.""" from __future__ import annotations +import socket import tomllib +from collections.abc import Iterator +from contextlib import contextmanager from pathlib import Path from types import SimpleNamespace from typing import Any @@ -12,8 +15,11 @@ from tests.conftest import ( DOCKER_MARKERS, OUTSIDE_ANY_TEST, + NetworkGuard, RepositoryInputGuard, + install_network_guard, install_repository_input_guard, + is_this_machine, load_python_route_inputs, outcome_counts, ) @@ -224,3 +230,103 @@ def test_the_first_guard_installed_stays_in_force(tmp_path: Path, monkeypatch: p first, second = _guard(tmp_path / "first"), _guard(tmp_path / "second") monkeypatch.setattr(conftest, "_installed_guard", first) assert install_repository_input_guard(second) is first + + +# The network guard. These tests hand the guard the audit events a socket +# call raises, as values. No test here sends anything: the addresses are the +# ones RFC 5737 and RFC 3849 reserve for documentation, and a ``.test`` name. + +UNIT_TEST = "tests/unit/devcapsule/test_thing.py::test_one" +ELSEWHERE_V4 = ("192.0.2.1", 443) +ELSEWHERE_V6 = ("2001:db8::1", 443, 0, 0) + + +@contextmanager +def _unsent(family: socket.AddressFamily) -> Iterator[socket.socket]: + """A datagram socket of the given family that is never bound, connected or written to.""" + with socket.socket(family, socket.SOCK_DGRAM) as peer: + yield peer + + +@pytest.mark.parametrize("host", [None, "", "localhost", "127.0.0.1", "127.8.9.1", "::1", "0.0.0.0", "::", b"127.0.0.1"]) +def test_no_host_localhost_and_loopback_addresses_are_this_machine(host: Any) -> None: + """``is_this_machine`` is true for an absent host, ``localhost``, and every loopback or unspecified address.""" + assert is_this_machine(host) is True + + +@pytest.mark.parametrize("host", ["192.0.2.1", "2001:db8::1", "example.test", "build-host-7", b"example.test"]) +def test_every_other_address_and_every_other_name_is_not_this_machine(host: Any) -> None: + """``is_this_machine`` is false for a routable address and for any name but ``localhost``, a bare host name included.""" + assert is_this_machine(host) is False + + +@pytest.mark.parametrize("event", ["socket.connect", "socket.sendto", "socket.sendmsg"]) +@pytest.mark.parametrize(("family", "address"), [(socket.AF_INET, ELSEWHERE_V4), (socket.AF_INET6, ELSEWHERE_V6)]) +def test_a_unit_tests_reach_for_another_machine_fails_before_anything_is_sent( + event: str, family: socket.AddressFamily, address: tuple[Any, ...], +) -> None: + """While the guard attends a unit test, the audit event of a connect or a send to another machine raises + ``pytest.fail``'s exception, which ``except Exception`` does not catch, and records the test and the host.""" + guard = NetworkGuard() + guard.attend(UNIT_TEST) + with _unsent(family) as peer, pytest.raises(pytest.fail.Exception) as failure: + guard.audit(event, (peer, address)) + assert not isinstance(failure.value, Exception) + assert UNIT_TEST in str(failure.value) and "rule 9" in str(failure.value) + assert guard.breaches == [(UNIT_TEST, f"reach {address[0]!r}")] + + +@pytest.mark.parametrize(("event", "arguments", "asked"), [ + ("socket.getaddrinfo", ("example.test", 443, 0, 1, 0), "example.test"), + ("socket.gethostbyname", ("example.test",), "example.test"), + ("socket.gethostbyaddr", ("192.0.2.1",), "192.0.2.1"), +]) +def test_a_unit_tests_question_to_the_resolver_fails_and_is_recorded( + event: str, arguments: tuple[Any, ...], asked: str, +) -> None: + """While the guard attends a unit test, the audit event of a lookup of anything but this machine fails and is recorded.""" + guard = NetworkGuard() + guard.attend(UNIT_TEST) + with pytest.raises(pytest.fail.Exception): + guard.audit(event, arguments) + assert guard.breaches == [(UNIT_TEST, f"look up {asked!r}")] + + +def test_what_stays_on_this_machine_passes_the_guard(tmp_path: Path) -> None: + """While the guard attends a unit test, loopback peers, a Unix socket, a send on a connected socket, lookups + of this machine, an event the guard does not watch and an event without arguments raise nothing and record nothing.""" + guard = NetworkGuard() + guard.attend(UNIT_TEST) + with _unsent(socket.AF_INET) as v4, _unsent(socket.AF_INET6) as v6, _unsent(socket.AF_UNIX) as unix: + guard.audit("socket.connect", (v4, ("127.0.0.1", 8080))) + guard.audit("socket.sendto", (v6, ("::1", 8080, 0, 0))) + guard.audit("socket.connect", (unix, str(tmp_path / "service.sock"))) + # The family decides, not the shape of the address: a socket that is not an internet socket cannot leave. + guard.audit("socket.connect", (unix, ELSEWHERE_V4)) + guard.audit("socket.sendmsg", (v4, None)) + guard.audit("socket.connect", (v4,)) + guard.audit("socket.getaddrinfo", ("localhost", 80, 0, 1, 0)) + guard.audit("socket.getaddrinfo", (None, 80, 0, 1, 0)) + guard.audit("socket.gethostbyaddr", ("127.0.0.1",)) + guard.audit("open", ("192.0.2.1", "r", 0)) + guard.audit("socket.getaddrinfo", ()) + assert guard.breaches == [] + + +def test_the_guard_stands_down_until_it_attends_a_test_and_after_it_leaves_one() -> None: + """A guard that attends no test, before its first and after ``leave``, lets a reach for another machine pass + unrecorded: between tests, and during a heavier suite's test, the network is not the unit suite's concern.""" + guard = NetworkGuard() + with _unsent(socket.AF_INET) as peer: + guard.audit("socket.connect", (peer, ELSEWHERE_V4)) + guard.attend(UNIT_TEST) + guard.leave() + guard.audit("socket.connect", (peer, ELSEWHERE_V4)) + assert guard.breaches == [] + + +def test_the_network_guard_in_force_is_not_replaced_by_a_later_one() -> None: + """Once a network guard is in force, here whichever one this process has after one install, installing + another returns the one in force: an audit hook cannot be removed, so a process keeps its first.""" + in_force = install_network_guard(NetworkGuard()) + assert install_network_guard(NetworkGuard()) is in_force diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index 9a3f174f..f5277a22 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -23,6 +23,13 @@ required values, and a unit test builds those values and patches nothing. `monkeypatch`, and every host input a constructor argument. The entry layers are tested as programs; see [Integration tests](integration-tests.md). +Two more rules of *Unit Tests* are held by machine. Rule 8: only +`tests/unit/devcapsule/test_cli.py` imports the command line, `devcapsule.cli`, +directly or through a helper under `tests`; the convention check refuses any +other file that is not legacy. The eight files that did on 2026-11-12 are +listed in `tests/command_line_debt.txt`, a list that only loses lines. Rule +9: a unit test uses no network; see the network guard under Fixtures. + ## Running them ```text @@ -158,6 +165,12 @@ so prefer the existing laws and an acceptance step for what the user sees. other paths on macOS and Apple Silicon runs linux-arm64 capsules. A test of another host patches the host itself and carries `own_host_patches`; Docker-marked tests keep the real host. +- The network guard, started in `pytest_configure`: while a unit test runs, + a connection or a send to any machine but this one, and any name lookup + but of this machine, fails the test before anything is sent, and the + session ends with a failing status and a list of the attempts. Loopback + stays open. Tests of the heavier suites are not held to it. It cannot see + the network use of a program a test starts. - `private_user_directories`, autouse: moves `HOME` and every XDG directory under the test's `tmp_path` for non-Docker tests. Inside a capsule this is not yet a private home: a home with no settings of its own reads the From bdffd172543f5f4b027ca9707b3ea4b60e5a2b8b Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 10:06:42 +0000 Subject: [PATCH 15/75] Maintenance status: the 17 failures dated, and the two rules held by machine Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 81 ++++++++++++++++++- 1 file changed, 80 insertions(+), 1 deletion(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 52598bed..b1c79e20 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d0a571433a6c @@ -16,6 +16,85 @@ Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selecti Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## Two rules held by machine: no network in a unit test, the command line only in `test_cli.py` — 2026-11-12 + +The owner asked why the capsule's 17 unit tests fail and when that began, +then ruled twice. This section records the answers and the two checks. + +**The 17, dated.** The cause is in the blocking bug record of 2026-11-10. +The dates: the isolation fixture is from 2026-10-10 (`93c83d4b`), when +settings lived under the XDG directories. On 2026-10-28, in the home slice +of 0.3.0 (PR #299), `21472b9d` made the fixture delete +`DEVCAPSULE_CONFIG_HOME` and `36bec846` added the fallback to the mounted +settings; together they opened the hole, and 0.3.0 shipped with it. The +owner accepted `claude-code` on 2026-11-01 and the first thirteen failures +of this cause appeared on 2026-11-03; `1c00b940` of 2026-11-05 marked them +expected to fail and left the fixture. The owner accepted `devcapsule-base` +and `vscode` on 2026-11-08, which turned today's 17 red with no change to +the code. + +**Measured.** With every connection and name lookup but loopback refused in +the test process, the unit suite gave the same 17 failed and 2961 passed, in +78 seconds where the ordinary run takes thirteen and a half minutes. One +test in the whole suite tried to use the network: +`test_offered_agent_still_needs_consent_and_can_be_omitted`, which calls +`cli.main` four times and, its consent already given, downloads 1.5 GB. + +**The rulings.** A unit test opens nothing on the network. Unless a test is +in `test_cli.py`, the mirror of `cli.py`, it has no business invoking the +command line. They are rules 9 and 8 of *Unit Tests* in `WORKFLOW-LOCAL.md`, +with the companion paragraph and the guide. + +**The checks.** + +- Rule 8, by reading imports, in + `scripts/validate_unittests_follow_conventions.py`, which already runs + before pytest in `nox -s tests`, `nox -s build` and the hosted workflow. + A file that is not legacy is refused when it imports `devcapsule.cli` or + `devcapsule.__main__`, directly or through a module under `tests`; a + `conftest.py` is refused too. It is not in the legacy + `tests/configuration/test_architecture.py`, because rule 5 and the gate + refuse a test added to a legacy file. +- Eight mirror files breach rule 8 today: three ordinary ones and five under + `legacy_refactoring/`. They are listed in + `devcapsule-src/tests/command_line_debt.txt`. The check refuses a line + whose file no longer needs it, and a line the base's list does not have. + 32 of the 102 legacy files reach the command line too; they meet the rule + when they are retired. +- Rule 9, at run time, in `tests/conftest.py`: `NetworkGuard`, on the + interpreter's audit hook, beside the repository-input guard. While a unit + test runs, a connect or a send to another machine, or a lookup of anything + but this machine, fails the test before anything is sent, with an + exception that `except Exception` does not catch; the session then ends + with a failing status and a list of the attempts. Loopback stays open. + Tests of the heavier suites are not held to it. + +**Evidence.** 27 faults planted in the new code, one at a time, in a scratch +copy: 23 caught by the unit tests of the checker and of the guard, 4 by the +new integration file `tests/integration/test_network_guard.py`, none +uncaught. The four are the wiring: the hook's installation, attending and +leaving a test, and failing a session whose breach failed no test. The +hosted pull-request gate does not run integration tests, so it does not +catch a break in that wiring. + +**Validation, in the capsule.** `nox -s typecheck`: mypy over 342 files +passes. `nox -s tests`: 17 failed, the standing ones by file and count, 3008 +passed, in 170 seconds with coverage; the guard names the one downloading +test, which now ends at once as the expected failure it is marked to be. +The convention check: 102 legacy files, 1350 legacy tests, 54 conforming +files, 0 breaches, 8 files in command-line debt. Five integration files, 94 +tests, pass. + +**Limits.** The import check does not see a test that starts the program as +a process; that is what an integration test does, and a unit test that did +it would breach rule 2 unseen. The network guard does not see the network +use of a program a test starts. `prepare_launch` reaches the same settings +and the same download without the command line; no rule names it yet. The +17 failures and their cause are untouched. + +**Next action.** The owner's: whether the eight files in debt are fixed +before 0.3.1, and the fix of the blocking bug. + ## The rule *Host Inputs*, and the partner's review of the rewrite — 2026-11-12 After reading the report of the section below, the owner asked for "a very From c92d5254680f4c2808747db630c040eea1d9b208 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 10:07:00 +0000 Subject: [PATCH 16/75] Maintenance status: the definition stamp after Unit Tests rules 8 and 9 Written by devcapsule0 workflow publish, coordination f4a63eefc722. Co-Authored-By: Claude --- engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index b1c79e20..fca71942 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -6,7 +6,7 @@ Start date: 2026-09-18 State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test -Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@d0a571433a6c +Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@4e9a93c9f73a Integration target: `main` From 1730cc17c3707206ae2bff3a29887ee8af66c25f Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 12:11:13 +0000 Subject: [PATCH 17/75] Launch: read, decide in memory, write; the decisions are testable from values Owner direction of 2026-11-12: read the configuration into memory first, decide second, and let a test of a decision skip the reading. - configuration/derivation.py: CheckoutState is a dataclass of values; load_state does all the reading. The state's methods no longer read the home's directory, the record's existence or the console's requests. - commands/_launch_review.py, new: review_launch(state, flags, ask=...) is the decision phase. It returns a LaunchReview or refuses, and writes nothing. RunFlags and Prepared moved here; _run_flow still exports them. - commands/_run_flow.py: prepare_launch is three phases in order: read_launch_state, review_launch, save_launch. The terminal dialogue stays there and is passed to the review as ask. - tests/unit/devcapsule/commands/test_launch_review.py: 18 tests that build their checkout in memory, with no directory, no home and no patch. No caller and no legacy test changed. Evidence: the unit suite passes as before, 3026 passed with the capsule's 17 standing failures; with the mounted-settings fallback switched off it fails only the fallback's own two tests, before and after. 22 planted faults: 17 caught, 5 named in the maintenance status with the reason for each. Co-Authored-By: Claude --- .../devcapsule/commands/_launch_review.py | 387 +++++++++++++++++ .../devcapsule/commands/_run_flow.py | 393 +++++------------- .../devcapsule/configuration/derivation.py | 137 ++++-- .../devcapsule/commands/test_launch_review.py | 229 ++++++++++ 4 files changed, 817 insertions(+), 329 deletions(-) create mode 100644 devcapsule-src/devcapsule/commands/_launch_review.py create mode 100644 devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py diff --git a/devcapsule-src/devcapsule/commands/_launch_review.py b/devcapsule-src/devcapsule/commands/_launch_review.py new file mode 100644 index 00000000..6643f558 --- /dev/null +++ b/devcapsule-src/devcapsule/commands/_launch_review.py @@ -0,0 +1,387 @@ +"""The review of a launch: what ``project run`` decides, in memory, from what was read. + +``project run`` prepares a launch in three phases, and +:func:`devcapsule.commands._run_flow.prepare_launch` shows them in order: + +1. Read. The project, the home and the checkout's record become a + :class:`~devcapsule.configuration.derivation.CheckoutState`; the command + line becomes a :class:`RunFlags`. +2. Decide. :func:`review_launch`, here: the state and the flags in, a + :class:`LaunchReview` out, or a refusal. Answers are staged on copies in + memory. Nothing is written. +3. Write. ``_run_flow.save_launch`` writes what the review staged. + +A test of a decision builds a state from documents it writes as values, calls +:func:`review_launch`, and reads the result. It needs no project directory and +no home. + +What this phase still takes from the host, each to be passed in as a value in +a later change: + +- the listing asks ``os.environ`` whether a host variable is set, and the + file system whether a bound directory exists; +- :func:`~devcapsule.configuration.derivation.derive_plan` asks the Docker + daemon for a local base image when the checkout selects one; +- accepting a channel stamps the acceptance with the clock; +- a run-once authorization is announced on standard error; +- the function given as ``ask`` talks to the developer, and its answer to a + console request runs a command that writes. +""" + +from __future__ import annotations + +from copy import deepcopy +from dataclasses import dataclass, field +from pathlib import Path +import shlex +import sys +from typing import Any, Callable, Mapping + +from devcapsule.compat import DecisionPending +from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value +from devcapsule.configuration.capabilities import ( + IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture, capability_notes, +) +from devcapsule.configuration.derivation import CheckoutState, Selection, derive_plan +from devcapsule.configuration.docker_arguments import validate_name, validate_value +from devcapsule.configuration.file_formats import ProjectConfigurationError +from devcapsule.configuration.listing import Decision +from devcapsule.configuration.manifest_document import Recommendations +from devcapsule.configuration.operations import CheckoutRecord +from devcapsule.configuration.storage import ResolvedProject +from devcapsule.configuration.trust import Channel, HomeTrust, channels_for +from devcapsule.configuration.values import legacy_memory_names, memory_size_bytes, normalize_launcher_value + +__all__ = [ + "BLOCKING_KINDS", "Ask", "LaunchReview", "Prepared", "RunFlags", "capability", "channel_for", + "refuse_contradictory_flags", "render_pending", "requested_ide", "review_launch", "stage_trust", +] + +BLOCKING_KINDS = {"ide", "env", "renew", "trust", "consent", "value", "secret"} +"""The kinds of decision a launch cannot go on without.""" + + +@dataclass(frozen=True) +class RunFlags: + """Run-once choices unless ``save``; trust is saved after the complete review, even without ``save``.""" + + ide: str | None = None + capabilities: tuple[str, ...] = () + providers: tuple[tuple[str, str], ...] = () + memory: str | None = None + cpus: str | None = None + environment: tuple[str, ...] = () # NAME=VALUE saved for this run, or NAME taken from the host + authorize: tuple[tuple[str, str], ...] = () # (node, value) + trust: tuple[str, ...] = () # channel ids, recorded only after every blocking decision is settled + save: bool = False + allow_unverified: bool = False + # Launch with the IDE given by ``ide`` although the project requires + # another: one named departure from the project's contract, for this + # launch only, warned and recorded, never saved (work order of 2026-10-28). + force: bool = False + + +@dataclass +class Prepared: + """What the launch runs with: the derived plan and this run's overrides.""" + + selected: ResolvedProject + host_overrides: dict[str, Any] = field(default_factory=dict) + memory_override: int | None = None + cpus_override: int | None = None + environment_tokens: list[str] = field(default_factory=list) + notes: list[str] = field(default_factory=list) + home: dict[str, Any] = field(default_factory=dict) + + +@dataclass +class LaunchReview: + """What the review decided and staged. None of it is written yet.""" + + state: CheckoutState + """The state the review worked on, with the home's trust and the saved environment as the answers left them.""" + record: CheckoutRecord + """The checkout's record with every recorded answer staged on it.""" + original: dict[str, Any] + """The record's document as the review found it; the record is written only when it differs.""" + environment: dict[str, str | None] + """The variables to save with the checkout's Docker arguments; None for one taken from the host.""" + accepted: list[str] + """The channels accepted for the home during this review, in the order accepted.""" + selected: ResolvedProject + """The derived plan.""" + host_overrides: dict[str, Any] + memory_override: int | None + cpus_override: int | None + environment_tokens: list[str] + notes: list[str] + saved: bool + """Whether ``--save`` was given: the flags then became the checkout's answers, not this run's overrides.""" + + def prepared(self) -> Prepared: + """The launch as the review leaves it, for a caller that writes nothing (``--print-command``).""" + return Prepared(self.selected, self.host_overrides, self.memory_override, self.cpus_override, + self.environment_tokens, self.notes, self.state.home) + + +Ask = Callable[ + [CheckoutState, CheckoutRecord, dict[str, Any], Decision, dict[str, Any], dict[str, "str | None"], list[str], RunFlags], + None, +] +"""Put one decision to the developer and stage the answer. + +The arguments are the state, the staged record, the checkout document the +decision was assessed on, the decision, and the three collections an answer +can add to: the run-once host overrides, the variables to save, and the +channels accepted. It raises :class:`DecisionPending` when the developer +declines a decision the launch cannot go on without. +""" + + +def refuse_contradictory_flags(flags: RunFlags) -> None: + """Refuse a command line that contradicts itself. It needs nothing but the flags.""" + if flags.force and flags.ide is None: + raise ProjectConfigurationError( + "--force names no departure; give the IDE to run instead of the project's required one: --ide IDE --force." + ) + if flags.force and flags.save: + # The owner requires a choice: save an allowed IDE or depart for one launch. + raise ProjectConfigurationError( + "--force applies to one launch and cannot be combined with --save. Launch without --save, " + "or save a choice the project allows without --force." + ) + + +def review_launch( + state: CheckoutState, + flags: RunFlags, + *, + ask: Ask | None, + print_only: bool = False, + check_display: bool = True, +) -> LaunchReview: + """Phase 2 of a launch's preparation: decide, in memory, from the state and the flags. + + ``ask`` is how a decision reaches the developer; None when there is no + terminal. Without it, and always under ``print_only``, an unanswered + decision the launch cannot go on without raises :class:`DecisionPending` + that names each one. An invalid request raises + :class:`ProjectConfigurationError`. Either way nothing has been written, + because this function writes nothing. + + The state must name the checkout's record: ``input_path`` is the record + found or the one the checkout will get. ``_run_flow.read_launch_state`` + sees to that. + """ + refuse_contradictory_flags(flags) + if flags.ide is not None: + # Refused, or noted on the state as this launch's departure, before any approval is reviewed. + requested_ide(state, flags) + manifest = state.manifest + assert state.input_path is not None, "the state names no record for the checkout" + input_path = state.input_path + record = CheckoutRecord.staged(input_path, state.checkout) + original = deepcopy(record.document) + notes: list[str] = list(capability_notes(manifest)) + # Channels accepted for this home, by flag or at the terminal: + # staged on the state's home document, written with the record. + accepted: list[str] = [] + host_overrides: dict[str, Any] = {} + environment: dict[str, str | None] = {} + environment_tokens: list[str] = [] + memory_override = None if flags.memory is None else memory_size_bytes(str(normalize_launcher_value("memory", flags.memory))) + cpus_override = None if flags.cpus is None else int(normalize_launcher_value("cpus", flags.cpus)) + for item in flags.environment: + name, separator, value = item.partition("=") + validate_name(name) + if separator: + validate_value(value) + state.saved_environment[name] = value if separator else None + environment_tokens.extend(["--env", item]) + if flags.save: + environment[name] = value if separator else None + if flags.save: + record.document = _selected_checkout(state, record.export(), flags) + record = CheckoutRecord.staged(input_path, record.document) + _resource_answers(record, manifest, flags) + for node, value in flags.authorize: + declaration = authorization_declarations(manifest, state.composed_lock(record.document)).get(node) + if declaration is None or (declaration.required and not flags.save): + raise ProjectConfigurationError(f"Authorization {node!r} cannot be answered for one run; the host accesses can.") + normalized = normalize_authorization_value(declaration, value) + if flags.save: + record.authorize(declaration, normalized) + else: + host_overrides[node] = normalized + print(f"Run-once authorization: {node} = {value}", file=sys.stderr) + + def launch_checkout() -> dict[str, Any]: + """The checkout document this launch runs on: the staged record with the run-once choices laid over it.""" + saved = record.export() + document = _selected_checkout(state, saved, flags) if not flags.save else saved + local = Selection(LocalCapabilities.read(document), state.surfaces) + recommended_ide = Recommendations.read(manifest).ide + # A lock that still pins an IDE (written when the project required + # one) stands for every checkout that chose none; the recommended IDE + # is the default only when the lock is project-only. + pinned_surface = state.composed_lock(document).get("components", {}).get("interactive-surface") + if (local.ide is None and recommended_ide is not None and pinned_surface is None + and not (set(CapabilityPolicy.read(manifest).required) & set(state.surfaces))): + local.ide = recommended_ide + document = state.with_selection(local, checkout=document, allow_unverified=flags.allow_unverified) + transient = CheckoutRecord.staged(input_path, document) + if not flags.save: + _resource_answers(transient, manifest, flags) + declarations = authorization_declarations(manifest, state.composed_lock(document)) + for name, value in host_overrides.items(): + transient.authorize(declarations[name], value) + return transient.export() + + # Assess, ask one decision, assess again: an answer can add decisions, as an IDE adds its consents. + asked: set[tuple[str, str]] = set() + while True: + checkout = launch_checkout() + for channel_id in flags.trust: + if channel_id not in accepted: + stage_trust(state, checkout, channel_id, accepted) + decisions = list(state.listing(checkout, check_display=check_display).decisions) + blocking = [d for d in decisions if d.kind in BLOCKING_KINDS] + if blocking and (print_only or ask is None): + raise DecisionPending(render_pending(blocking, state.root)) + pending = [d for d in decisions if (d.kind, d.name) not in asked] + if not pending or print_only or ask is None: + if blocking: + raise DecisionPending(render_pending(blocking, state.root)) + for decision in decisions: + if decision.kind == "console": + notes.append( + f"The console's request {decision.name} of {decision.reason} awaits your confirmation: " + f"{decision.description}. Apply or discard: {decision.command}" + ) + else: + notes.append( + f"The project asks for {decision.description} ({decision.reason}); not granted this run. " + f"Allow or deny: {decision.command}" + ) + break + decision = pending[0] + asked.add((decision.kind, decision.name)) + ask(state, record, checkout, decision, host_overrides, environment, accepted, flags) + + # Validation can still refuse (for example, an invalid binding). Derive + # first so neither --save nor a terminal answer escapes on that path. + selected = derive_plan(state, checkout, write=False) + for row in state.listing(checkout, check_display=check_display).rows: + if row.kind == "access" and "(kept;" in row.source: + notes.append(f"Host access {row.name}: {row.effective}; {row.source}.") + return LaunchReview( + state=state, record=record, original=original, environment=environment, accepted=accepted, + selected=selected, host_overrides=host_overrides, memory_override=memory_override, + cpus_override=cpus_override, environment_tokens=environment_tokens, notes=notes, saved=flags.save, + ) + + +def _resource_answers(record: CheckoutRecord, manifest: Mapping[str, Any], flags: RunFlags) -> None: + """Stage ``--memory`` and ``--cpus`` on a record as the checkout's values.""" + for name, value in (("memory", flags.memory), ("cpus", flags.cpus)): + if value is not None: + record.set_value(name, normalize_launcher_value(name, value)) + if name == "memory": + for alias in legacy_memory_names(manifest): + record.values.pop(alias, None) + record.omitted_values.discard(alias) + + +def _selected_checkout(state: CheckoutState, document: dict[str, Any], flags: RunFlags) -> dict[str, Any]: + """The checkout document with the IDE, capabilities and providers of the flags selected on it.""" + if flags.ide is None and not flags.capabilities and not flags.providers: + return document + selection = Selection(LocalCapabilities.read(document), state.surfaces) + if flags.ide is not None: + selection.ide = requested_ide(state, flags) + for name in flags.capabilities: + canonical = state.matrix.canonical_name(name) + if state.matrix.is_ide(canonical): + raise ProjectConfigurationError(f"Choose an IDE with '--ide {canonical}'.") + selection.without = {item for item in selection.without if state.matrix.canonical_name(item) != canonical} + selection.extra.add(canonical) + for name, component in flags.providers: + selection.use(state.matrix, CapabilityPolicy.read(state.manifest), Recommendations.read(state.manifest), name, component) + return state.with_selection(selection, checkout=document, allow_unverified=flags.allow_unverified) + + +def requested_ide(state: CheckoutState, flags: RunFlags) -> str: + """The IDE capability ``--ide`` names, checked against the project's required IDE. + + A component name (``codium``) or a capability name (``frontend-ide``) + selects the same surface. Another IDE than the project requires is + refused with the explicit override named; with ``--force`` it is one + named departure of this launch (:data:`IDE_REQUIREMENT`), and the plan + derives from the policy without that requirement. ``--force`` with + nothing to set aside is refused: it never selects a replacement itself. + """ + assert flags.ide is not None + requested = capability(flags.ide, state.surfaces, "IDE") + required = state.required_ide() + conflicts = required is not None and state.matrix.canonical_name(required) != state.matrix.canonical_name(requested) + if conflicts: + assert required is not None + required_component = state.shared_lock.get("components", {}).get("interactive-surface") or state.surfaces[required] + if not flags.force: + override = shlex.join(["devcapsule", "project", "--path", str(state.root), "run", "--ide", flags.ide.strip(), "--force"]) + raise ProjectConfigurationError( + f"The project requires {required} ({required_component}); {requested} ({state.surfaces[requested]}) is " + f"another IDE. To launch it once, setting the requirement aside for that launch only: {override}. " + "The project's requirement and this checkout's saved IDE stay as they are." + ) + state.depart(RequirementDeparture(IDE_REQUIREMENT, required, requested)) + elif flags.force: + raise ProjectConfigurationError( + f"--force has nothing to set aside: {requested} is the project's required IDE." + if required is not None else + f"--force has nothing to set aside: the project requires no IDE; '--ide {flags.ide.strip()}' alone launches {requested}." + ) + return requested + + +def channel_for(lock: Mapping[str, Any], channel_id: str) -> Channel: + """The channel ``channel_id`` of a lock; refused with the lock's channels when unknown.""" + channels = channels_for(lock) + channel = channels.get(channel_id) + if channel is None: + raise ProjectConfigurationError( + f"No channel {channel_id!r} on this project; its channels: " + (", ".join(sorted(channels)) or "none") + "." + ) + return channel + + +def stage_trust(state: CheckoutState, checkout: Mapping[str, Any], channel_id: str, accepted: list[str]) -> None: + """Stage the acceptance of ``channel_id`` on the state's home document; written with the answers.""" + channel = channel_for(state.composed_lock(checkout), channel_id) + trust = HomeTrust.read(state.home).with_channel(channel) + state.home = {**state.home, "trust": trust.document()} + if channel_id not in accepted: + accepted.append(channel_id) + + +def capability(value: str, names: Mapping[str, str], kind: str) -> str: + """The capability a developer's word names: a capability name, or the component that provides one.""" + candidate = value.strip() + by_component = {component: name for name, component in names.items()} + candidate = by_component.get(candidate, candidate) + if candidate not in names: + raise ProjectConfigurationError(f"Unknown {kind} {value!r}; choose one of {', '.join(sorted(names))}.") + return candidate + + +def render_pending(decisions: list[Decision], root: Path) -> str: + """The status-3 text: every answer is still staged, including trust.""" + lines = ["the launch of this checkout needs answers:"] + for decision in decisions: + flag = {"ide": "--ide IDE", "env": f"--env {decision.name}=VALUE", "consent": f"--authorize {decision.name} {decision.value}" if decision.name == "host-x11" else "", + "access": f"--authorize {decision.name} {decision.value}", "renew": f"--authorize {decision.name} {decision.value}", + "trust": f"--trust {decision.name}", "value": "", "secret": "", "console": ""}[decision.kind] + lines.append(f" {decision.kind} {decision.name}: {decision.description}" + (f" ({decision.reason})" if decision.reason else "")) + lines.append(" " + (f"{flag} | " if flag else "") + decision.command) + lines.append("Nothing was written. Answer on the command line or in a terminal.") + return "\n".join(lines) diff --git a/devcapsule-src/devcapsule/commands/_run_flow.py b/devcapsule-src/devcapsule/commands/_run_flow.py index dcb09e2a..2e895f92 100644 --- a/devcapsule-src/devcapsule/commands/_run_flow.py +++ b/devcapsule-src/devcapsule/commands/_run_flow.py @@ -24,86 +24,29 @@ from __future__ import annotations from copy import deepcopy -from dataclasses import dataclass, field import getpass from pathlib import Path -import shlex import sys -from typing import Any, Callable, Mapping, TextIO +from typing import Any, Callable, TextIO +from devcapsule.commands._launch_review import ( + LaunchReview, Prepared, RunFlags, capability, channel_for, refuse_contradictory_flags, render_pending, + requested_ide, review_launch, stage_trust, +) from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import HOME_CAPABILITY_DEFAULTS, authorization_declarations, normalize_authorization_value -from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture -from devcapsule.configuration.derivation import CheckoutState, Selection, derive_plan, load_state, register_checkout -from devcapsule.configuration.docker_arguments import arguments_path, read_environment, update_environment, validate_name, validate_value -from devcapsule.configuration.file_formats import ProjectConfigurationError, render_toml -from devcapsule.configuration.manifest_document import Recommendations +from devcapsule.configuration.capabilities import LocalCapabilities +from devcapsule.configuration.console_requests import deferred_rows +from devcapsule.configuration.derivation import CheckoutState, Selection, load_state, register_checkout +from devcapsule.configuration.docker_arguments import arguments_path, read_environment, update_environment, validate_value +from devcapsule.configuration.file_formats import render_toml from devcapsule.configuration.listing import Decision from devcapsule.configuration.operations import CheckoutRecord, apply_configuration_answers, ProvidedAnswer from devcapsule.configuration.storage import ResolvedProject, atomic_write, checkout_name_for, manifest_for, write_settings -from devcapsule.configuration.trust import Channel, HomeTrust, channels_for -from devcapsule.configuration.values import legacy_memory_names, memory_size_bytes, normalize_launcher_value +from devcapsule.configuration.trust import Channel, HomeTrust __all__ = ["Prepared", "RunFlags", "prepare_launch"] -BLOCKING_KINDS = {"ide", "env", "renew", "trust", "consent", "value", "secret"} - - -@dataclass(frozen=True) -class RunFlags: - """Run-once choices unless ``save``; trust is saved after the complete review, even without ``save``.""" - - ide: str | None = None - capabilities: tuple[str, ...] = () - providers: tuple[tuple[str, str], ...] = () - memory: str | None = None - cpus: str | None = None - environment: tuple[str, ...] = () # NAME=VALUE saved for this run, or NAME taken from the host - authorize: tuple[tuple[str, str], ...] = () # (node, value) - trust: tuple[str, ...] = () # channel ids, recorded only after every blocking decision is settled - save: bool = False - allow_unverified: bool = False - # Launch with the IDE given by ``ide`` although the project requires - # another: one named departure from the project's contract, for this - # launch only, warned and recorded, never saved (work order of 2026-10-28). - force: bool = False - - -@dataclass -class Prepared: - """What the launch runs with: the derived plan and this run's overrides.""" - - selected: ResolvedProject - host_overrides: dict[str, Any] = field(default_factory=dict) - memory_override: int | None = None - cpus_override: int | None = None - environment_tokens: list[str] = field(default_factory=list) - notes: list[str] = field(default_factory=list) - home: dict[str, Any] = field(default_factory=dict) - - -def load_launch_state(start: Path, flags: RunFlags) -> CheckoutState: - """Load the launch inputs and reject invalid IDE requests before any approval review. - - Departures are applied in memory. The staged launch review still checks - consent, trust, dependencies and host access for the requested environment. - """ - if flags.force and flags.ide is None: - raise ProjectConfigurationError( - "--force names no departure; give the IDE to run instead of the project's required one: --ide IDE --force." - ) - if flags.force and flags.save: - # The owner requires a choice: save an allowed IDE or depart for one launch. - raise ProjectConfigurationError( - "--force applies to one launch and cannot be combined with --save. Launch without --save, " - "or save a choice the project allows without --force." - ) - root, manifest = manifest_for(start) - state = load_state(root, manifest) - if flags.ide is not None: - _requested_ide(state, flags) - return state - def prepare_launch( start: Path, @@ -115,189 +58,91 @@ def prepare_launch( print_only: bool = False, check_display: bool = True, ) -> Prepared: - """Review in memory, then save answers and the plan after every blocking decision. + """Prepare a launch in three phases: read, decide in memory, write. ``print_only`` never asks or writes. Without a terminal, an unanswered blocking decision raises :class:`DecisionPending` before any write. """ + # A command line that contradicts itself is refused before anything is read. + refuse_contradictory_flags(flags) + + # Phase 1, read: the project, the home and the checkout's record, and what the terminal is. + state = read_launch_state(start) interactive = sys.stdin.isatty() if interactive is None else interactive - output = output_stream if output_stream is not None else sys.stdout - state = load_launch_state(start, flags) - root, manifest = state.root, state.manifest - input_path = register_checkout(state, write=False) - record = CheckoutRecord.staged(input_path, state.checkout) - original = deepcopy(record.document) - from devcapsule.configuration.capabilities import capability_notes - notes: list[str] = list(capability_notes(manifest)) - # Channels accepted for this home, by flag or at the terminal: - # staged on the state's home document, written with the record. - accepted: list[str] = [] - host_overrides: dict[str, Any] = {} - environment: dict[str, str | None] = {} - environment_tokens: list[str] = [] - memory_override = None if flags.memory is None else memory_size_bytes(str(normalize_launcher_value("memory", flags.memory))) - cpus_override = None if flags.cpus is None else int(normalize_launcher_value("cpus", flags.cpus)) - for item in flags.environment: - name, separator, value = item.partition("=") - validate_name(name) - if separator: - validate_value(value) - state.saved_environment[name] = value if separator else None - environment_tokens.extend(["--env", item]) - if flags.save: - environment[name] = value if separator else None - if flags.save: - record.document = _selected_checkout(state, record.export(), flags) - record = CheckoutRecord.staged(input_path, record.document) - _resource_answers(record, manifest, flags) - for node, value in flags.authorize: - declaration = authorization_declarations(manifest, state.composed_lock(record.document)).get(node) - if declaration is None or (declaration.required and not flags.save): - raise ProjectConfigurationError(f"Authorization {node!r} cannot be answered for one run; the host accesses can.") - normalized = normalize_authorization_value(declaration, value) - if flags.save: - record.authorize(declaration, normalized) - else: - host_overrides[node] = normalized - print(f"Run-once authorization: {node} = {value}", file=sys.stderr) - - def launch_checkout() -> dict[str, Any]: - saved = record.export() - document = _selected_checkout(state, saved, flags) if not flags.save else saved - local = Selection(LocalCapabilities.read(document), state.surfaces) - recommended_ide = Recommendations.read(manifest).ide - # A lock that still pins an IDE (written when the project required - # one) stands for every checkout that chose none; the recommended IDE - # is the default only when the lock is project-only. - pinned_surface = state.composed_lock(document).get("components", {}).get("interactive-surface") - if (local.ide is None and recommended_ide is not None and pinned_surface is None - and not (set(CapabilityPolicy.read(manifest).required) & set(state.surfaces))): - local.ide = recommended_ide - document = state.with_selection(local, checkout=document, allow_unverified=flags.allow_unverified) - transient = CheckoutRecord.staged(input_path, document) - if not flags.save: - _resource_answers(transient, manifest, flags) - declarations = authorization_declarations(manifest, state.composed_lock(document)) - for name, value in host_overrides.items(): - transient.authorize(declarations[name], value) - return transient.export() - - asked: set[tuple[str, str]] = set() reader = input_stream.readline if input_stream is not None else lambda: sys.stdin.readline() - while True: - checkout = launch_checkout() - for channel_id in flags.trust: - if channel_id not in accepted: - _stage_trust(state, checkout, channel_id, accepted) - decisions = list(state.listing(checkout, check_display=check_display).decisions) - blocking = [d for d in decisions if d.kind in BLOCKING_KINDS] - if blocking and (print_only or not interactive): - raise DecisionPending(_render_pending(blocking, root)) - pending = [d for d in decisions if (d.kind, d.name) not in asked] - if not pending or print_only or not interactive: - if blocking: - raise DecisionPending(_render_pending(blocking, root)) - for decision in decisions: - if decision.kind == "console": - notes.append( - f"The console's request {decision.name} of {decision.reason} awaits your confirmation: " - f"{decision.description}. Apply or discard: {decision.command}" - ) - else: - notes.append( - f"The project asks for {decision.description} ({decision.reason}); not granted this run. " - f"Allow or deny: {decision.command}" - ) - break - decision = pending[0] - asked.add((decision.kind, decision.name)) + output = output_stream if output_stream is not None else sys.stdout + + # Phase 2, decide: from the state and the flags alone. Nothing is written. + def ask_at_terminal( + state: CheckoutState, record: CheckoutRecord, checkout: dict[str, Any], decision: Decision, + host_overrides: dict[str, Any], environment: dict[str, str | None], accepted: list[str], flags: RunFlags, + ) -> None: _settle(state, record, checkout, decision, host_overrides, environment, accepted, flags, reader, output) - # Validation can still refuse (for example, an invalid binding). Derive - # first so neither --save nor a terminal answer escapes on that path. - selected = derive_plan(state, checkout, write=False) - for row in state.listing(checkout, check_display=check_display).rows: - if row.kind == "access" and "(kept;" in row.source: - notes.append(f"Host access {row.name}: {row.effective}; {row.source}.") - if not print_only: - if environment: - read_environment(arguments_path(input_path)) # Refuse ambiguous saved tokens before any write. - if not state.registered: - notes.append(f"Registered this checkout: {checkout_name_for(manifest, input_path)} ({root}).") - if not state.registered or record.document != original: - record.write() - for name, saved_value in environment.items(): - update_environment(arguments_path(input_path), name, saved_value, from_host=saved_value is None) - atomic_write(selected.resolution_path, render_toml(selected.resolution)) - if accepted: - write_settings({"trust": HomeTrust.read(state.home).document()}) - notes.extend(f"Accepted the channel {channel_id} for this home." for channel_id in accepted) - if flags.save: - notes.insert(0, "Recorded the flags given for this checkout.") - environment_tokens = [] - memory_override = cpus_override = None - return Prepared(selected, host_overrides, memory_override, cpus_override, environment_tokens, notes, state.home) - - -def _resource_answers(record: CheckoutRecord, manifest: Mapping[str, Any], flags: RunFlags) -> None: - for name, value in (("memory", flags.memory), ("cpus", flags.cpus)): - if value is not None: - record.set_value(name, normalize_launcher_value(name, value)) - if name == "memory": - for alias in legacy_memory_names(manifest): - record.values.pop(alias, None) - record.omitted_values.discard(alias) - - -def _selected_checkout(state: CheckoutState, document: dict[str, Any], flags: RunFlags) -> dict[str, Any]: - if flags.ide is None and not flags.capabilities and not flags.providers: - return document - selection = Selection(LocalCapabilities.read(document), state.surfaces) - if flags.ide is not None: - selection.ide = _requested_ide(state, flags) - for capability in flags.capabilities: - name = state.matrix.canonical_name(capability) - if state.matrix.is_ide(name): - raise ProjectConfigurationError(f"Choose an IDE with '--ide {name}'.") - selection.without = {item for item in selection.without if state.matrix.canonical_name(item) != name} - selection.extra.add(name) - for capability, component in flags.providers: - selection.use(state.matrix, CapabilityPolicy.read(state.manifest), Recommendations.read(state.manifest), capability, component) - return state.with_selection(selection, checkout=document, allow_unverified=flags.allow_unverified) - - -def _requested_ide(state: CheckoutState, flags: RunFlags) -> str: - """The IDE capability ``--ide`` names, checked against the project's required IDE. - - A component name (``codium``) or a capability name (``frontend-ide``) - selects the same surface. Another IDE than the project requires is - refused with the explicit override named; with ``--force`` it is one - named departure of this launch (:data:`IDE_REQUIREMENT`), and the plan - derives from the policy without that requirement. ``--force`` with - nothing to set aside is refused: it never selects a replacement itself. + review = review_launch(state, flags, ask=ask_at_terminal if interactive else None, + print_only=print_only, check_display=check_display) + + # Phase 3, write: what the review staged. + return review.prepared() if print_only else save_launch(review) + + +def read_launch_state(start: Path) -> CheckoutState: + """Phase 1 of a launch's preparation: read the project at ``start``, the home and the checkout's record. + + A checkout that has no record yet is given the path its record will have, + which can mean looking for a free name among the project's checkouts. + Nothing is written. """ - assert flags.ide is not None - requested = _capability(flags.ide, state.surfaces, "IDE") - required = state.required_ide() - conflicts = required is not None and state.matrix.canonical_name(required) != state.matrix.canonical_name(requested) - if conflicts: - assert required is not None - required_component = state.shared_lock.get("components", {}).get("interactive-surface") or state.surfaces[required] - if not flags.force: - override = shlex.join(["devcapsule", "project", "--path", str(state.root), "run", "--ide", flags.ide.strip(), "--force"]) - raise ProjectConfigurationError( - f"The project requires {required} ({required_component}); {requested} ({state.surfaces[requested]}) is " - f"another IDE. To launch it once, setting the requirement aside for that launch only: {override}. " - "The project's requirement and this checkout's saved IDE stay as they are." - ) - state.depart(RequirementDeparture(IDE_REQUIREMENT, required, requested)) - elif flags.force: - raise ProjectConfigurationError( - f"--force has nothing to set aside: {requested} is the project's required IDE." - if required is not None else - f"--force has nothing to set aside: the project requires no IDE; '--ide {flags.ide.strip()}' alone launches {requested}." - ) - return requested + root, manifest = manifest_for(start) + state = load_state(root, manifest) + register_checkout(state, write=False) + return state + + +def save_launch(review: LaunchReview) -> Prepared: + """Phase 3 of a launch's preparation: write what the review staged, and say what was written. + + The checkout's record, when new or changed; the variables saved with its + Docker arguments; the derived plan; the home's trust, when a channel was + accepted. With ``--save`` the flags are now the checkout's answers, so the + launch carries no run-once overrides of its own. + """ + state, record, selected = review.state, review.record, review.selected + notes = list(review.notes) + environment_tokens, memory_override, cpus_override = review.environment_tokens, review.memory_override, review.cpus_override + if review.environment: + read_environment(arguments_path(record.input_path)) # Refuse ambiguous saved tokens before any write. + if not state.registered: + notes.append(f"Registered this checkout: {checkout_name_for(state.manifest, record.input_path)} ({state.root}).") + if not state.registered or record.document != review.original: + record.write() + state.registered = True + for name, saved_value in review.environment.items(): + update_environment(arguments_path(record.input_path), name, saved_value, from_host=saved_value is None) + atomic_write(selected.resolution_path, render_toml(selected.resolution)) + if review.accepted: + write_settings({"trust": HomeTrust.read(state.home).document()}) + notes.extend(f"Accepted the channel {channel_id} for this home." for channel_id in review.accepted) + if review.saved: + notes.insert(0, "Recorded the flags given for this checkout.") + environment_tokens = [] + memory_override = cpus_override = None + return Prepared(selected, review.host_overrides, memory_override, cpus_override, environment_tokens, notes, state.home) + + +def load_launch_state(start: Path, flags: RunFlags) -> CheckoutState: + """Read the launch's inputs and refuse an invalid IDE request, before any approval is reviewed. + + For the command that offers software approvals ahead of the launch: the + same refusals :func:`prepare_launch` gives first, given early. A departure + is noted on the returned state, in memory. + """ + refuse_contradictory_flags(flags) + root, manifest = manifest_for(start) + state = load_state(root, manifest) + if flags.ide is not None: + requested_ide(state, flags) + return state def launch_listing_document(selected: ResolvedProject) -> dict[str, Any]: @@ -327,17 +172,7 @@ def launch_listing_document(selected: ResolvedProject) -> dict[str, Any]: def project_channel(root: Path, manifest: dict[str, Any], channel_id: str) -> Channel: """The channel ``channel_id`` of this project's lock; refused with the project's channels when unknown.""" state = load_state(root, manifest) - return _channel_for(state.composed_lock(), channel_id) - - -def _channel_for(lock: Mapping[str, Any], channel_id: str) -> Channel: - channels = channels_for(lock) - channel = channels.get(channel_id) - if channel is None: - raise ProjectConfigurationError( - f"No channel {channel_id!r} on this project; its channels: " + (", ".join(sorted(channels)) or "none") + "." - ) - return channel + return channel_for(state.composed_lock(), channel_id) def accept_channel(root: Path, manifest: dict[str, Any], channel_id: str) -> Path: @@ -347,43 +182,18 @@ def accept_channel(root: Path, manifest: dict[str, Any], channel_id: str) -> Pat return write_settings({"trust": HomeTrust.read(load_trust()).with_channel(channel).document()}) -def _stage_trust(state: CheckoutState, checkout: Mapping[str, Any], channel_id: str, accepted: list[str]) -> None: - """Stage the acceptance of ``channel_id`` on the state's home document; written with the answers.""" - channel = _channel_for(state.composed_lock(checkout), channel_id) - trust = HomeTrust.read(state.home).with_channel(channel) - state.home = {**state.home, "trust": trust.document()} - if channel_id not in accepted: - accepted.append(channel_id) - - -def _capability(value: str, names: Mapping[str, str], kind: str) -> str: - candidate = value.strip() - by_component = {component: name for name, component in names.items()} - candidate = by_component.get(candidate, candidate) - if candidate not in names: - raise ProjectConfigurationError(f"Unknown {kind} {value!r}; choose one of {', '.join(sorted(names))}.") - return candidate - - -def _render_pending(decisions: list[Decision], root: Path) -> str: - """The status-3 text: every answer is still staged, including trust.""" - lines = ["the launch of this checkout needs answers:"] - for decision in decisions: - flag = {"ide": "--ide IDE", "env": f"--env {decision.name}=VALUE", "consent": f"--authorize {decision.name} {decision.value}" if decision.name == "host-x11" else "", - "access": f"--authorize {decision.name} {decision.value}", "renew": f"--authorize {decision.name} {decision.value}", - "trust": f"--trust {decision.name}", "value": "", "secret": "", "console": ""}[decision.kind] - lines.append(f" {decision.kind} {decision.name}: {decision.description}" + (f" ({decision.reason})" if decision.reason else "")) - lines.append(" " + (f"{flag} | " if flag else "") + decision.command) - lines.append("Nothing was written. Answer on the command line or in a terminal.") - return "\n".join(lines) - - def _settle( state: CheckoutState, record: CheckoutRecord, checkout: dict[str, Any], decision: Decision, host_overrides: dict[str, Any], environment: dict[str, str | None], accepted: list[str], flags: RunFlags, reader: Callable[[], str], output: TextIO, ) -> None: - """Stage one answer. Reassess before the next question; an IDE can add consents.""" + """Put one decision to the developer at the terminal and stage the answer. + + The review assesses again before the next question, since an IDE can add + consents. Everything is staged in memory, with one exception: applying or + discarding a console request runs that command now, which writes, and the + state is then brought up to date with what the command left. + """ root, manifest = state.root, state.manifest if decision.kind == "ide": output.write("The project leaves the IDE to you. Choose one:\n") @@ -391,7 +201,7 @@ def _settle( output.write(f" {index}. {name:<13} {version}\n") choice = _ask(output, reader, f"IDE [1-{len(decision.choices)}]: ") names = [name for name, _ in decision.choices] - picked = names[int(choice) - 1] if choice.isdecimal() and 1 <= int(choice) <= len(names) else _capability(choice, state.surfaces, "IDE") + picked = names[int(choice) - 1] if choice.isdecimal() and 1 <= int(choice) <= len(names) else capability(choice, state.surfaces, "IDE") selection = Selection(LocalCapabilities.read(record.document), state.surfaces) selection.ide = picked selected = state.with_selection(selection, checkout=record.document, allow_unverified=flags.allow_unverified) @@ -435,8 +245,11 @@ def changed(target: dict[str, Any], old: dict[str, Any], new: dict[str, Any]) -> state.checkout = record.export() state.home = changed(state.home, before.home, after.home) state.saved_environment = {**after.saved_environment, **environment} + # The state is a snapshot; the command just changed what it was read from. + state.registered, state.deferred = after.registered, after.deferred elif answer in {"d", "discard"}: discard_deferred(record.input_path, decision.name) + state.deferred = tuple(deferred_rows(state.input_path, state.root)) output.write("Discarded.\n") else: output.write(f"Kept. Apply or discard later: {decision.command}\n") @@ -446,12 +259,12 @@ def changed(target: dict[str, Any], old: dict[str, Any], new: dict[str, Any]) -> output.write(f" {decision.reason}\n") answer = _ask(output, reader, "Accept for this DevCapsule home? [y/N]: ").lower() if answer in {"y", "yes"}: - _stage_trust(state, checkout, decision.name, accepted) + stage_trust(state, checkout, decision.name, accepted) output.write(f"Accepted for this review. Trust will be saved when all required answers are complete. " f"Withdraw: devcapsule home trust withdraw {decision.name}\n") else: output.write(f"Not accepted. Accept later: {decision.command}\n") - raise DecisionPending(_render_pending([decision], root)) + raise DecisionPending(render_pending([decision], root)) elif decision.kind in {"access", "renew", "consent"}: declaration = authorization_declarations(manifest, state.composed_lock(checkout))[decision.name] if decision.kind in {"access", "renew"}: @@ -474,7 +287,7 @@ def changed(target: dict[str, Any], old: dict[str, Any], new: dict[str, Any]) -> elif decision.kind == "access": output.write(f"Not now; the secure default applies. Allow or deny later: {decision.command}\n") else: - raise DecisionPending(_render_pending([decision], root)) + raise DecisionPending(render_pending([decision], root)) elif decision.kind == "value": value = _ask(output, reader, f"{decision.name} ({decision.description}): ") apply_configuration_answers((ProvidedAnswer("set", decision.name, value),), manifest, state.composed_lock(checkout), record) @@ -485,7 +298,7 @@ def changed(target: dict[str, Any], old: dict[str, Any], new: dict[str, Any]) -> apply_configuration_answers((ProvidedAnswer("bind", decision.name, f"host-environment:{decision.variable}"),), manifest, state.composed_lock(checkout), record) else: - raise DecisionPending(_render_pending([decision], root)) + raise DecisionPending(render_pending([decision], root)) def _ask(output: TextIO, reader: Callable[[], str], prompt: str) -> str: diff --git a/devcapsule-src/devcapsule/configuration/derivation.py b/devcapsule-src/devcapsule/configuration/derivation.py index 89afb695..006282af 100644 --- a/devcapsule-src/devcapsule/configuration/derivation.py +++ b/devcapsule-src/devcapsule/configuration/derivation.py @@ -14,11 +14,19 @@ over it when asked), derives and writes the resolution, and hands the launch a :class:`ResolvedProject`. Asking the developer is the command's job; the structured decisions come from the listing. + +Reading and deciding are apart here. :func:`load_state` reads: it is the only +place that opens the project's lock, the home's settings and the checkout's +record. :class:`CheckoutState` holds what was read and answers from it, in +memory. A test of a decision builds a state from documents it writes as +values and never calls :func:`load_state`. """ from __future__ import annotations from copy import deepcopy +from dataclasses import dataclass, field +from functools import cached_property from pathlib import Path import tomllib import shlex @@ -26,6 +34,7 @@ from devcapsule.compat import DecisionPending from devcapsule.materialization import validate_base_image +from devcapsule.platforms import Platform from devcapsule.project import sanitize_name from devcapsule.resolution_matrix import MATRICES, ResolutionMatrix, known_base_image @@ -35,7 +44,7 @@ from .capability_selection import compose_lock, effective_lock, local_pins, inspection_capabilities, inspection_providers, known_policy_names from .console_requests import deferred_rows from .file_formats import ProjectConfigurationError, canonical_digest, render_checkout, render_toml -from .listing import Listing, assess_checkout +from .listing import Listing, ListingRow, assess_checkout from .model import Configuration from .manifest_document import Recommendations from .trust import HomeTrust @@ -102,44 +111,55 @@ def use(self, matrix: ResolutionMatrix, policy: CapabilityPolicy, recommendation self.providers[name] = component +@dataclass class CheckoutState: - """One checkout's documents as loaded for a launch, registered or not, writing nothing on load.""" - - def __init__(self, root: Path, manifest: dict[str, Any]) -> None: - self.root = root - self.manifest = manifest - self.platform = project_platform(root) - self.matrix = MATRICES[self.platform] - self.surfaces = {name: self.matrix.resolve_provider(name) or name for name in self.matrix.ide_capabilities()} - self.lock_path, self.shared_lock = recommendation_lock_for(root, manifest) - self.home = load_settings() - # The named departures of this launch from the project's contract - # (``project run --ide IDE --force``). In memory only: the manifest, - # the lock and the record are never written with them. - self.departures: tuple[RequirementDeparture, ...] = () - record = find_checkout_record(manifest, root) - self.input_path: Path | None = record - self.checkout: dict[str, Any] = load_checkout(record, manifest, root) if record is not None else tomllib.loads( - render_checkout(manifest, root, {}, {}) - ) - if record is None: - try: - self.input_path, _ = checkout_record_paths(manifest, root) - except ProjectConfigurationError: - self.input_path = None # the default record belongs to another checkout of this project - self.saved_environment: dict[str, str | None] = {} - if record is not None: - read_arguments(arguments_path(record)) # Malformed storage is a refusal. - try: - self.saved_environment = read_environment(arguments_path(record)) - except ProjectConfigurationError: - # Ambiguous Docker tokens remain literal passthrough. They - # cannot establish answers to declared environment inputs. - self.saved_environment = {} + """One checkout's documents and surroundings, in memory. + + Nothing here opens a file or reads the environment. :func:`load_state` + does that and builds a state; a test builds one from values. The review + of a launch changes the state as answers are staged: the home's trust, + the saved environment, the departures. + """ + + root: Path + """The project's directory.""" + manifest: dict[str, Any] + platform: Platform + """The capsule platform this host runs the project as.""" + lock_path: Path + shared_lock: dict[str, Any] + """The project's committed lock for ``platform``, as ``lock_path`` holds it.""" + home: dict[str, Any] + """The home's settings document.""" + home_path: Path + """The home's directory, which the listing names in what it tells the developer.""" + input_path: Path | None + """The checkout's record: the one found, or the default one it would get. + + None when the checkout has no record and the default one belongs to + another checkout of the project; :func:`register_checkout` then names one. + """ + registered: bool + """Whether the record at ``input_path`` exists.""" + checkout: dict[str, Any] + """The record's document; for an unregistered checkout, the empty record it would start with.""" + saved_environment: dict[str, str | None] = field(default_factory=dict) + """The variables saved with the checkout's Docker arguments; None for one taken from the host.""" + deferred: tuple[ListingRow, ...] = () + """The console's requests that await the developer's confirmation, as listing rows.""" + departures: tuple[RequirementDeparture, ...] = () + """The named departures of this launch from the project's contract + (``project run --ide IDE --force``). In memory only: the manifest, the + lock and the record are never written with them.""" @property - def registered(self) -> bool: - return self.input_path is not None and self.input_path.is_file() + def matrix(self) -> ResolutionMatrix: + return MATRICES[self.platform] + + @cached_property + def surfaces(self) -> dict[str, str]: + """Each IDE capability of the platform with the component that provides it.""" + return {name: self.matrix.resolve_provider(name) or name for name in self.matrix.ide_capabilities()} @property def policy(self) -> CapabilityPolicy: @@ -178,14 +198,14 @@ def listing(self, checkout: Mapping[str, Any] | None = None, *, check_display: b providers = inspection_providers(self.manifest, lock, document) listing = assess_checkout( self.manifest, self.shared_lock, lock, document, - home_path=config_root(), home=self.home, saved_environment=self.saved_environment, + home_path=self.home_path, home=self.home, saved_environment=self.saved_environment, surfaces=self.surfaces, project=self.root, registered=self.registered, access_lock=access_lock, capability_versions=versions, capability_providers=providers, base_display=base.contract.display if check_display and base is not None else None, departures=self.departures, ) - return Listing(listing.rows + tuple(deferred_rows(self.input_path, self.root)), listing.notes, listing.departures) + return Listing(listing.rows + self.deferred, listing.notes, listing.departures) def with_selection(self, selection: Selection, *, allow_unverified: bool = False, checkout: Mapping[str, Any] | None = None) -> dict[str, Any]: @@ -213,7 +233,41 @@ def with_selection(self, selection: Selection, *, allow_unverified: bool = False def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: - return CheckoutState(root, manifest) + """Read one checkout's documents and surroundings into memory. Nothing is written. + + This is the reading half of every command that works on a checkout: the + platform and its committed lock from the project, the settings from the + home, the checkout's record or the path it would get, the environment + saved with its Docker arguments, and the console's deferred requests. + """ + platform = project_platform(root) + lock_path, shared_lock = recommendation_lock_for(root, manifest) + home = load_settings() + record = find_checkout_record(manifest, root) + input_path: Path | None = record + if record is not None: + checkout = load_checkout(record, manifest, root) + else: + checkout = tomllib.loads(render_checkout(manifest, root, {}, {})) + try: + input_path, _ = checkout_record_paths(manifest, root) + except ProjectConfigurationError: + input_path = None # the default record belongs to another checkout of this project + saved_environment: dict[str, str | None] = {} + if record is not None: + read_arguments(arguments_path(record)) # Malformed storage is a refusal. + try: + saved_environment = read_environment(arguments_path(record)) + except ProjectConfigurationError: + # Ambiguous Docker tokens remain literal passthrough. They + # cannot establish answers to declared environment inputs. + saved_environment = {} + return CheckoutState( + root=root, manifest=manifest, platform=platform, lock_path=lock_path, shared_lock=shared_lock, + home=home, home_path=config_root(), input_path=input_path, registered=record is not None, + checkout=checkout, saved_environment=saved_environment, + deferred=tuple(deferred_rows(input_path, root)), + ) def register_checkout(state: CheckoutState, *, write: bool = True) -> Path: @@ -222,6 +276,10 @@ def register_checkout(state: CheckoutState, *, write: bool = True) -> Path: Answer 14 of the work order: ``run`` registers a second checkout of the same project by itself, with a name derived from its path; each checkout keeps its own record and inherits nothing. + + With ``write=False`` this only names the record on the state. Finding a + free name looks at the project's other records, so this belongs with the + reading, before any decision. """ if state.registered: assert state.input_path is not None @@ -238,6 +296,7 @@ def register_checkout(state: CheckoutState, *, write: bool = True) -> Path: assert state.input_path is not None if write: atomic_write(state.input_path, render_toml(state.checkout)) + state.registered = True return state.input_path diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py new file mode 100644 index 00000000..7ee7a7f0 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -0,0 +1,229 @@ +"""Unit tests of ``devcapsule/commands/_launch_review.py``: what ``project run`` decides, from values. + +Every test builds its checkout in memory: a manifest written out here, the +lock the product derives from it, and the record ``project init`` would +leave. No test has a project directory or a home. The paths below are names +that the decisions print; nothing opens them. +""" + +from __future__ import annotations + +from copy import deepcopy +from pathlib import Path +import tomllib +from typing import Any + +import pytest + +from devcapsule.commands._launch_review import RunFlags, review_launch, stage_trust +from devcapsule.compat import DecisionPending +from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value +from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture +from devcapsule.configuration.capability_selection import generate_lock +from devcapsule.configuration.derivation import CheckoutState, Selection +from devcapsule.configuration.file_formats import ProjectConfigurationError, render_checkout +from devcapsule.configuration.listing import Decision +from devcapsule.configuration.operations import CheckoutRecord +from devcapsule.configuration.values import memory_size_bytes +from devcapsule.platforms import Platform +from devcapsule.resolution_matrix import MATRICES + +ROOT = Path("/projects/order") +HOME = Path("/homes/developer") +RECORD = HOME / "projects" / "order" / "devcapsule.checkout.toml" + +REQUIRING_PYCHARM = ("python", "python-ide", "codex-agent") +"""The work order's project: PyCharm required beside an unrelated mandatory tool.""" +REQUIRING_NO_IDE = ("python",) + + +def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide") -> CheckoutState: + """A registered checkout of a project that requires ``required``, in a home that has accepted nothing. + + It is what ``project init --require ... --ide IDE --authorize base-image + default`` leaves, built with the operations that command uses and no file: + the lock derived from the policy, the IDE pinned on the record, the base + image authorized for this checkout. + """ + manifest: dict[str, Any] = { + "devcapsule-schema-version": 2, + "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, + "capabilities": {"required": sorted(required)}, + } + state = CheckoutState( + root=ROOT, manifest=manifest, platform=Platform.LINUX_AMD64, + lock_path=ROOT / ".devcapsule" / "devcapsule.linux-amd64.lock", + shared_lock=generate_lock(CapabilityPolicy.read(manifest), MATRICES[Platform.LINUX_AMD64]), + home={}, home_path=HOME, input_path=RECORD, registered=True, + checkout=tomllib.loads(render_checkout(manifest, ROOT, {}, {})), + ) + selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) + selection.ide = ide + record = CheckoutRecord.staged(RECORD, state.with_selection(selection)) + base_image = authorization_declarations(manifest, state.composed_lock(record.document))["base-image"] + record.authorize(base_image, normalize_authorization_value(base_image, "default")) + state.checkout = record.export() + return state + + +def never_asked(*arguments: Any) -> None: + """An ``ask`` for a review that must not reach the developer.""" + pytest.fail("the review asked the developer") + + +def accepting(asked: list[Decision]) -> Any: + """An ``ask`` that accepts every channel put to it, as a developer answering yes, and lists what was asked.""" + def ask(state: CheckoutState, record: CheckoutRecord, checkout: dict[str, Any], decision: Decision, + host_overrides: dict[str, Any], environment: dict[str, str | None], accepted: list[str], flags: RunFlags) -> None: + asked.append(decision) + assert decision.kind == "trust", decision + stage_trust(state, checkout, decision.name, accepted) + return ask + + +def test_the_saved_required_ide_is_planned_without_a_question() -> None: + """With PyCharm required and saved and the base authorized, the review derives a PyCharm plan with no departure.""" + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(), ask=None) + + assert review.selected.resolution["runtime"]["component"] == "pycharm" + assert review.selected.departures == () + assert "departures" not in review.selected.resolution + assert "codex" in review.selected.lock["components"] + + +@pytest.mark.parametrize("named", ["pycharm", "python-ide", " python-ide "]) +def test_the_required_ide_can_be_named_by_component_or_capability(named: str) -> None: + """``--ide`` given the required IDE's component or its capability, spaces aside, selects it with no departure.""" + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide=named), ask=None) + + assert review.selected.resolution["runtime"]["component"] == "pycharm" + assert review.selected.departures == () + + +def test_another_ide_than_the_required_one_is_refused_naming_the_override() -> None: + """``--ide codium`` against a required PyCharm is refused with both IDEs and the ``--force`` command named, + and leaves the state's documents and departures as they were.""" + state = checkout_of(REQUIRING_PYCHARM) + before = deepcopy((state.checkout, state.home)) + + with pytest.raises(ProjectConfigurationError) as refused: + review_launch(state, RunFlags(ide="codium"), ask=None) + + message = str(refused.value) + assert "The project requires python-ide (pycharm); frontend-ide (codium) is another IDE" in message + assert f"devcapsule project --path {ROOT} run --ide codium --force" in message + assert "saved IDE stay as they are" in message + assert (state.checkout, state.home) == before + assert state.departures == () + + +def test_the_ide_request_is_judged_before_any_other_flag() -> None: + """With another IDE than the required one and an authorization that cannot be answered for one run, both on + the command line, the refusal is the IDE's: the request is judged before any approval is reviewed.""" + flags = RunFlags(ide="codium", authorize=(("no-such-access", "allow"),)) + + with pytest.raises(ProjectConfigurationError, match="frontend-ide \\(codium\\) is another IDE"): + review_launch(checkout_of(REQUIRING_PYCHARM), flags, ask=None) + + +def test_an_unknown_ide_is_refused_with_the_platforms_ides() -> None: + """``--ide`` given a name no IDE has is refused, and the refusal lists the IDE capabilities to choose from.""" + with pytest.raises(ProjectConfigurationError, match="Unknown IDE 'emacs'; choose one of .*python-ide"): + review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="emacs"), ask=None) + + +def test_a_forced_ide_still_waits_for_its_vendors_channel() -> None: + """``--ide vscode --force`` without a terminal ends pending on Microsoft's channel: ``--force`` sets the IDE + requirement aside and accepts nothing. The home's trust and the checkout's record are as they were.""" + state = checkout_of(REQUIRING_PYCHARM) + before = deepcopy((state.checkout, state.home)) + + with pytest.raises(DecisionPending) as pending: + review_launch(state, RunFlags(ide="vscode", force=True), ask=None) + + message = str(pending.value) + assert "trust vscode" in message and "--trust vscode" in message + assert f"launched from this DevCapsule home, `{HOME}`" in message + assert "Nothing was written" in message + assert (state.checkout, state.home) == before + + +def test_a_forced_ide_is_planned_once_its_channel_is_accepted() -> None: + """When the developer accepts the one channel asked, the forced launch plans Visual Studio Code with the IDE + requirement recorded as this launch's departure. The acceptance is staged for the home, and the record + staged for writing still has PyCharm saved.""" + asked: list[Decision] = [] + + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True), ask=accepting(asked)) + + assert [(decision.kind, decision.name) for decision in asked] == [("trust", "vscode")] + assert review.selected.resolution["runtime"]["component"] == "vscode" + assert review.selected.departures == (RequirementDeparture(IDE_REQUIREMENT, "python-ide", "vscode-ide"),) + assert review.accepted == ["vscode"] + assert "vscode" in review.state.home["trust"]["channels"] + assert LocalCapabilities.read(review.record.document).selected == ("python-ide",) + assert review.record.document == review.original + + +def test_the_channel_can_be_accepted_on_the_command_line() -> None: + """``--trust vscode`` beside the forced IDE settles the channel without a terminal.""" + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True, trust=("vscode",)), ask=None) + + assert review.selected.resolution["runtime"]["component"] == "vscode" + assert review.accepted == ["vscode"] + + +def test_print_only_never_asks() -> None: + """Under ``print_only`` a pending channel ends the review as pending although a terminal is there to ask.""" + with pytest.raises(DecisionPending, match="trust vscode"): + review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True), ask=never_asked, print_only=True) + + +@pytest.mark.parametrize(("flags", "refusal"), [ + (RunFlags(force=True), "--force names no departure"), + (RunFlags(ide="codium", force=True, save=True), "cannot be combined with --save"), +]) +def test_a_command_line_that_contradicts_itself_is_refused(flags: RunFlags, refusal: str) -> None: + """``--force`` without ``--ide``, and ``--force`` with ``--save``, are refused whatever the project requires.""" + with pytest.raises(ProjectConfigurationError, match=refusal): + review_launch(checkout_of(REQUIRING_PYCHARM), flags, ask=never_asked) + + +@pytest.mark.parametrize(("required", "ide", "refusal"), [ + (REQUIRING_PYCHARM, "pycharm", "--force has nothing to set aside: python-ide is the project's required IDE"), + (REQUIRING_NO_IDE, "codium", "--force has nothing to set aside: the project requires no IDE; '--ide codium' alone launches frontend-ide"), +]) +def test_force_with_no_requirement_to_set_aside_is_refused(required: tuple[str, ...], ide: str, refusal: str) -> None: + """``--force`` is refused when the named IDE is the required one, and when the project requires none.""" + with pytest.raises(ProjectConfigurationError, match=refusal): + review_launch(checkout_of(required), RunFlags(ide=ide, force=True), ask=never_asked) + + +def test_another_ide_needs_no_force_where_none_is_required() -> None: + """In a project that requires no IDE, ``--ide codium`` plans VSCodium for this launch and leaves PyCharm saved.""" + review = review_launch(checkout_of(REQUIRING_NO_IDE), RunFlags(ide="codium"), ask=None) + + assert review.selected.resolution["runtime"]["component"] == "codium" + assert review.selected.departures == () + assert LocalCapabilities.read(review.record.document).selected == ("python-ide",) + + +def test_run_once_resources_are_overrides_of_the_launch_and_not_of_the_record() -> None: + """``--memory`` and ``--cpus`` without ``--save`` come back as this launch's overrides; the record is unchanged.""" + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(memory="8g", cpus="2"), ask=None) + + assert (review.memory_override, review.cpus_override) == (8 * 1024 ** 3, 2) + assert review.saved is False + assert review.record.document == review.original + prepared = review.prepared() + assert (prepared.memory_override, prepared.cpus_override) == (8 * 1024 ** 3, 2) + assert prepared.selected is review.selected + + +def test_saved_resources_are_staged_on_the_record() -> None: + """With ``--save``, ``--memory`` is staged on the checkout's record as its value, and the review says it is saved.""" + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(memory="8g", save=True), ask=None) + + assert review.saved is True + assert review.record.document != review.original + assert memory_size_bytes(str(review.record.values["memory"])) == 8 * 1024 ** 3 From 9cdb6235d4c56f5553b36be652d853ed909dccec Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 12:11:13 +0000 Subject: [PATCH 18/75] Maintenance status: the launch's three phases, first slice Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 92 ++++++++++++++++++- 1 file changed, 90 insertions(+), 2 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index fca71942..de6eb8b6 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; a first slice of the owner's read-then-decide direction on `ws-maintenance/launch-phases`, with the launch's decisions testable from values and the six legacy files of the 17 still to retire Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@4e9a93c9f73a @@ -12,10 +12,98 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/host-inputs-at-source` from release-0.3.1 2f1109db, PR #26 open, the owner merges; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/launch-phases` from `ws-maintenance/host-inputs-at-source` c92d5254, stacked on PR #26; `ws-maintenance/host-inputs-at-source` from release-0.3.1 2f1109db, PR #26 open, the owner merges; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## A launch's preparation in three phases: read, decide in memory, write — 2026-11-12 + +Owner direction, 2026-11-12, on the 17 standing failures: the processing of +configuration reads its files and the command line into memory first, and +then decides; a test of a decision sets its precondition as data in memory +and skips the reading, which is tested apart. This section records the first +slice, on `ws-maintenance/launch-phases`, stacked on PR #26. + +**What the check of the direction found.** + +- The code was half-way there: `prepare_launch` loaded a `CheckoutState`, + reviewed in memory and wrote at the end. What kept a test from skipping + the reading was that the state's constructor did the reading, and that + the state's methods read again: the home's directory, the record's + existence and the console's requests, on every listing. +- There are three phases, not two. The writes are the third, and + "writes nothing" in a test's name is a statement about it. +- The product does not use Pydantic. It is in `requirements.txt` only as a + dependency of `python-on-whales`. The documents are dictionaries checked + by code of our own, so the reading does need its own tests. +- The 17 do not turn green by this refactoring alone. They are legacy tests + that call `prepare_launch` or the command line with a path, so they read + the mounted settings whatever the code below does. Each must be rewritten + on the decision phase, and rule 5 makes that the retirement of its whole + file: six files, 191 tests, 3172 lines. + +**The product code.** + +- `configuration/derivation.py`: `CheckoutState` is a dataclass of values, + with the home's directory, whether the record exists, and the console's + deferred requests among them. `load_state` does all the reading and is + the only reader. No caller changed. +- `commands/_launch_review.py`, new: `review_launch(state, flags, ask=...)` + is the decision phase. It returns a `LaunchReview`, or refuses, and writes + nothing. `ask` is how a decision reaches the developer; None when there is + no terminal. `RunFlags` and `Prepared` moved here and are still exported + by `_run_flow`. +- `commands/_run_flow.py`: `prepare_launch` is the three phases in order: + `read_launch_state`, `review_launch`, `save_launch`. The terminal dialogue + stays here and is passed to the review as `ask`. + +**The tests.** `tests/unit/devcapsule/commands/test_launch_review.py`, 18 +tests, none with a project directory, a home, `tmp_path` or a patch. Each +builds its checkout in memory with the operations `project init` uses: +`generate_lock` for the lock, `with_selection` and `authorize` for the +record. A state built that way was compared with the one `load_state` reads +from a project `init` wrote: manifest, lock and record are equal. The two +tests the owner named are among them, and they pass in the owner's capsule, +where their legacy forms are 2 of the 17. + +**Evidence.** The whole unit suite, 3008 tests before, passes as before +with the 17 standing failures; with the fallback to the mounted settings +switched off by a diagnostic plugin, it fails only the two tests of the +fallback itself, before and after. 22 faults planted in the changed code: 2 +caught by the new tests alone after two assertions were added, 15 by legacy +tests, 5 by nothing: + +- the refusal of contradictory flags before the reading, which the review + repeats; only the order of two refusals could show it; +- "no terminal" checked a second time in the loop, redundant before this + change too; +- the state brought up to date after the developer applies, and after they + discard, a console request during a review; the two lines are new, and + the console's storage reads the home from the environment, so no test can + reach them from values yet; +- the saved environment not loaded: the reading is unchanged, and no unit + test covers it. + +**What the decision phase still takes from the host**, named in the new +module's docstring: the listing asks `os.environ` whether a host variable is +set and the file system whether a bound directory exists; `derive_plan` +asks the Docker daemon for a local base image; accepting a channel reads the +clock; a run-once authorization is printed to standard error; the answer to +a console request runs a command that writes. + +**Differences in behaviour.** Two orders of refusal: a checkout that cannot +be given a free record name is now refused before a wrong IDE is, and the +console's requests are read once per review, so one that arrives during a +review is seen at the next run. + +**Not done.** The retirement of the six legacy files. `load_state` still +finds the home through the environment, so the reading has no test from +values yet. `_run_flow.py` has no mirror test, since its legacy twin +`tests/test_run_flow.py` stands. + +**Next action.** The owner's: the order in which the six files are retired, +and whether the 17 wait for that or get the one-line fixture change first. + ## Two rules held by machine: no network in a unit test, the command line only in `test_cli.py` — 2026-11-12 The owner asked why the capsule's 17 unit tests fail and when that began, From 6d9be28d46768703a09cebbee8c98335ab8b618e Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 12:11:40 +0000 Subject: [PATCH 19/75] Maintenance status: correct the count of faults the new tests catch Co-Authored-By: Claude --- .../wip/2026-09-18-maintenance/CURRENT-STATUS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index de6eb8b6..1f320427 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -69,9 +69,9 @@ where their legacy forms are 2 of the 17. **Evidence.** The whole unit suite, 3008 tests before, passes as before with the 17 standing failures; with the fallback to the mounted settings switched off by a diagnostic plugin, it fails only the two tests of the -fallback itself, before and after. 22 faults planted in the changed code: 2 -caught by the new tests alone after two assertions were added, 15 by legacy -tests, 5 by nothing: +fallback itself, before and after. 22 faults planted in the changed code: 3 +caught by the new tests, two of them after an assertion was added for each, +14 by legacy tests, 5 by nothing: - the refusal of contradictory flags before the reading, which the review repeats; only the order of two refusals could show it; From 74354f52357413651b694ddb7e9afae2b48c7ce1 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 12:38:06 +0000 Subject: [PATCH 20/75] Launch review: the daemon, the clock and the announcement reach the decisions as functions The owner asked why the decision phase still read the host in five places. Three are closed here, the ones no legacy test calls: - derivation.py: Host, two functions bound by load_state. derive_plan asks it for a local base image; the lookup still goes through the operations adapter when called, so the legacy tests that patch it are unaffected. - _launch_review.py: stage_trust stamps an acceptance with the host's time; a run-once authorization goes to announce, a function the review is given. - _run_flow.py: prepare_launch passes standard error as announce. The fourth, the dialogue, was already the function ask. The fifth is left: the listing and the configuration review ask the environment and the file system, in assess_checkout and Configuration, which five legacy files call. Evidence: 20 mirror tests, three of them new, with no directory, no home and no patch; five planted faults, four caught, the fifth the one line that binds the real clock. The unit suite passes as before, 3028 passed with the capsule's 17 standing failures. Co-Authored-By: Claude --- .../devcapsule/commands/_launch_review.py | 28 +++--- .../devcapsule/commands/_run_flow.py | 1 + .../devcapsule/configuration/derivation.py | 42 +++++++-- .../devcapsule/commands/test_launch_review.py | 90 +++++++++++++++---- 4 files changed, 122 insertions(+), 39 deletions(-) diff --git a/devcapsule-src/devcapsule/commands/_launch_review.py b/devcapsule-src/devcapsule/commands/_launch_review.py index 6643f558..439fc978 100644 --- a/devcapsule-src/devcapsule/commands/_launch_review.py +++ b/devcapsule-src/devcapsule/commands/_launch_review.py @@ -15,17 +15,20 @@ :func:`review_launch`, and reads the result. It needs no project directory and no home. -What this phase still takes from the host, each to be passed in as a value in -a later change: +What a decision needs of the machine reaches it as a value or as a function +it is given: the state's :class:`~devcapsule.configuration.derivation.Host` +looks up a local base image and tells the time, ``ask`` puts a decision to +the developer, and ``announce`` shows a line at once. + +Two reads of the machine are still made below this phase, by code it calls: - the listing asks ``os.environ`` whether a host variable is set, and the file system whether a bound directory exists; -- :func:`~devcapsule.configuration.derivation.derive_plan` asks the Docker - daemon for a local base image when the checkout selects one; -- accepting a channel stamps the acceptance with the clock; -- a run-once authorization is announced on standard error; -- the function given as ``ask`` talks to the developer, and its answer to a - console request runs a command that writes. +- the configuration review resolves a bound directory's path and asks the + file system whether it exists. + +Both are in functions that legacy tests call, ``assess_checkout`` and +``Configuration``. They become values when those tests are retired. """ from __future__ import annotations @@ -34,7 +37,6 @@ from dataclasses import dataclass, field from pathlib import Path import shlex -import sys from typing import Any, Callable, Mapping from devcapsule.compat import DecisionPending @@ -157,13 +159,15 @@ def review_launch( flags: RunFlags, *, ask: Ask | None, + announce: Callable[[str], None], print_only: bool = False, check_display: bool = True, ) -> LaunchReview: """Phase 2 of a launch's preparation: decide, in memory, from the state and the flags. ``ask`` is how a decision reaches the developer; None when there is no - terminal. Without it, and always under ``print_only``, an unanswered + terminal. ``announce`` shows the developer one line at once, before any + question. Without ``ask``, and always under ``print_only``, an unanswered decision the launch cannot go on without raises :class:`DecisionPending` that names each one. An invalid request raises :class:`ProjectConfigurationError`. Either way nothing has been written, @@ -213,7 +217,7 @@ def review_launch( record.authorize(declaration, normalized) else: host_overrides[node] = normalized - print(f"Run-once authorization: {node} = {value}", file=sys.stderr) + announce(f"Run-once authorization: {node} = {value}") def launch_checkout() -> dict[str, Any]: """The checkout document this launch runs on: the staged record with the run-once choices laid over it.""" @@ -358,7 +362,7 @@ def channel_for(lock: Mapping[str, Any], channel_id: str) -> Channel: def stage_trust(state: CheckoutState, checkout: Mapping[str, Any], channel_id: str, accepted: list[str]) -> None: """Stage the acceptance of ``channel_id`` on the state's home document; written with the answers.""" channel = channel_for(state.composed_lock(checkout), channel_id) - trust = HomeTrust.read(state.home).with_channel(channel) + trust = HomeTrust.read(state.home).with_channel(channel, accepted_at=state.host.now()) state.home = {**state.home, "trust": trust.document()} if channel_id not in accepted: accepted.append(channel_id) diff --git a/devcapsule-src/devcapsule/commands/_run_flow.py b/devcapsule-src/devcapsule/commands/_run_flow.py index 2e895f92..f98f2ba5 100644 --- a/devcapsule-src/devcapsule/commands/_run_flow.py +++ b/devcapsule-src/devcapsule/commands/_run_flow.py @@ -80,6 +80,7 @@ def ask_at_terminal( _settle(state, record, checkout, decision, host_overrides, environment, accepted, flags, reader, output) review = review_launch(state, flags, ask=ask_at_terminal if interactive else None, + announce=lambda line: print(line, file=sys.stderr), print_only=print_only, check_display=check_display) # Phase 3, write: what the review staged. diff --git a/devcapsule-src/devcapsule/configuration/derivation.py b/devcapsule-src/devcapsule/configuration/derivation.py index 006282af..8c2f56a9 100644 --- a/devcapsule-src/devcapsule/configuration/derivation.py +++ b/devcapsule-src/devcapsule/configuration/derivation.py @@ -26,14 +26,15 @@ from copy import deepcopy from dataclasses import dataclass, field +from datetime import datetime, timezone from functools import cached_property from pathlib import Path import tomllib import shlex -from typing import Any, Mapping +from typing import Any, Callable, Mapping from devcapsule.compat import DecisionPending -from devcapsule.materialization import validate_base_image +from devcapsule.materialization import ImageDetails, validate_base_image from devcapsule.platforms import Platform from devcapsule.project import sanitize_name from devcapsule.resolution_matrix import MATRICES, ResolutionMatrix, known_base_image @@ -64,7 +65,23 @@ from .file_formats import selected_version_lock from .docker_arguments import arguments_path, read_arguments, read_environment -__all__ = ["CheckoutState", "Selection", "derive_plan", "load_state", "register_checkout"] +__all__ = ["CheckoutState", "Host", "Selection", "derive_plan", "load_state", "register_checkout"] + + +@dataclass(frozen=True) +class Host: + """What a decision may ask of the machine it runs on, given to it as functions. + + A decision cannot know these in advance: which image it must look up + follows from what the developer selects, and the moment of an acceptance + is the moment it is given. So the reading phase binds the functions and + the decision calls them. A test passes its own. + """ + + local_image: Callable[[str], ImageDetails] + """The Docker daemon's details of the local image with this reference; it refuses when there is none.""" + now: Callable[[], datetime] + """The current time, with its time zone.""" class Selection: @@ -133,6 +150,7 @@ class CheckoutState: """The home's settings document.""" home_path: Path """The home's directory, which the listing names in what it tells the developer.""" + host: Host input_path: Path | None """The checkout's record: the one found, or the default one it would get. @@ -232,6 +250,17 @@ def with_selection(self, selection: Selection, *, allow_unverified: bool = False return document +def _this_host() -> Host: + """The machine this process runs on.""" + def local_image(reference: str) -> ImageDetails: + # Looked up through the operations adapter when called, not when bound: + # it is the one seam that legacy tests of the launch patch for the local daemon. + from . import operations + return operations.required_local_image(reference) + + return Host(local_image=local_image, now=lambda: datetime.now(timezone.utc)) + + def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: """Read one checkout's documents and surroundings into memory. Nothing is written. @@ -264,7 +293,7 @@ def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: saved_environment = {} return CheckoutState( root=root, manifest=manifest, platform=platform, lock_path=lock_path, shared_lock=shared_lock, - home=home, home_path=config_root(), input_path=input_path, registered=record is not None, + home=home, home_path=config_root(), host=_this_host(), input_path=input_path, registered=record is not None, checkout=checkout, saved_environment=saved_environment, deferred=tuple(deferred_rows(input_path, root)), ) @@ -330,10 +359,7 @@ def derive_plan(state: CheckoutState, checkout: Mapping[str, Any] | None = None, trust = HomeTrust.read(state.home) base_selection = authorized_base_selection(lock, document, trust=trust) if "base" in lock else None if base_selection is not None and base_selection.local_image_identity is not None: - # Looked up through the operations adapter, the one seam the launch - # and its tests patch for the local daemon. - from . import operations - local_base = operations.required_local_image(base_selection.reference) + local_base = state.host.local_image(base_selection.reference) validate_base_image(local_base, platform=str(lock["platform"]), expected_identity=base_selection.local_image_identity) assert state.input_path is not None resolution_path = resolved_record_path(state.input_path) diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index 7ee7a7f0..01e4e29d 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -9,6 +9,7 @@ from __future__ import annotations from copy import deepcopy +from datetime import datetime, timezone from pathlib import Path import tomllib from typing import Any @@ -20,7 +21,7 @@ from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture from devcapsule.configuration.capability_selection import generate_lock -from devcapsule.configuration.derivation import CheckoutState, Selection +from devcapsule.configuration.derivation import CheckoutState, Host, Selection from devcapsule.configuration.file_formats import ProjectConfigurationError, render_checkout from devcapsule.configuration.listing import Decision from devcapsule.configuration.operations import CheckoutRecord @@ -32,14 +33,25 @@ HOME = Path("/homes/developer") RECORD = HOME / "projects" / "order" / "devcapsule.checkout.toml" +ACCEPTED_AT = datetime(2026, 1, 2, 3, 4, 5, tzinfo=timezone.utc) +"""The time the test's host tells.""" + REQUIRING_PYCHARM = ("python", "python-ide", "codex-agent") """The work order's project: PyCharm required beside an unrelated mandatory tool.""" REQUIRING_NO_IDE = ("python",) -def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide") -> CheckoutState: +def no_local_image(reference: str) -> Any: + """The daemon of a host that must not be asked for an image.""" + pytest.fail(f"the review asked the Docker daemon for {reference}") + + +def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Host | None = None) -> CheckoutState: """A registered checkout of a project that requires ``required``, in a home that has accepted nothing. + Its host tells the time ``ACCEPTED_AT`` and fails the test when asked for + a local image, unless ``host`` is given. + It is what ``project init --require ... --ide IDE --authorize base-image default`` leaves, built with the operations that command uses and no file: the lock derived from the policy, the IDE pinned on the record, the base @@ -55,6 +67,7 @@ def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide") -> Checko lock_path=ROOT / ".devcapsule" / "devcapsule.linux-amd64.lock", shared_lock=generate_lock(CapabilityPolicy.read(manifest), MATRICES[Platform.LINUX_AMD64]), home={}, home_path=HOME, input_path=RECORD, registered=True, + host=host or Host(local_image=no_local_image, now=lambda: ACCEPTED_AT), checkout=tomllib.loads(render_checkout(manifest, ROOT, {}, {})), ) selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) @@ -71,6 +84,11 @@ def never_asked(*arguments: Any) -> None: pytest.fail("the review asked the developer") +def never_announced(line: str) -> None: + """An ``announce`` for a review that has nothing to tell the developer.""" + pytest.fail(f"the review announced {line!r}") + + def accepting(asked: list[Decision]) -> Any: """An ``ask`` that accepts every channel put to it, as a developer answering yes, and lists what was asked.""" def ask(state: CheckoutState, record: CheckoutRecord, checkout: dict[str, Any], decision: Decision, @@ -83,7 +101,7 @@ def ask(state: CheckoutState, record: CheckoutRecord, checkout: dict[str, Any], def test_the_saved_required_ide_is_planned_without_a_question() -> None: """With PyCharm required and saved and the base authorized, the review derives a PyCharm plan with no departure.""" - review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(), ask=None) + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(), ask=None, announce=never_announced) assert review.selected.resolution["runtime"]["component"] == "pycharm" assert review.selected.departures == () @@ -94,7 +112,7 @@ def test_the_saved_required_ide_is_planned_without_a_question() -> None: @pytest.mark.parametrize("named", ["pycharm", "python-ide", " python-ide "]) def test_the_required_ide_can_be_named_by_component_or_capability(named: str) -> None: """``--ide`` given the required IDE's component or its capability, spaces aside, selects it with no departure.""" - review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide=named), ask=None) + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide=named), ask=None, announce=never_announced) assert review.selected.resolution["runtime"]["component"] == "pycharm" assert review.selected.departures == () @@ -107,7 +125,7 @@ def test_another_ide_than_the_required_one_is_refused_naming_the_override() -> N before = deepcopy((state.checkout, state.home)) with pytest.raises(ProjectConfigurationError) as refused: - review_launch(state, RunFlags(ide="codium"), ask=None) + review_launch(state, RunFlags(ide="codium"), ask=None, announce=never_announced) message = str(refused.value) assert "The project requires python-ide (pycharm); frontend-ide (codium) is another IDE" in message @@ -123,13 +141,13 @@ def test_the_ide_request_is_judged_before_any_other_flag() -> None: flags = RunFlags(ide="codium", authorize=(("no-such-access", "allow"),)) with pytest.raises(ProjectConfigurationError, match="frontend-ide \\(codium\\) is another IDE"): - review_launch(checkout_of(REQUIRING_PYCHARM), flags, ask=None) + review_launch(checkout_of(REQUIRING_PYCHARM), flags, ask=None, announce=never_announced) def test_an_unknown_ide_is_refused_with_the_platforms_ides() -> None: """``--ide`` given a name no IDE has is refused, and the refusal lists the IDE capabilities to choose from.""" with pytest.raises(ProjectConfigurationError, match="Unknown IDE 'emacs'; choose one of .*python-ide"): - review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="emacs"), ask=None) + review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="emacs"), ask=None, announce=never_announced) def test_a_forced_ide_still_waits_for_its_vendors_channel() -> None: @@ -139,7 +157,7 @@ def test_a_forced_ide_still_waits_for_its_vendors_channel() -> None: before = deepcopy((state.checkout, state.home)) with pytest.raises(DecisionPending) as pending: - review_launch(state, RunFlags(ide="vscode", force=True), ask=None) + review_launch(state, RunFlags(ide="vscode", force=True), ask=None, announce=never_announced) message = str(pending.value) assert "trust vscode" in message and "--trust vscode" in message @@ -150,24 +168,24 @@ def test_a_forced_ide_still_waits_for_its_vendors_channel() -> None: def test_a_forced_ide_is_planned_once_its_channel_is_accepted() -> None: """When the developer accepts the one channel asked, the forced launch plans Visual Studio Code with the IDE - requirement recorded as this launch's departure. The acceptance is staged for the home, and the record - staged for writing still has PyCharm saved.""" + requirement recorded as this launch's departure. The acceptance is staged for the home with the time the + host tells, and the record staged for writing still has PyCharm saved.""" asked: list[Decision] = [] - review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True), ask=accepting(asked)) + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True), ask=accepting(asked), announce=never_announced) assert [(decision.kind, decision.name) for decision in asked] == [("trust", "vscode")] assert review.selected.resolution["runtime"]["component"] == "vscode" assert review.selected.departures == (RequirementDeparture(IDE_REQUIREMENT, "python-ide", "vscode-ide"),) assert review.accepted == ["vscode"] - assert "vscode" in review.state.home["trust"]["channels"] + assert review.state.home["trust"]["channels"]["vscode"]["accepted"] == "2026-01-02T03:04:05+00:00" assert LocalCapabilities.read(review.record.document).selected == ("python-ide",) assert review.record.document == review.original def test_the_channel_can_be_accepted_on_the_command_line() -> None: """``--trust vscode`` beside the forced IDE settles the channel without a terminal.""" - review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True, trust=("vscode",)), ask=None) + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True, trust=("vscode",)), ask=None, announce=never_announced) assert review.selected.resolution["runtime"]["component"] == "vscode" assert review.accepted == ["vscode"] @@ -176,7 +194,7 @@ def test_the_channel_can_be_accepted_on_the_command_line() -> None: def test_print_only_never_asks() -> None: """Under ``print_only`` a pending channel ends the review as pending although a terminal is there to ask.""" with pytest.raises(DecisionPending, match="trust vscode"): - review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True), ask=never_asked, print_only=True) + review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide="vscode", force=True), ask=never_asked, announce=never_announced, print_only=True) @pytest.mark.parametrize(("flags", "refusal"), [ @@ -186,7 +204,7 @@ def test_print_only_never_asks() -> None: def test_a_command_line_that_contradicts_itself_is_refused(flags: RunFlags, refusal: str) -> None: """``--force`` without ``--ide``, and ``--force`` with ``--save``, are refused whatever the project requires.""" with pytest.raises(ProjectConfigurationError, match=refusal): - review_launch(checkout_of(REQUIRING_PYCHARM), flags, ask=never_asked) + review_launch(checkout_of(REQUIRING_PYCHARM), flags, ask=never_asked, announce=never_announced) @pytest.mark.parametrize(("required", "ide", "refusal"), [ @@ -196,12 +214,12 @@ def test_a_command_line_that_contradicts_itself_is_refused(flags: RunFlags, refu def test_force_with_no_requirement_to_set_aside_is_refused(required: tuple[str, ...], ide: str, refusal: str) -> None: """``--force`` is refused when the named IDE is the required one, and when the project requires none.""" with pytest.raises(ProjectConfigurationError, match=refusal): - review_launch(checkout_of(required), RunFlags(ide=ide, force=True), ask=never_asked) + review_launch(checkout_of(required), RunFlags(ide=ide, force=True), ask=never_asked, announce=never_announced) def test_another_ide_needs_no_force_where_none_is_required() -> None: """In a project that requires no IDE, ``--ide codium`` plans VSCodium for this launch and leaves PyCharm saved.""" - review = review_launch(checkout_of(REQUIRING_NO_IDE), RunFlags(ide="codium"), ask=None) + review = review_launch(checkout_of(REQUIRING_NO_IDE), RunFlags(ide="codium"), ask=None, announce=never_announced) assert review.selected.resolution["runtime"]["component"] == "codium" assert review.selected.departures == () @@ -210,7 +228,7 @@ def test_another_ide_needs_no_force_where_none_is_required() -> None: def test_run_once_resources_are_overrides_of_the_launch_and_not_of_the_record() -> None: """``--memory`` and ``--cpus`` without ``--save`` come back as this launch's overrides; the record is unchanged.""" - review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(memory="8g", cpus="2"), ask=None) + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(memory="8g", cpus="2"), ask=None, announce=never_announced) assert (review.memory_override, review.cpus_override) == (8 * 1024 ** 3, 2) assert review.saved is False @@ -222,8 +240,42 @@ def test_run_once_resources_are_overrides_of_the_launch_and_not_of_the_record() def test_saved_resources_are_staged_on_the_record() -> None: """With ``--save``, ``--memory`` is staged on the checkout's record as its value, and the review says it is saved.""" - review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(memory="8g", save=True), ask=None) + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(memory="8g", save=True), ask=None, announce=never_announced) assert review.saved is True assert review.record.document != review.original assert memory_size_bytes(str(review.record.values["memory"])) == 8 * 1024 ** 3 + + +def test_a_run_once_authorization_is_announced_and_overrides_this_launch_only() -> None: + """``--authorize network host`` without ``--save`` is announced at once, comes back as this launch's host + override, and is not staged on the record.""" + announced: list[str] = [] + + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(authorize=(("network", "host"),)), + ask=None, announce=announced.append) + + assert announced == ["Run-once authorization: network = host"] + assert review.host_overrides == {"network": "host"} + assert review.record.document == review.original + + +def test_a_local_base_image_is_looked_up_on_the_host_by_its_reference() -> None: + """A checkout whose base authorization names a local image has that reference looked up through the host; + when the host has no such image, the review ends with the host's refusal.""" + asked: list[str] = [] + + def no_such_image(reference: str) -> Any: + asked.append(reference) + raise ProjectConfigurationError(f"no local image {reference}") + + state = checkout_of(REQUIRING_PYCHARM, host=Host(local_image=no_such_image, now=lambda: ACCEPTED_AT)) + record = CheckoutRecord.staged(RECORD, state.checkout) + base_image = authorization_declarations(state.manifest, state.composed_lock())["base-image"] + record.authorize(base_image, "local/devcapsule-base:work", image_identity="sha256:" + "a" * 64) + state.checkout = record.export() + + with pytest.raises(ProjectConfigurationError, match="no local image local/devcapsule-base:work"): + review_launch(state, RunFlags(), ask=None, announce=never_announced) + + assert asked == ["local/devcapsule-base:work"] From 7849233651e88672719756aee8420c785ee602b1 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 12:38:06 +0000 Subject: [PATCH 21/75] Maintenance status: three of the decision phase's host reads closed, and what the last waits for Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 42 +++++++++++++------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 1f320427..9ff49515 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -57,7 +57,7 @@ slice, on `ws-maintenance/launch-phases`, stacked on PR #26. `read_launch_state`, `review_launch`, `save_launch`. The terminal dialogue stays here and is passed to the review as `ask`. -**The tests.** `tests/unit/devcapsule/commands/test_launch_review.py`, 18 +**The tests.** `tests/unit/devcapsule/commands/test_launch_review.py`, 20 tests, none with a project directory, a home, `tmp_path` or a patch. Each builds its checkout in memory with the operations `project init` uses: `generate_lock` for the lock, `with_selection` and `authorize` for the @@ -69,9 +69,8 @@ where their legacy forms are 2 of the 17. **Evidence.** The whole unit suite, 3008 tests before, passes as before with the 17 standing failures; with the fallback to the mounted settings switched off by a diagnostic plugin, it fails only the two tests of the -fallback itself, before and after. 22 faults planted in the changed code: 3 -caught by the new tests, two of them after an assertion was added for each, -14 by legacy tests, 5 by nothing: +fallback itself, before and after. 27 faults planted in the changed code: 6 +caught by the new tests, 15 by legacy tests, 6 by nothing: - the refusal of contradictory flags before the reading, which the review repeats; only the order of two refusals could show it; @@ -82,14 +81,33 @@ caught by the new tests, two of them after an assertion was added for each, the console's storage reads the home from the environment, so no test can reach them from values yet; - the saved environment not loaded: the reading is unchanged, and no unit - test covers it. - -**What the decision phase still takes from the host**, named in the new -module's docstring: the listing asks `os.environ` whether a host variable is -set and the file system whether a bound directory exists; `derive_plan` -asks the Docker daemon for a local base image; accepting a channel reads the -clock; a run-once authorization is printed to standard error; the answer to -a console request runs a command that writes. + test covers it; +- the clock that `load_state` binds, one line that names the real one. + +**What the decision phase asked of the host, and what it asks now.** The +first commit of the slice left five. The owner asked why. Three had no +caller among the legacy tests and are closed in the second commit: the state +carries a `Host` of two functions, bound by `load_state`; `derive_plan` asks +it for a local base image and `stage_trust` asks it for the time; a run-once +authorization goes to a function the review is given, `announce`. A fourth, +the dialogue with the developer, is `ask`, a function the review is given +too. One is left, in two places below the review: + +- the listing asks `os.environ` whether a host variable is set, and the file + system whether a bound directory exists, in `assess_checkout`; +- the configuration review resolves a bound directory's path and asks + whether it exists, in `Configuration`. + +Making these values means a new required argument on `assess_checkout` and +on `Configuration`. Five legacy files call them: `tests/test_listing.py` +three times, and `tests/configuration/test_adt.py`, +`tests/test_ide_requirement_override.py`, `tests/test_capability_policy.py` +and `tests/test_trust.py` sixteen times between them. Rule 5 of *Unit Tests* +makes an edited call in a legacy test the retirement of its file, and rule 2 +of *Host Inputs* forbids the other way, an optional argument whose default +reads the host. So this last read waits for one of three rulings: the five +files are retired first; rule 5 lets a call site in a legacy test follow a +signature; or the argument is optional until they are retired. **Differences in behaviour.** Two orders of refusal: a checkout that cannot be given a free record name is now refused before a wrong IDE is, and the From 5673ef0010bf3d6f34ccfbe70c7141294931c4f5 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:06:58 +0000 Subject: [PATCH 22/75] Launch review: the shell's environment and the bound directories reach the decisions through the Host Owner ruling of 2026-11-12, option 3: the argument is optional until the legacy tests that call these functions are retired. - configuration/bindings.py: HostDirectory, what the host says of a named directory, and host_directory, which asks this machine. - assess_checkout takes host_environment and directory; Configuration, review_configuration and resolve_configuration_bindings take directory. Left out, this process's environment and this machine's file system are asked, as before; five legacy files rely on that. - derivation.py: the Host carries both; the state's listing and derive_plan pass them. Nothing in the decision phase reads the machine any more. Evidence: four new mirror tests with a constructed host, 24 in all. The unit suite with the mounted-settings fallback switched off fails only the fallback's own two tests, as before: 3047 passed. Co-Authored-By: Claude --- .../devcapsule/commands/_launch_review.py | 20 ++--- .../devcapsule/configuration/bindings.py | 40 ++++++++-- .../devcapsule/configuration/derivation.py | 13 ++- .../devcapsule/configuration/listing.py | 34 +++++--- .../devcapsule/configuration/model.py | 9 ++- .../devcapsule/configuration/review.py | 14 +++- .../devcapsule/commands/test_launch_review.py | 80 +++++++++++++++++-- 7 files changed, 167 insertions(+), 43 deletions(-) diff --git a/devcapsule-src/devcapsule/commands/_launch_review.py b/devcapsule-src/devcapsule/commands/_launch_review.py index 439fc978..43c31750 100644 --- a/devcapsule-src/devcapsule/commands/_launch_review.py +++ b/devcapsule-src/devcapsule/commands/_launch_review.py @@ -15,20 +15,12 @@ :func:`review_launch`, and reads the result. It needs no project directory and no home. -What a decision needs of the machine reaches it as a value or as a function -it is given: the state's :class:`~devcapsule.configuration.derivation.Host` -looks up a local base image and tells the time, ``ask`` puts a decision to -the developer, and ``announce`` shows a line at once. - -Two reads of the machine are still made below this phase, by code it calls: - -- the listing asks ``os.environ`` whether a host variable is set, and the - file system whether a bound directory exists; -- the configuration review resolves a bound directory's path and asks the - file system whether it exists. - -Both are in functions that legacy tests call, ``assess_checkout`` and -``Configuration``. They become values when those tests are retired. +Nothing in this phase reads the machine it runs on. What a decision needs of +it is a value or a function the phase is given: the state's +:class:`~devcapsule.configuration.derivation.Host` carries the shell's +environment, looks up a bound directory and a local base image, and tells +the time; ``ask`` puts a decision to the developer; ``announce`` shows a +line at once. """ from __future__ import annotations diff --git a/devcapsule-src/devcapsule/configuration/bindings.py b/devcapsule-src/devcapsule/configuration/bindings.py index 315a6703..91f49c24 100644 --- a/devcapsule-src/devcapsule/configuration/bindings.py +++ b/devcapsule-src/devcapsule/configuration/bindings.py @@ -3,7 +3,7 @@ from __future__ import annotations from dataclasses import dataclass from pathlib import Path -from typing import Any, Mapping +from typing import Any, Callable, Mapping from devcapsule.components.catalog import ComponentCatalogError, selected_component_definitions, selected_runtime_templates from .file_formats import ProjectConfigurationError @@ -144,9 +144,37 @@ def resolve_secret_bindings( return resolved +@dataclass(frozen=True) +class HostDirectory: + """What the host says of a directory a developer named.""" + + expanded: Path + """The name with ``~`` expanded, as the developer would read it back.""" + resolved: Path + """The absolute path, links followed, as a mount takes it.""" + exists: bool + """Whether it is a directory.""" + + +DirectoryLookup = Callable[[str], HostDirectory] +"""Ask the host about a directory, by the name the developer gave.""" + + +def host_directory(name: str) -> HostDirectory: + """Ask this machine about a directory. The one place the configuration package touches the file system for it.""" + expanded = Path(name).expanduser() + return HostDirectory(expanded, expanded.resolve(), expanded.is_dir()) + + def resolve_configuration_bindings( - lock: Mapping[str, Any], checkout: Mapping[str, Any] + lock: Mapping[str, Any], checkout: Mapping[str, Any], directory: DirectoryLookup | None = None, ) -> dict[str, str]: + """Each declared binding the checkout sets, with the resolved path of its existing host directory. + + ``directory`` tells what the host says of a named directory. Owner ruling + of 2026-11-12, until the legacy tests that reach this are retired: when + it is left out, this machine is asked. + """ declarations = configuration_binding_declarations(lock) configuration = checkout.get("configuration", {}) if not isinstance(configuration, dict): @@ -169,11 +197,11 @@ def resolve_configuration_bindings( elif not isinstance(raw_source, str) or not raw_source or "\x00" in raw_source: problems.append(f"Host-directory binding {name!r} must contain a filesystem path string.") else: - source = Path(raw_source).expanduser().resolve() - if not source.is_dir(): - problems.append(f"Host-directory binding {name!r} is not an existing directory: {source}") + found = (directory or host_directory)(raw_source) + if not found.exists: + problems.append(f"Host-directory binding {name!r} is not an existing directory: {found.resolved}") else: - resolved[name] = str(source) + resolved[name] = str(found.resolved) if problems: raise ProjectConfigurationError("\n".join(problems)) return resolved diff --git a/devcapsule-src/devcapsule/configuration/derivation.py b/devcapsule-src/devcapsule/configuration/derivation.py index 8c2f56a9..7a121a2e 100644 --- a/devcapsule-src/devcapsule/configuration/derivation.py +++ b/devcapsule-src/devcapsule/configuration/derivation.py @@ -28,6 +28,7 @@ from dataclasses import dataclass, field from datetime import datetime, timezone from functools import cached_property +import os from pathlib import Path import tomllib import shlex @@ -40,6 +41,7 @@ from devcapsule.resolution_matrix import MATRICES, ResolutionMatrix, known_base_image from .authorization import authorized_base_selection +from .bindings import DirectoryLookup, host_directory from .capabilities import CapabilityPolicy, LocalCapabilities, RequirementDeparture, resolution_recommendations from .capability_commands import pin_selection, release_deselected from .capability_selection import compose_lock, effective_lock, local_pins, inspection_capabilities, inspection_providers, known_policy_names @@ -82,6 +84,10 @@ class Host: """The Docker daemon's details of the local image with this reference; it refuses when there is none.""" now: Callable[[], datetime] """The current time, with its time zone.""" + environment: Mapping[str, str] + """The environment of the developer's shell. A decision asks whether a variable is set, never for its value.""" + directory: DirectoryLookup + """What the host says of a directory the developer named: its path and whether it exists.""" class Selection: @@ -222,6 +228,7 @@ def listing(self, checkout: Mapping[str, Any] | None = None, *, check_display: b capability_providers=providers, base_display=base.contract.display if check_display and base is not None else None, departures=self.departures, + host_environment=self.host.environment, directory=self.host.directory, ) return Listing(listing.rows + self.deferred, listing.notes, listing.departures) @@ -258,7 +265,8 @@ def local_image(reference: str) -> ImageDetails: from . import operations return operations.required_local_image(reference) - return Host(local_image=local_image, now=lambda: datetime.now(timezone.utc)) + return Host(local_image=local_image, now=lambda: datetime.now(timezone.utc), + environment=dict(os.environ), directory=host_directory) def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: @@ -353,7 +361,8 @@ def derive_plan(state: CheckoutState, checkout: Mapping[str, Any] | None = None, ) from exc if not lock.get("components", {}).get("interactive-surface"): raise ProjectConfigurationError("Choose your IDE for this checkout: devcapsule project config ide IDE.") - configuration = Configuration(state.manifest, lock, document, state.home, departures=state.departures) + configuration = Configuration(state.manifest, lock, document, state.home, departures=state.departures, + directory=state.host.directory) configuration.review().require_ready(state.root) resolution = configuration.resolve() trust = HomeTrust.read(state.home) diff --git a/devcapsule-src/devcapsule/configuration/listing.py b/devcapsule-src/devcapsule/configuration/listing.py index df7bd6dc..abf09b64 100644 --- a/devcapsule-src/devcapsule/configuration/listing.py +++ b/devcapsule-src/devcapsule/configuration/listing.py @@ -43,7 +43,7 @@ render_authorization_value, review_authorizations, ) -from .bindings import component_secret_inputs, configuration_binding_declarations +from .bindings import DirectoryLookup, component_secret_inputs, configuration_binding_declarations, host_directory from .capabilities import CapabilityPolicy, LocalCapabilities, RequirementDeparture, capability_notes from .file_formats import ProjectConfigurationError, render_toml_scalar, table from .launcher_values import launcher_value_source @@ -199,9 +199,17 @@ def assess_checkout( capability_versions: Mapping[str, str | None] | None = None, capability_providers: Mapping[str, tuple[str, str]] | None = None, departures: tuple[RequirementDeparture, ...] = (), + host_environment: Mapping[str, str] | None = None, + directory: DirectoryLookup | None = None, ) -> Listing: """The listing of one checkout, from its documents, writing nothing. + ``host_environment`` is the environment of the developer's shell, asked + whether a variable is set, never for its value. ``directory`` tells what + the host says of a bound directory. Owner ruling of 2026-11-12, until the + legacy tests that call this are retired: when either is left out, this + process's environment and this machine's file system are asked. + ``composed_lock`` is the shared lock with the checkout's pins laid over it (``capability_selection.compose_lock``); ``surfaces`` maps IDE capability names to the component each selects, as @@ -235,12 +243,14 @@ def assess_checkout( rows.extend(_launcher_value_rows(manifest, checkout, home, project)) rows.extend(_access_rows(manifest, composed_lock if access_lock is None else access_lock, checkout, project, base_display, home, home_path)) - rows.extend(_environment_rows(manifest, saved_environment or {}, project)) + if host_environment is None: + host_environment = os.environ + rows.extend(_environment_rows(manifest, saved_environment or {}, project, host_environment)) rows.extend(_source_rows(manifest)) has_surface = bool(table(composed_lock, "components").get("interactive-surface")) if has_surface: - rows.extend(_binding_rows(composed_lock, checkout, project)) - rows.extend(_secret_rows(composed_lock, checkout, project)) + rows.extend(_binding_rows(composed_lock, checkout, project, directory or host_directory)) + rows.extend(_secret_rows(composed_lock, checkout, project, host_environment)) else: notes.append("State directories and component secrets are listed once an IDE is chosen.") rows.extend(_value_rows(manifest, checkout, project)) @@ -444,6 +454,7 @@ def _source_rows(manifest: Mapping[str, Any]) -> list[ListingRow]: def _environment_rows( manifest: Mapping[str, Any], saved: Mapping[str, str | None], project: Path | None, + host_environment: Mapping[str, str], ) -> list[ListingRow]: rows: list[ListingRow] = [] environment = EnvironmentPolicy.read(manifest) @@ -463,7 +474,7 @@ def _environment_rows( effective = "set" if saved[name] is not None else "from the host's variable" rows.append(ListingRow("env", name, effective, "checkout")) for index, row in enumerate(rows): - if row.name in saved and saved[row.name] is None and row.name not in os.environ: + if row.name in saved and saved[row.name] is None and row.name not in host_environment: rows[index] = ListingRow("env", row.name, "unset", row.source, "the bound host variable is missing in this shell", _command(project, "env", "set", row.name, "VALUE"), @@ -472,7 +483,8 @@ def _environment_rows( return rows -def _binding_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: Path | None) -> list[ListingRow]: +def _binding_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: Path | None, + directory: DirectoryLookup) -> list[ListingRow]: try: declarations = configuration_binding_declarations(lock) except ProjectConfigurationError as exc: @@ -483,8 +495,9 @@ def _binding_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: for name in sorted(declarations): bound = bindings.get(name, adopted.get(name)) if isinstance(bound, str): - path = Path(bound).expanduser() - if path.is_dir(): + found = directory(bound) + path = found.expanded + if found.exists: rows.append(ListingRow("binding", name, str(path), "checkout")) else: rows.append(ListingRow("binding", name, str(path), "checkout", "the directory does not exist", @@ -494,7 +507,8 @@ def _binding_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: return rows -def _secret_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: Path | None) -> list[ListingRow]: +def _secret_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: Path | None, + host_environment: Mapping[str, str]) -> list[ListingRow]: try: declarations = component_secret_inputs(lock) except ProjectConfigurationError as exc: @@ -504,7 +518,7 @@ def _secret_rows(lock: Mapping[str, Any], checkout: Mapping[str, Any], project: for name, declaration in sorted(declarations.items()): variable = declaration.environment_variable if name in bound: - available = variable in os.environ + available = variable in host_environment rows.append(ListingRow("secret", name, f"from {variable}", "checkout" if available else "checkout (variable unset in this shell)")) elif declaration.required: command = _command(project, "bind", name, f"host-environment:{variable}") diff --git a/devcapsule-src/devcapsule/configuration/model.py b/devcapsule-src/devcapsule/configuration/model.py index b0081a37..eb1c9e0e 100644 --- a/devcapsule-src/devcapsule/configuration/model.py +++ b/devcapsule-src/devcapsule/configuration/model.py @@ -17,6 +17,7 @@ from devcapsule.components.catalog import INTERACTIVE_SURFACES +from .bindings import DirectoryLookup from .capabilities import RequirementDeparture from .authorization import locked_base_reference from .file_formats import ConfigurationFileKind, ProjectConfigurationError, canonical_digest, validate_file_format, table @@ -36,7 +37,11 @@ class Configuration: def __init__(self, manifest: Mapping[str, Any], lock: Mapping[str, Any], checkout: Mapping[str, Any], home: Mapping[str, Any] | None = None, *, - departures: tuple[RequirementDeparture, ...] = ()) -> None: + departures: tuple[RequirementDeparture, ...] = (), + directory: DirectoryLookup | None = None) -> None: + # ``directory`` tells what the host says of a bound directory. Left out, + # the review asks this machine: owner ruling of 2026-11-12, until the + # legacy tests that construct a Configuration are retired. # The manifest as given is the file's own schema; a checkpoint from # before scoped digests recorded its whole digest, kept for freshness. self._manifest = current_manifest(manifest, Path("manifest")).document() @@ -63,7 +68,7 @@ def __init__(self, manifest: Mapping[str, Any], lock: Mapping[str, Any], LocalCapabilities.read(self._checkout).validate(policy) if policy.minimums and table(self._checkout, "authorization", "base-image").get("image-id"): raise ProjectConfigurationError("A local base override cannot establish the project's minimum-version guarantee; select the pinned project base.") - self._review = review_configuration(self._manifest, self._lock, self._checkout, self._home) + self._review = review_configuration(self._manifest, self._lock, self._checkout, self._home, directory=directory) def review(self) -> ConfigurationReview: return deepcopy(self._review) diff --git a/devcapsule-src/devcapsule/configuration/review.py b/devcapsule-src/devcapsule/configuration/review.py index 4d1e6ec5..015788d5 100644 --- a/devcapsule-src/devcapsule/configuration/review.py +++ b/devcapsule-src/devcapsule/configuration/review.py @@ -13,7 +13,7 @@ from typing import Any, Mapping from .authorization import AuthorizationChoice, AuthorizationReview, review_authorizations -from .bindings import resolve_configuration_bindings, resolve_secret_bindings +from .bindings import DirectoryLookup, resolve_configuration_bindings, resolve_secret_bindings from .file_formats import AuthorizationScalar, ConfigurationScalar, ProjectConfigurationError, table from .nodes import build_node_registry from .launcher_values import resolve_launcher_values @@ -135,8 +135,14 @@ def effective_host(self, overrides: Mapping[str, Any] | None = None) -> HostAcce def review_configuration( manifest: Mapping[str, Any], lock: Mapping[str, Any], checkout: Mapping[str, Any], home: Mapping[str, Any] | None = None, + *, + directory: DirectoryLookup | None = None, ) -> ConfigurationReview: - """Assess one checkout; ``home`` holds the home's defaults for the launcher-owned values.""" + """Assess one checkout; ``home`` holds the home's defaults for the launcher-owned values. + + ``directory`` tells what the host says of a bound directory; left out, + this machine is asked (see ``resolve_configuration_bindings``). + """ # No consumer can assess a tree with ambiguous names or runtime effects. build_node_registry(manifest, lock) problems: list[str] = [] @@ -161,7 +167,7 @@ def review_configuration( except ProjectConfigurationError as exc: problems.append(str(exc)) try: - bindings = resolve_configuration_bindings(lock, checkout) + bindings = resolve_configuration_bindings(lock, checkout, directory) except ProjectConfigurationError as exc: problems.append(str(exc)) try: @@ -178,7 +184,7 @@ def review_configuration( problems.append("Checkout state.adopted must be a table.") else: try: - resolve_configuration_bindings(lock, {"configuration": {"bindings": {"host-directory": adopted}}}) + resolve_configuration_bindings(lock, {"configuration": {"bindings": {"host-directory": adopted}}}, directory) except ProjectConfigurationError as exc: problems.append("Adopted state: " + str(exc)) overlap = sorted(set(adopted) & set(bindings)) diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index 01e4e29d..6712fe1f 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -19,6 +19,7 @@ from devcapsule.commands._launch_review import RunFlags, review_launch, stage_trust from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value +from devcapsule.configuration.bindings import HostDirectory from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture from devcapsule.configuration.capability_selection import generate_lock from devcapsule.configuration.derivation import CheckoutState, Host, Selection @@ -46,11 +47,26 @@ def no_local_image(reference: str) -> Any: pytest.fail(f"the review asked the Docker daemon for {reference}") -def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Host | None = None) -> CheckoutState: +def a_host(*, variables: tuple[str, ...] = (), directories: tuple[str, ...] = (), local_image: Any = no_local_image) -> Host: + """A host whose shell sets ``variables``, on which ``directories`` exist, and whose clock shows ``ACCEPTED_AT``. + + A directory resolves to its name under ``/resolved``, so that a test can + tell the resolved path from the name the developer gave. Asked for a local + image, the host fails the test unless ``local_image`` is given. + """ + def directory(name: str) -> HostDirectory: + return HostDirectory(Path(name), Path("/resolved") / name.lstrip("~/"), name in directories) + + return Host(local_image=local_image, now=lambda: ACCEPTED_AT, + environment={name: "a value no decision reads" for name in variables}, directory=directory) + + +def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Host | None = None, + manifest_tables: dict[str, Any] | None = None) -> CheckoutState: """A registered checkout of a project that requires ``required``, in a home that has accepted nothing. - Its host tells the time ``ACCEPTED_AT`` and fails the test when asked for - a local image, unless ``host`` is given. + Its host is ``a_host()`` unless ``host`` is given. ``manifest_tables`` are + further tables of the manifest, ``environment`` for instance. It is what ``project init --require ... --ide IDE --authorize base-image default`` leaves, built with the operations that command uses and no file: @@ -61,13 +77,14 @@ def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Hos "devcapsule-schema-version": 2, "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, "capabilities": {"required": sorted(required)}, + **(manifest_tables or {}), } state = CheckoutState( root=ROOT, manifest=manifest, platform=Platform.LINUX_AMD64, lock_path=ROOT / ".devcapsule" / "devcapsule.linux-amd64.lock", shared_lock=generate_lock(CapabilityPolicy.read(manifest), MATRICES[Platform.LINUX_AMD64]), home={}, home_path=HOME, input_path=RECORD, registered=True, - host=host or Host(local_image=no_local_image, now=lambda: ACCEPTED_AT), + host=host or a_host(), checkout=tomllib.loads(render_checkout(manifest, ROOT, {}, {})), ) selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) @@ -269,7 +286,7 @@ def no_such_image(reference: str) -> Any: asked.append(reference) raise ProjectConfigurationError(f"no local image {reference}") - state = checkout_of(REQUIRING_PYCHARM, host=Host(local_image=no_such_image, now=lambda: ACCEPTED_AT)) + state = checkout_of(REQUIRING_PYCHARM, host=a_host(local_image=no_such_image)) record = CheckoutRecord.staged(RECORD, state.checkout) base_image = authorization_declarations(state.manifest, state.composed_lock())["base-image"] record.authorize(base_image, "local/devcapsule-base:work", image_identity="sha256:" + "a" * 64) @@ -279,3 +296,56 @@ def no_such_image(reference: str) -> Any: review_launch(state, RunFlags(), ask=None, announce=never_announced) assert asked == ["local/devcapsule-base:work"] + + +NEEDING_A_TOKEN: dict[str, Any] = {"environment": {"required": {"SERVICE_TOKEN": {"reason": "the service's API"}}}} +"""A manifest table that makes the project need the variable ``SERVICE_TOKEN``.""" + + +def test_a_variable_taken_from_the_host_must_be_set_in_the_developers_shell() -> None: + """A required variable that the checkout takes from the host, on a host whose shell does not set it, leaves + the review pending on that variable.""" + state = checkout_of(REQUIRING_PYCHARM, host=a_host(variables=()), manifest_tables=NEEDING_A_TOKEN) + state.saved_environment = {"SERVICE_TOKEN": None} + + with pytest.raises(DecisionPending, match="env SERVICE_TOKEN: The bound host variable is missing in this shell"): + review_launch(state, RunFlags(), ask=None, announce=never_announced) + + +def test_a_variable_taken_from_the_host_is_settled_when_the_shell_sets_it() -> None: + """The same checkout on a host whose shell sets the variable is planned without a question.""" + state = checkout_of(REQUIRING_PYCHARM, host=a_host(variables=("SERVICE_TOKEN",)), manifest_tables=NEEDING_A_TOKEN) + state.saved_environment = {"SERVICE_TOKEN": None} + + review = review_launch(state, RunFlags(), ask=None, announce=never_announced) + + assert review.selected.resolution["runtime"]["component"] == "pycharm" + + +def bound_home(directory: str, host: Host) -> CheckoutState: + """The order's checkout with its ``home`` state bound to a directory of the host, as ``config bind`` records it.""" + state = checkout_of(REQUIRING_PYCHARM, host=host) + record = CheckoutRecord.staged(RECORD, state.checkout) + record.directory_bindings["home"] = directory + state.checkout = record.export() + return state + + +def test_a_bound_directory_the_host_does_not_have_refuses_the_plan() -> None: + """A checkout bound to a directory that does not exist on the host is refused, naming the path as the host + resolved it.""" + state = bound_home("~/capsule-home", a_host(directories=())) + + with pytest.raises(ProjectConfigurationError, match="binding 'home' is not an existing directory: /resolved/capsule-home"): + review_launch(state, RunFlags(), ask=None, announce=never_announced) + + +def test_a_bound_directory_the_host_has_is_planned_by_its_resolved_path() -> None: + """A checkout bound to a directory that exists on the host is planned with the path as the host resolved it, + and the launch's checkout keeps the name the developer gave.""" + state = bound_home("~/capsule-home", a_host(directories=("~/capsule-home",))) + + review = review_launch(state, RunFlags(), ask=None, announce=never_announced) + + assert review.selected.resolution["state"]["bindings"] == {"home": "/resolved/capsule-home"} + assert review.selected.checkout["configuration"]["bindings"]["host-directory"] == {"home": "~/capsule-home"} From 7b507ef11b61ae4af32688c5a7ff7dbfa4232e8e Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:12:12 +0000 Subject: [PATCH 23/75] Tests: the IDE-override decisions in memory, twelve of the legacy file's twenty-six tests tests/test_ide_requirement_override.py is ordered retired whole. These are the tests of it that need no product change: - test_launch_review.py: a forced IDE replaces the required one and keeps the rest; a saved version set; the minimum a departure waives and the one it does not; the required IDE named by another spelling; a schema-1 manifest. 33 tests now. - configuration/test_capabilities.py, new: CapabilityPolicy.departing. - configuration/test_capability_selection.py: a saved IDE that conflicts with a later requirement names the override. - capabilities.py and bindings.py declare __all__. The legacy file stays: its other fourteen tests reach the command line with patched launch and materialization, files, a patched component class and a mirror with a legacy twin. The maintenance status lists the five product changes they wait for. Evidence: nox -s typecheck passes over 345 files; nox -s tests, 3045 passed with the capsule's 17 standing failures; 0 convention breaches. Co-Authored-By: Claude --- .../devcapsule/configuration/bindings.py | 7 ++ .../devcapsule/configuration/capabilities.py | 7 ++ .../devcapsule/commands/test_launch_review.py | 95 ++++++++++++++++++- .../configuration/test_capabilities.py | 29 ++++++ .../test_capability_selection.py | 21 +++- 5 files changed, 157 insertions(+), 2 deletions(-) create mode 100644 devcapsule-src/tests/unit/devcapsule/configuration/test_capabilities.py diff --git a/devcapsule-src/devcapsule/configuration/bindings.py b/devcapsule-src/devcapsule/configuration/bindings.py index 91f49c24..8dcbce06 100644 --- a/devcapsule-src/devcapsule/configuration/bindings.py +++ b/devcapsule-src/devcapsule/configuration/bindings.py @@ -11,6 +11,13 @@ from devcapsule.platforms import XdgHomes +__all__ = [ + "ConfigurationBindingDeclaration", "DirectoryLookup", "HostDirectory", "SecretInputMetadata", + "component_secret_inputs", "configuration_binding_declarations", "host_directory", "managed_binding_path", + "resolve_configuration_bindings", "resolve_secret_bindings", +] + + @dataclass(frozen=True) class ConfigurationBindingDeclaration: name: str diff --git a/devcapsule-src/devcapsule/configuration/capabilities.py b/devcapsule-src/devcapsule/configuration/capabilities.py index be5db675..4dd120e8 100644 --- a/devcapsule-src/devcapsule/configuration/capabilities.py +++ b/devcapsule-src/devcapsule/configuration/capabilities.py @@ -12,6 +12,13 @@ from .file_formats import ProjectConfigurationError, table +__all__ = [ + "CapabilityPolicy", "IDE_REQUIREMENT", "LocalCapabilities", "RETIRED_CAPABILITY_FIELD", "RequirementDeparture", + "capability_notes", "current_capability_fields", "meets_minimum", "names", "provider_choices", "requirement", + "resolution_recommendations", "version_parts", +] + + def names(value: object, label: str) -> tuple[str, ...]: """Return sorted, unique names from a decoded TOML array. diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index 6712fe1f..b09ede20 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -23,8 +23,9 @@ from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture from devcapsule.configuration.capability_selection import generate_lock from devcapsule.configuration.derivation import CheckoutState, Host, Selection -from devcapsule.configuration.file_formats import ProjectConfigurationError, render_checkout +from devcapsule.configuration.file_formats import ProjectConfigurationError, canonical_digest, render_checkout, render_toml from devcapsule.configuration.listing import Decision +from devcapsule.configuration.manifest import current_manifest from devcapsule.configuration.operations import CheckoutRecord from devcapsule.configuration.values import memory_size_bytes from devcapsule.platforms import Platform @@ -349,3 +350,95 @@ def test_a_bound_directory_the_host_has_is_planned_by_its_resolved_path() -> Non assert review.selected.resolution["state"]["bindings"] == {"home": "/resolved/capsule-home"} assert review.selected.checkout["configuration"]["bindings"]["host-directory"] == {"home": "~/capsule-home"} + + +@pytest.mark.parametrize("named", ["codium", "frontend-ide"]) +def test_a_forced_ide_replaces_the_required_one_and_keeps_every_other_requirement(named: str) -> None: + """``--ide codium --force`` against a required PyCharm plans VSCodium, by component or capability name, with + the departure in the plan. PyCharm is not in the launch's lock; the unrelated mandatory tool is. The + project's policy and the record staged for writing are as they were; only the launch's own copy of the + checkout selects the other IDE.""" + review = review_launch(checkout_of(REQUIRING_PYCHARM), RunFlags(ide=named, force=True), ask=None, announce=never_announced) + + selected = review.selected + assert selected.departures == (RequirementDeparture(IDE_REQUIREMENT, "python-ide", "frontend-ide"),) + assert selected.resolution["runtime"]["component"] == "codium" + assert selected.resolution["departures"] == {IDE_REQUIREMENT: {"required": "python-ide", "launched": "frontend-ide"}} + components = selected.lock["components"] + assert components["interactive-surface"] == "codium" and "codium" in components + assert "pycharm" not in components + assert "codex" in components + assert CapabilityPolicy.read(selected.manifest).required == ("codex-agent", "python", "python-ide") + assert review.record.document == review.original + assert LocalCapabilities.read(review.record.document).selected == ("python-ide",) + assert "frontend-ide" in LocalCapabilities.read(selected.checkout).selected + + +def test_a_forced_ide_is_planned_from_a_saved_version_set() -> None: + """A checkout that saved its version set, PyCharm's, is still planned with VSCodium under ``--force``: the + departure is in the plan, PyCharm is not in the launch's lock, and the saved set is not staged for change.""" + state = checkout_of(REQUIRING_PYCHARM) + state.checkout["version-set"] = {"format": 1, "lock": render_toml(state.composed_lock()), + "recommendation-digest": canonical_digest(state.shared_lock)} + + review = review_launch(state, RunFlags(ide="codium", force=True), ask=None, announce=never_announced) + + assert review.selected.resolution["runtime"]["component"] == "codium" + assert review.selected.resolution["departures"][IDE_REQUIREMENT]["required"] == "python-ide" + assert "pycharm" not in review.selected.lock["components"] + assert "codex" in review.selected.lock["components"] + assert review.record.document == review.original + + +def requiring_minimums(*requirements: str) -> CheckoutState: + """The order's checkout after its owner rewrote the requirements with minimum versions; lock and record are older.""" + state = checkout_of(REQUIRING_PYCHARM) + state.manifest["capabilities"]["required"] = list(requirements) + return state + + +@pytest.mark.parametrize("required_ide", ["python-ide", "pycharm"]) +def test_force_has_nothing_to_set_aside_when_the_required_ide_is_named_by_another_spelling(required_ide: str) -> None: + """Whether the project requires the IDE by capability or by component name, ``--ide python-ide --force`` is + refused: the two names are the same IDE.""" + state = requiring_minimums("python>=3", f"{required_ide}>=9999", "codex-agent") + + with pytest.raises(ProjectConfigurationError, match="nothing to set aside"): + review_launch(state, RunFlags(ide="python-ide", force=True), ask=None, announce=never_announced) + + +@pytest.mark.parametrize("required_ide", ["python-ide", "pycharm"]) +def test_a_departure_waives_the_minimum_of_the_ide_it_sets_aside(required_ide: str) -> None: + """With a minimum on the required IDE that no version meets, a forced VSCodium is planned, and the plan + names the requirement as the project declared it.""" + state = requiring_minimums("python>=3", f"{required_ide}>=9999", "codex-agent") + + review = review_launch(state, RunFlags(ide="codium", force=True), ask=None, announce=never_announced) + + assert review.selected.resolution["runtime"]["component"] == "codium" + assert review.selected.resolution["departures"][IDE_REQUIREMENT]["required"] == required_ide + + +def test_a_departure_waives_no_other_minimum() -> None: + """A minimum on Python that no version meets still refuses the forced launch: only the IDE's is waived.""" + state = requiring_minimums("python>=9999", "python-ide>=9999", "codex-agent") + + with pytest.raises(ProjectConfigurationError, match="python.*9999"): + review_launch(state, RunFlags(ide="codium", force=True), ask=None, announce=never_announced) + + +def test_a_schema_one_manifest_recommends_its_ide_and_another_needs_no_force() -> None: + """A schema-1 manifest's ``need`` list, read as this launcher reads it, requires no IDE: ``--ide codium`` + without ``--force`` plans VSCodium with no departure and stages no change to the record.""" + state = checkout_of(REQUIRING_PYCHARM) + state.manifest = current_manifest({ + "devcapsule-schema-version": 1, + "project": dict(state.manifest["project"]), + "capabilities": {"need": ["python", "python-ide", "codex-agent"]}, + }, "the project's manifest").document() + + review = review_launch(state, RunFlags(ide="codium"), ask=None, announce=never_announced) + + assert review.selected.resolution["runtime"]["component"] == "codium" + assert review.selected.departures == () and "departures" not in review.selected.resolution + assert review.record.document == review.original diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_capabilities.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_capabilities.py new file mode 100644 index 00000000..1d02af56 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_capabilities.py @@ -0,0 +1,29 @@ +"""Unit tests of ``devcapsule/configuration/capabilities.py``: a launch's departure from a project's requirement.""" +from __future__ import annotations + +from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, RequirementDeparture + +REQUIRING_PYCHARM = CapabilityPolicy( + ("python", "python-ide"), ("browser-automation",), (("python", "3.12"), ("python-ide", "2026")), +) +"""A policy that requires Python and PyCharm, each with a minimum version, and offers one optional capability.""" + + +def test_departing_sets_aside_the_named_requirement_and_its_minimum() -> None: + """A departure from the required IDE gives a policy without that requirement and without its minimum; + the other requirement, its minimum and the optional capability stay.""" + departed = REQUIRING_PYCHARM.departing((RequirementDeparture(IDE_REQUIREMENT, "python-ide", "frontend-ide"),)) + + assert departed == CapabilityPolicy(("python",), ("browser-automation",), (("python", "3.12"),)) + + +def test_departing_from_a_capability_the_policy_does_not_require_changes_nothing() -> None: + """A departure that names a capability the policy does not require returns the policy itself.""" + departure = RequirementDeparture(IDE_REQUIREMENT, "java-ide", "frontend-ide") + + assert REQUIRING_PYCHARM.departing((departure,)) is REQUIRING_PYCHARM + + +def test_departing_with_no_departure_changes_nothing() -> None: + """With no departure the policy itself is returned.""" + assert REQUIRING_PYCHARM.departing(()) is REQUIRING_PYCHARM diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_selection.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_selection.py index db22e10a..3b2be1b4 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_selection.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_selection.py @@ -8,7 +8,8 @@ import pytest -from devcapsule.configuration.capability_selection import pins_for_platform +from devcapsule.configuration.capabilities import CapabilityPolicy +from devcapsule.configuration.capability_selection import generate_lock, pins_for_platform, selected_lock from devcapsule.configuration.file_formats import ProjectConfigurationError from devcapsule.platforms import Platform from devcapsule.resolution_matrix import MATRICES, ResolutionMatrix @@ -51,3 +52,21 @@ def test_a_personal_version_the_other_platform_lacks_asks_for_a_new_choice() -> channel = {"platform": "linux-amd64", "components": {"codex": {"version": "9.9.9", "url": "https://example.test/x64.tgz"}}} with pytest.raises(ProjectConfigurationError, match="codex 9.9.9 is pinned for linux-amd64.*linux-arm64 has no pin.*config use"): pins_for_platform(channel, ARM64) + + +def test_a_saved_ide_that_conflicts_with_the_required_one_is_refused_naming_the_override() -> None: + """A checkout whose saved IDE is VSCodium, in a project that now requires PyCharm, has no effective lock: + the refusal names both IDEs and the ``--force`` launch that sets the requirement aside once.""" + manifest: dict[str, Any] = { + "devcapsule-schema-version": 2, + "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, + "capabilities": {"required": ["codex-agent", "python", "python-ide"]}, + } + shared = generate_lock(CapabilityPolicy.read(manifest), AMD64) + checkout = {"capabilities": {"selected": ["frontend-ide"], "lock": AMD64.resolve(["frontend-ide"]).render_lock()}} + + with pytest.raises( + ProjectConfigurationError, + match="Local IDE 'frontend-ide' conflicts with the project's required IDE 'python-ide'.*--ide frontend-ide --force", + ): + selected_lock(manifest, shared, checkout) From e42052dc3c9c05649ca9273d61f7f79b485b6ce7 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:12:12 +0000 Subject: [PATCH 24/75] Maintenance status: option 3 on the last host read, and where the first legacy file's retirement stands Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 76 ++++++++++++------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 9ff49515..c05f3a10 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -57,7 +57,7 @@ slice, on `ws-maintenance/launch-phases`, stacked on PR #26. `read_launch_state`, `review_launch`, `save_launch`. The terminal dialogue stays here and is passed to the review as `ask`. -**The tests.** `tests/unit/devcapsule/commands/test_launch_review.py`, 20 +**The tests.** `tests/unit/devcapsule/commands/test_launch_review.py`, 33 tests, none with a project directory, a home, `tmp_path` or a patch. Each builds its checkout in memory with the operations `project init` uses: `generate_lock` for the lock, `with_selection` and `authorize` for the @@ -85,42 +85,64 @@ caught by the new tests, 15 by legacy tests, 6 by nothing: - the clock that `load_state` binds, one line that names the real one. **What the decision phase asked of the host, and what it asks now.** The -first commit of the slice left five. The owner asked why. Three had no -caller among the legacy tests and are closed in the second commit: the state -carries a `Host` of two functions, bound by `load_state`; `derive_plan` asks -it for a local base image and `stage_trust` asks it for the time; a run-once -authorization goes to a function the review is given, `announce`. A fourth, -the dialogue with the developer, is `ask`, a function the review is given -too. One is left, in two places below the review: - -- the listing asks `os.environ` whether a host variable is set, and the file - system whether a bound directory exists, in `assess_checkout`; -- the configuration review resolves a bound directory's path and asks - whether it exists, in `Configuration`. - -Making these values means a new required argument on `assess_checkout` and -on `Configuration`. Five legacy files call them: `tests/test_listing.py` -three times, and `tests/configuration/test_adt.py`, -`tests/test_ide_requirement_override.py`, `tests/test_capability_policy.py` -and `tests/test_trust.py` sixteen times between them. Rule 5 of *Unit Tests* -makes an edited call in a legacy test the retirement of its file, and rule 2 -of *Host Inputs* forbids the other way, an optional argument whose default -reads the host. So this last read waits for one of three rulings: the five -files are retired first; rule 5 lets a call site in a legacy test follow a -signature; or the argument is optional until they are retired. +first commit of the slice left five reads. The owner asked why. All are +closed. The state carries a `Host`, bound by `load_state`: the shell's +environment, a lookup of a bound directory, a lookup of a local base image, +and the clock. The review is given two functions besides: `ask`, the +dialogue with the developer, and `announce`, for a run-once authorization. +A test passes its own of each. + +**The owner's ruling on the last read, 2026-11-12: option 3.** The listing +and the configuration review asked `os.environ` and the file system inside +`assess_checkout` and `Configuration`, which five legacy files call 19 +times. Rule 5 of *Unit Tests* would retire a file for an edited call, and +rule 2 of *Host Inputs* forbids an argument whose default reads the host. +The owner chose the optional argument until those files are retired: +`host_environment` and `directory` on `assess_checkout`, `directory` on +`Configuration`, `review_configuration` and `resolve_configuration_bindings`. +Left out, this process and this machine are asked, as before. The launch +passes them from the `Host`. The rule's text is not amended; each default +names the ruling in its docstring. + +**`tests/test_ide_requirement_override.py`, ordered retired whole. It is not +yet.** Of its 26 test functions, 12 now have a form that needs no file, no +home and no patch: 10 in `test_launch_review.py`, 1 as three tests in the +new `tests/unit/devcapsule/configuration/test_capabilities.py`, 1 in +`test_capability_selection.py`. The other 14 wait for five changes to the +product, because each reaches something the code takes from a global: + +1. Six drive `project run` through `cli.main` with the Docker launch and the + materialization replaced by patches on `commands.project`. The command's + body, `ProjectCommand._run`, is some 300 lines that read files, settings + and those two module names. It must take them as values first. +2. Four more go through `cli.main` for a refusal and need no stand-in. They + become integration tests that start the program. +3. Three read or write the launch's files: the listing of a departed launch, + the plan file of the launch after it, and `config show`. The last one + patches `runtime_configuration.CHANNEL_PATH`, the capsule's fixed + `/run/devcapsule-configuration`. +4. One patches a method of a component class to give Codex a dependency on + an IDE; `usable_lock` takes the component catalog from a global. +5. One tests `realize_environment`, whose mirror file has a legacy twin of 9 + tests; adding a test there retires that twin too. + +Until then rule 5 keeps the legacy file whole, the 12 tests stand twice, and +2 of the capsule's 17 failures stay. **Differences in behaviour.** Two orders of refusal: a checkout that cannot be given a free record name is now refused before a wrong IDE is, and the console's requests are read once per review, so one that arrives during a review is seen at the next run. -**Not done.** The retirement of the six legacy files. `load_state` still +**Not done.** The retirement of the six legacy files; see the first of them above. `load_state` still finds the home through the environment, so the reading has no test from values yet. `_run_flow.py` has no mirror test, since its legacy twin `tests/test_run_flow.py` stands. -**Next action.** The owner's: the order in which the six files are retired, -and whether the 17 wait for that or get the one-line fixture change first. +**Next action.** The owner's: whether `ProjectCommand._run` is restructured +before 0.3.1, which the retirement of this file and of `tests/test_run_flow.py` +both need; and whether the 17 wait for that or get the one-line fixture +change first. ## Two rules held by machine: no network in a unit test, the command line only in `test_cli.py` — 2026-11-12 From b2d891e3cd6165e13975623c5411caee3962bb2b Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:12:42 +0000 Subject: [PATCH 25/75] Maintenance status: three refusal tests, not four Co-Authored-By: Claude --- engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index c05f3a10..6f13a125 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -115,7 +115,7 @@ product, because each reaches something the code takes from a global: materialization replaced by patches on `commands.project`. The command's body, `ProjectCommand._run`, is some 300 lines that read files, settings and those two module names. It must take them as values first. -2. Four more go through `cli.main` for a refusal and need no stand-in. They +2. Three more go through `cli.main` for a refusal and need no stand-in. They become integration tests that start the program. 3. Three read or write the launch's files: the listing of a departed launch, the plan file of the launch after it, and `config show`. The last one From 6c9950cc11cd396a8037c43ea5b18d62d050f4d4 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:51:54 +0000 Subject: [PATCH 26/75] Unit Tests rule 5: a legacy test's call may follow a signature by its keyword arguments Owner direction of 2026-11-12, option 2, beside option 3. - WORKFLOW-LOCAL.md: rule 5 allows one change to a legacy test, keyword arguments added to or removed from a call when the function's signature changes in the same pull request. Host Inputs rule 2 names the two functions that keep a host-reading default until their legacy callers are retired. The companion says why, for both. - scripts/validate_unittests_follow_conventions.py: a changed legacy test is accepted when its two versions differ only in which keyword arguments the calls in its body name. Positional arguments, the values of keywords that stay, every other statement, the decorators and the test's own parameters must be the same; a change of layout alone is still refused. Evidence: 12 new cases in the checker's tests, 4 accepted forms and 8 refused ones; nox -s typecheck passes; 0 breaches in the repository. Co-Authored-By: Claude --- WORKFLOW-LOCAL-humane.md | 23 +++++++ WORKFLOW-LOCAL.md | 9 ++- .../validate_unittests_follow_conventions.py | 61 ++++++++++++++++++- ...t_validate_unittests_follow_conventions.py | 49 +++++++++++++++ engineering-docs/development/unit-tests.md | 4 +- 5 files changed, 141 insertions(+), 5 deletions(-) diff --git a/WORKFLOW-LOCAL-humane.md b/WORKFLOW-LOCAL-humane.md index 9839554d..1c66232f 100644 --- a/WORKFLOW-LOCAL-humane.md +++ b/WORKFLOW-LOCAL-humane.md @@ -266,6 +266,22 @@ process. Git on a scratch repository can pass both, and even then its commit dates come from the clock unless the test sets them. A Docker build passes neither. +The allowance in rule 5 was added on 2026-11-12. Rule 5 made every change +to a function's signature cost the whole legacy file of each test that +called it: in PR #26 one removed keyword retired a file of 22 tests, and +making the listing take the host's environment as an argument would have +retired five files for nineteen one-line calls. The owner's ruling: a call +in a legacy test may follow the signature, by keyword arguments added or +removed, and by nothing else. The test stays legacy and asserts what it +asserted; when the new argument is the host itself, the call now says so. +The gate holds the form of the change, by comparing the two versions of +the test as syntax: positional arguments, the values of the keywords that +stay, every other statement, the decorators and the test's own parameters +must be the same, and a change of layout alone is still refused. That the +signature did change is left to the reviewer. Beside it the owner allowed, +for two functions that five legacy files call, an argument that is optional +until those files are retired; see *Host Inputs*. + The rules on the command line and on the network were added on 2026-11-12, from one test. `test_offered_agent_still_needs_consent_and_can_be_omitted` calls `cli.main` four times and expects the second call to stop for consent @@ -341,6 +357,13 @@ why the entry layer must stay small. A value that is costly to read, the installed version for instance, is passed as a function so that the top layer does not pay for it on every start. +One exception stands by the owner's ruling of 2026-11-12. `assess_checkout` +and `Configuration` take what the host says, its environment and its +directories, as arguments that may be left out, and then ask this machine +themselves. Five legacy test files call them nineteen times and rely on +that. The launch passes the arguments. The defaults go when those files are +retired, or sooner by the allowance of *Unit Tests* rule 5. + ## Reasoning And Code Navigation **Rule.** Start from the contract, state the uncertainty, navigate from the diff --git a/WORKFLOW-LOCAL.md b/WORKFLOW-LOCAL.md index 4e9a93c9..e84d2678 100644 --- a/WORKFLOW-LOCAL.md +++ b/WORKFLOW-LOCAL.md @@ -218,7 +218,10 @@ capsule for reasons that were not bugs. until it declares one: `__all__`, or a module docstring that names the public operations and leaves the rest private. 5. Existing test files carry `pytestmark = pytest.mark.legacy`. Do not - add, change or delete individual test functions in a legacy file. The + add, change or delete individual test functions in a legacy file. + Owner direction, 2026-11-12: one change is allowed. When a pull request + changes the signature of a function, a call to it in a legacy test may + gain or lose keyword arguments. Change nothing else in the test. The mirror of a legacy file `tests/test_.py` is every `tests/unit//test_.py`; the gate pairs them by file name alone. When a change edits a test in a legacy file or adds, changes or @@ -262,7 +265,9 @@ patches. 2. Every other module takes these as values, in required arguments. Give no parameter a default that reads the host. Add no parameter that only a test passes. Pass a value that is costly to read as a function without - arguments. + arguments. Owner direction, 2026-11-12: `assess_checkout` and + `Configuration` keep such a default until the legacy tests that call + them are retired. 3. Bind the values that several operations share in a frozen dataclass. Its constructor stores them and does nothing else. 4. Separate each decision from its effect. Write the decision as a function diff --git a/devcapsule-src/scripts/validate_unittests_follow_conventions.py b/devcapsule-src/scripts/validate_unittests_follow_conventions.py index 81e8ab96..1b51f303 100644 --- a/devcapsule-src/scripts/validate_unittests_follow_conventions.py +++ b/devcapsule-src/scripts/validate_unittests_follow_conventions.py @@ -16,7 +16,10 @@ 3. **Whole-file legacy retirement.** A legacy file, one whose module-level ``pytestmark`` includes ``legacy``, is compared with the base revision: no test function is added, changed or removed while the file remains, and - no marker other than ``legacy`` is added. A legacy file the base does not + no marker other than ``legacy`` is added. One change to a test is let + through: calls in its body that gain or lose keyword arguments, which is + how a legacy test follows a function whose signature changed. That the + signature did change is the reviewer's to see. A legacy file the base does not have is refused. Adding, changing or deleting a test in ``tests/unit//test_.py`` while a flat legacy unit-test file ``tests/test_.py`` still exists is also refused, the two paired by file name alone; refurbish the entire @@ -41,6 +44,7 @@ import os import subprocess import sys +import textwrap from collections.abc import Iterable, Sequence from dataclasses import dataclass, field from pathlib import Path @@ -330,7 +334,7 @@ def _check_legacy(module: TestModule, base: TestModule | None) -> list[str]: f"{module.path}: {name} was added to a legacy file; " f"refurbish the whole legacy file into {UNIT_MIRROR} and delete {module.path}" ) - elif source != base.functions[name]: + elif source != base.functions[name] and not _only_call_keywords_differ(base.functions[name], source): breaches.append( f"{module.path}: {name} changed in a legacy file; " f"refurbish the whole legacy file into {UNIT_MIRROR} and delete {module.path}" @@ -346,6 +350,59 @@ def _check_legacy(module: TestModule, base: TestModule | None) -> list[str]: return breaches +def _only_call_keywords_differ(before: str, after: str) -> bool: + """Whether two versions of a test function differ by keyword arguments of calls in the body, and by nothing else. + + This is the one change rule 3 lets through. True needs at least one call + that gained or lost a keyword argument: a change of layout or of a + comment alone is still a change to a legacy test. The decorators and the + function's own parameters must be the same. + """ + try: + old, new = (ast.parse(textwrap.dedent(source)).body[0] for source in (before, after)) + except SyntaxError: + return False + if not isinstance(old, (ast.FunctionDef, ast.AsyncFunctionDef)) or type(old) is not type(new): + return False + assert isinstance(new, (ast.FunctionDef, ast.AsyncFunctionDef)) + def header(function: ast.FunctionDef | ast.AsyncFunctionDef) -> tuple[str, str, list[str]]: + return function.name, ast.dump(function.args), [ast.dump(item) for item in function.decorator_list] + + if header(old) != header(new) or len(old.body) != len(new.body): + return False + moved: list[str] = [] + same = all(_same_but_for_call_keywords(mine, theirs, moved) for mine, theirs in zip(old.body, new.body)) + return same and bool(moved) + + +def _same_but_for_call_keywords(old: object, new: object, moved: list[str]) -> bool: + """Compare two syntax trees node by node; a call may differ in which keyword arguments it names. + + ``moved`` collects the name of every keyword argument found on one side + only. A keyword argument both sides name must have the same value, and so + must every positional argument and every ``**`` argument. + """ + if isinstance(old, list) and isinstance(new, list): + return len(old) == len(new) and all(_same_but_for_call_keywords(a, b, moved) for a, b in zip(old, new)) + if not isinstance(old, ast.AST) or not isinstance(new, ast.AST): + return old == new # a name, a constant's value, an operator's absence + if type(old) is not type(new): + return False + if isinstance(old, ast.Call) and isinstance(new, ast.Call): + named_old = {keyword.arg: keyword.value for keyword in old.keywords if keyword.arg is not None} + named_new = {keyword.arg: keyword.value for keyword in new.keywords if keyword.arg is not None} + moved.extend(sorted(named_old.keys() ^ named_new.keys())) + spread_old = [keyword.value for keyword in old.keywords if keyword.arg is None] + spread_new = [keyword.value for keyword in new.keywords if keyword.arg is None] + return (_same_but_for_call_keywords(old.func, new.func, moved) + and _same_but_for_call_keywords(old.args, new.args, moved) + and _same_but_for_call_keywords(spread_old, spread_new, moved) + and all(_same_but_for_call_keywords(named_old[name], named_new[name], moved) + for name in named_old.keys() & named_new.keys())) + # ``_fields`` are a node's children and values; line and column numbers are not among them. + return all(_same_but_for_call_keywords(getattr(old, name, None), getattr(new, name, None), moved) for name in old._fields) + + def _check_mirror_against_legacy( module: TestModule, base_mirror: TestModule | None, diff --git a/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py b/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py index 902c2da0..ad9ae601 100644 --- a/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py +++ b/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py @@ -476,3 +476,52 @@ def test_main_refuses_a_line_added_to_the_debt_list(tmp_path: Path, capsys: pyte assert conventions.main(["--base", "main", "--project-root", str(root)]) == 1 captured = capsys.readouterr() assert captured.err == f"{DEBT_LIST}: tests/unit/devcapsule/test_other.py was added; the list loses lines and never gains one\n" + + + +# Rule 3's one allowance: a call in a legacy test may gain or lose keyword arguments. + +LEGACY_HEAD = "import pytest\npytestmark = pytest.mark.legacy\n" + + +def _legacy_breaches(root: Path, before: str, after: str) -> list[str]: + """The breaches of a legacy file whose only test function went from ``before`` to ``after``.""" + base = _module("tests/test_old.py", LEGACY_HEAD + before) + head = _module("tests/test_old.py", LEGACY_HEAD + after) + return conventions.check([head], {head.path: base}, root) + + +@pytest.mark.parametrize(("before", "after"), [ + ("def test_one():\n assert listing(document) == 1\n", + "def test_one():\n assert listing(document, host_environment=ENVIRONMENT) == 1\n"), + ("def test_one():\n assert plan(checkout, runtime_root=ROOT, caller_uid=0) == 1\n", + "def test_one():\n assert plan(checkout) == 1\n"), + ("def test_one():\n result = outer(inner(1), 2)\n assert result\n", + "def test_one():\n result = outer(\n inner(1, directory=lookup),\n 2,\n )\n assert result\n"), + ("class TestThing:\n def test_one(self):\n assert listing(document) == 1\n", + "class TestThing:\n def test_one(self):\n assert listing(document, directory=lookup) == 1\n"), +]) +def test_a_legacy_test_may_follow_a_signature_by_its_calls_keyword_arguments(tmp_path: Path, before: str, after: str) -> None: + """A legacy test whose calls gained a keyword argument, lost some, gained one in a nested call laid out + anew, or gained one inside a test class, is no breach.""" + assert _legacy_breaches(tmp_path, before, after) == [] + + +@pytest.mark.parametrize(("before", "after"), [ + ("def test_one():\n assert listing(document) == 1\n", "def test_one():\n assert listing(other, host_environment=E) == 1\n"), + ("def test_one():\n assert listing(document, home=HOME) == 1\n", "def test_one():\n assert listing(document, home=OTHER, directory=d) == 1\n"), + ("def test_one():\n assert listing(document) == 1\n", "def test_one():\n assert listing(document, directory=d) == 2\n"), + ("def test_one():\n assert listing(document) == 1\n", "def test_one():\n setup()\n assert listing(document, directory=d) == 1\n"), + ("def test_one():\n assert listing(document, **options) == 1\n", "def test_one():\n assert listing(document, **others) == 1\n"), + ("def test_one():\n assert listing(document) == 1\n", "def test_one():\n assert listing(\n document,\n ) == 1 # reworded\n"), + ("@pytest.mark.parametrize('x', [1])\ndef test_one(x):\n assert listing(x) == 1\n", + "@pytest.mark.parametrize('x', [1], ids=['one'])\ndef test_one(x):\n assert listing(x, directory=d) == 1\n"), + ("def test_one(tmp_path):\n assert listing(tmp_path) == 1\n", "def test_one(tmp_path, capsys):\n assert listing(tmp_path, directory=d) == 1\n"), +]) +def test_any_other_change_to_a_legacy_test_is_still_a_breach(tmp_path: Path, before: str, after: str) -> None: + """A legacy test is still refused when, beside or without a keyword argument that moved, a positional + argument changed, a kept keyword's value changed, an expected value changed, a statement was added, a ``**`` + argument changed, only the layout and a comment changed, a decorator changed, or the test's own parameters + changed.""" + breaches = _legacy_breaches(tmp_path, before, after) + assert len(breaches) == 1 and "changed in a legacy file" in breaches[0] diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index f5277a22..3957b07a 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -14,7 +14,9 @@ gate's check; its summary line counts the files still marked `legacy`. The flat files under `tests/` are those legacy files: they are never edited in place or shrunk one function at a time, and touching one, or adding, changing or deleting a test in a `tests/unit/` file of the same name, -retires the entire legacy file into the mirror. +retires the entire legacy file into the mirror. One change to a legacy test +is let through: a call that gains or loses keyword arguments, to follow a +function whose signature changed in the same pull request. *Host Inputs* in the same file binds new and changed tests further: only an entry layer reads the host, the modules below it take what it read as From 31f6d35230b7046833f5199d552453a25e738b4d Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:51:54 +0000 Subject: [PATCH 27/75] Tests: the IDE-override legacy file names its own home, and passes inside a capsule The file's home fixture sets DEVCAPSULE_CONFIG_HOME under the test's directory. A home that is only implied, with no settings of its own, reads the launcher's mounted settings inside a capsule; a named home does not. No test function and no product code changed. Evidence: all 33 cases of the file pass in the owner's capsule, where two failed; nox -s tests ends with 15 failed, the standing ones of the other five files, and 3059 passed. Co-Authored-By: Claude --- devcapsule-src/tests/test_ide_requirement_override.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/devcapsule-src/tests/test_ide_requirement_override.py b/devcapsule-src/tests/test_ide_requirement_override.py index 44c6393e..754bd2f6 100644 --- a/devcapsule-src/tests/test_ide_requirement_override.py +++ b/devcapsule-src/tests/test_ide_requirement_override.py @@ -49,6 +49,10 @@ def shared_bytes(root: Path) -> dict[str, bytes]: def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME"): monkeypatch.setenv(key, str(tmp_path / key.lower())) + # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its + # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the + # developer accepted there answers the consents these tests expect to be pending. + monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) return tmp_path From 75eff35fc137af931b3b9d544bfe822a8ee72284 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:51:54 +0000 Subject: [PATCH 28/75] Maintenance status: option 2, and the first legacy file green in the capsule Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 6f13a125..24be4995 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -104,6 +104,28 @@ Left out, this process and this machine are asked, as before. The launch passes them from the `Host`. The rule's text is not amended; each default names the ruling in its docstring. +**The owner's second ruling, 2026-11-12: option 2 as well.** Rule 5 of +*Unit Tests* now lets a call in a legacy test gain or lose keyword +arguments when the function's signature changes in the same pull request, +and nothing else. The checker holds the form: it compares the two versions +of the test as syntax and accepts a difference only in which keyword +arguments calls in the body name; a change of layout alone is still +refused. That the signature changed is the reviewer's to see. The optional +arguments of option 3 stay, and rule 2 of *Host Inputs* names the two +functions that keep them. No legacy call was changed under the allowance +yet. + +**`tests/test_ide_requirement_override.py` passes in the capsule.** Its own +`home` fixture now names the home, `DEVCAPSULE_CONFIG_HOME` under the +test's directory. A named home is the product's own way to say that a home +is the whole truth, so the fallback to the mounted settings does not apply. +No test function changed and no product code. All 33 cases pass; the +capsule's standing failures are 15. The earlier trial of the same variable +in the suite's shared fixture broke 31 tests that assert the XDG layout; +none of them is in this file. By that trial's log, the same line in the +other five files would turn 14 of the 15 green; one test of +`tests/test_run_flow.py` asserts the layout. + **`tests/test_ide_requirement_override.py`, ordered retired whole. It is not yet.** Of its 26 test functions, 12 now have a form that needs no file, no home and no patch: 10 in `test_launch_review.py`, 1 as three tests in the @@ -126,8 +148,7 @@ product, because each reaches something the code takes from a global: 5. One tests `realize_environment`, whose mirror file has a legacy twin of 9 tests; adding a test there retires that twin too. -Until then rule 5 keeps the legacy file whole, the 12 tests stand twice, and -2 of the capsule's 17 failures stay. +Until then rule 5 keeps the legacy file whole and the 12 tests stand twice. **Differences in behaviour.** Two orders of refusal: a checkout that cannot be given a free record name is now refused before a wrong IDE is, and the From 8542c41e3325ca0c80a3b84bdb8139f3daf3f966 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 13:52:08 +0000 Subject: [PATCH 29/75] Maintenance status: the definition stamp after rule 5's allowance Written by devcapsule0 workflow publish, coordination 65aa11f0d72f. Co-Authored-By: Claude --- engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 24be4995..96172170 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -6,7 +6,7 @@ Start date: 2026-09-18 State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; a first slice of the owner's read-then-decide direction on `ws-maintenance/launch-phases`, with the launch's decisions testable from values and the six legacy files of the 17 still to retire -Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@4e9a93c9f73a +Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@e84d2678942b Integration target: `main` From e56dab065d627ec0956e270287ef26fec3219165 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 14:41:43 +0000 Subject: [PATCH 30/75] Launch: the home's settings can be handed in; four legacy tests say what their home holds Owner direction of 2026-11-12: a test fixes its precondition by constructing the configuration in memory, not through the environment. - derivation.py: load_state takes the home's settings document as home and then reads no settings file. An empty document is a home with no settings file; any other is admitted as a file is. The state keeps its own copy. - _run_flow.py: prepare_launch and read_launch_state pass it on. - tests/test_run_flow.py: the four tests that fail inside a capsule pass home={} on their five calls, under the allowance of Unit Tests rule 5. Nothing else in them changed; the checker accepts it. - tests/unit/devcapsule/configuration/test_derivation.py, new: six tests of load_state. No command passes home yet; the owner allowed the parameter for the legacy tests. Evidence: the file's 48 cases pass in the owner's capsule, where 8 failed; nox -s tests ends with 7 failed, in four other files, and 3073 passed; nox -s typecheck passes over 346 files. Co-Authored-By: Claude --- .../devcapsule/commands/_run_flow.py | 14 ++- .../devcapsule/configuration/derivation.py | 19 +++- devcapsule-src/tests/test_run_flow.py | 10 +- .../configuration/test_derivation.py | 105 ++++++++++++++++++ 4 files changed, 134 insertions(+), 14 deletions(-) create mode 100644 devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py diff --git a/devcapsule-src/devcapsule/commands/_run_flow.py b/devcapsule-src/devcapsule/commands/_run_flow.py index f98f2ba5..72a6b3f8 100644 --- a/devcapsule-src/devcapsule/commands/_run_flow.py +++ b/devcapsule-src/devcapsule/commands/_run_flow.py @@ -27,7 +27,7 @@ import getpass from pathlib import Path import sys -from typing import Any, Callable, TextIO +from typing import Any, Callable, Mapping, TextIO from devcapsule.commands._launch_review import ( LaunchReview, Prepared, RunFlags, capability, channel_for, refuse_contradictory_flags, render_pending, @@ -57,17 +57,20 @@ def prepare_launch( output_stream: TextIO | None = None, print_only: bool = False, check_display: bool = True, + home: Mapping[str, Any] | None = None, ) -> Prepared: """Prepare a launch in three phases: read, decide in memory, write. ``print_only`` never asks or writes. Without a terminal, an unanswered blocking decision raises :class:`DecisionPending` before any write. + ``home`` is the home's settings document when the caller holds it; left + out, phase 1 reads it (see ``load_state``). """ # A command line that contradicts itself is refused before anything is read. refuse_contradictory_flags(flags) # Phase 1, read: the project, the home and the checkout's record, and what the terminal is. - state = read_launch_state(start) + state = read_launch_state(start, home=home) interactive = sys.stdin.isatty() if interactive is None else interactive reader = input_stream.readline if input_stream is not None else lambda: sys.stdin.readline() output = output_stream if output_stream is not None else sys.stdout @@ -87,15 +90,16 @@ def ask_at_terminal( return review.prepared() if print_only else save_launch(review) -def read_launch_state(start: Path) -> CheckoutState: +def read_launch_state(start: Path, *, home: Mapping[str, Any] | None = None) -> CheckoutState: """Phase 1 of a launch's preparation: read the project at ``start``, the home and the checkout's record. A checkout that has no record yet is given the path its record will have, which can mean looking for a free name among the project's checkouts. - Nothing is written. + Nothing is written. ``home`` is the home's settings document when the + caller holds it; left out, it is read. """ root, manifest = manifest_for(start) - state = load_state(root, manifest) + state = load_state(root, manifest, home=home) register_checkout(state, write=False) return state diff --git a/devcapsule-src/devcapsule/configuration/derivation.py b/devcapsule-src/devcapsule/configuration/derivation.py index 7a121a2e..fb2c32c8 100644 --- a/devcapsule-src/devcapsule/configuration/derivation.py +++ b/devcapsule-src/devcapsule/configuration/derivation.py @@ -59,7 +59,7 @@ find_checkout_record, load_checkout, load_toml, - load_settings, config_root, + load_settings, config_root, validate_settings, named_checkout_record_paths, recommendation_lock_for, resolved_record_path, @@ -269,17 +269,28 @@ def local_image(reference: str) -> ImageDetails: environment=dict(os.environ), directory=host_directory) -def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: +def load_state(root: Path, manifest: dict[str, Any], *, home: Mapping[str, Any] | None = None) -> CheckoutState: """Read one checkout's documents and surroundings into memory. Nothing is written. This is the reading half of every command that works on a checkout: the platform and its committed lock from the project, the settings from the home, the checkout's record or the path it would get, the environment saved with its Docker arguments, and the console's deferred requests. + + ``home`` is the home's settings document, for a caller that holds it + already; the home's file is then not read. An empty document is a home + with no settings file. Any other is admitted as a settings file is. + Owner ruling of 2026-11-12: legacy tests of the launch pass it, to say + what their home has accepted. No command passes it yet. """ platform = project_platform(root) lock_path, shared_lock = recommendation_lock_for(root, manifest) - home = load_settings() + if home is None: + settings = load_settings() + else: + settings = deepcopy(dict(home)) + if settings: + validate_settings(settings, config_root() / "settings.toml") record = find_checkout_record(manifest, root) input_path: Path | None = record if record is not None: @@ -301,7 +312,7 @@ def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: saved_environment = {} return CheckoutState( root=root, manifest=manifest, platform=platform, lock_path=lock_path, shared_lock=shared_lock, - home=home, home_path=config_root(), host=_this_host(), input_path=input_path, registered=record is not None, + home=settings, home_path=config_root(), host=_this_host(), input_path=input_path, registered=record is not None, checkout=checkout, saved_environment=saved_environment, deferred=tuple(deferred_rows(input_path, root)), ) diff --git a/devcapsule-src/tests/test_run_flow.py b/devcapsule-src/tests/test_run_flow.py index 7d63b9d1..4df25891 100644 --- a/devcapsule-src/tests/test_run_flow.py +++ b/devcapsule-src/tests/test_run_flow.py @@ -92,10 +92,10 @@ def test_a_second_checkout_is_registered_under_its_directory_name(project: Path, for name in ("devcapsule.toml", "devcapsule.linux-amd64.lock"): (second / ".devcapsule" / name).write_bytes((project / ".devcapsule" / name).read_bytes()) with pytest.raises(DecisionPending): # its own record: no IDE; the base's channel is the home's question - prepare_launch(second, RunFlags(), interactive=False) + prepare_launch(second, RunFlags(), interactive=False, home={}) prompts = io.StringIO() prepared = prepare_launch(second, RunFlags(ide="python-ide", authorize=()), interactive=True, - input_stream=io.StringIO("y\n"), output_stream=prompts) + input_stream=io.StringIO("y\n"), output_stream=prompts, home={}) assert "Accept for this DevCapsule home?" in prompts.getvalue() assert load_toml(settings_path())["trust"]["channels"]["devcapsule-base"]["vendor"] names = {item.checkout_name: item.checkout_path for item in registered_checkouts()} @@ -111,7 +111,7 @@ def test_interactive_questions_record_answers_where_the_config_family_would(proj prompts = io.StringIO() # In listing order: IDE by number; network: once; docker-daemon: deny; the base's channel: yes; env value. answers = io.StringIO("3\no\nd\ny\ndb.example.org\n") - prepared = prepare_launch(project, RunFlags(), interactive=True, input_stream=answers, output_stream=prompts) + prepared = prepare_launch(project, RunFlags(), interactive=True, input_stream=answers, output_stream=prompts, home={}) transcript = prompts.getvalue() assert "Choose one:" in transcript and "3. frontend-ide" in transcript assert "removes network namespace isolation" in transcript @@ -194,7 +194,7 @@ def test_save_with_pending_consent_writes_nothing(project: Path, tmp_path: Path, with pytest.raises(DecisionPending, match='trust devcapsule-base'): prepare_launch(root, RunFlags(ide='python-ide', memory='6g', environment=('PRIVATE=value',), authorize=(('network', 'host'),), save=True), - interactive=False, print_only=print_only) + interactive=False, print_only=print_only, home={}) assert snapshot(tmp_path) == before @@ -204,7 +204,7 @@ def test_partial_terminal_review_saves_no_answers(project: Path, tmp_path: Path, before = snapshot(tmp_path) with pytest.raises(DecisionPending): prepare_launch(second, RunFlags(memory='6g', save=True), interactive=True, - input_stream=io.StringIO(answers), output_stream=io.StringIO()) + input_stream=io.StringIO(answers), output_stream=io.StringIO(), home={}) assert snapshot(tmp_path) == before diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py new file mode 100644 index 00000000..62b9f680 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py @@ -0,0 +1,105 @@ +"""Unit tests of ``devcapsule/configuration/derivation.py``: reading a checkout into memory. + +Each test writes its project under ``tmp_path``: a manifest and the lock the +product derives from it. The home is the private one the suite gives every +test; a test that needs a settings file there writes it. +""" +from __future__ import annotations + +from pathlib import Path +from typing import Any + +import pytest + +from devcapsule.configuration.capabilities import CapabilityPolicy +from devcapsule.configuration.capability_selection import generate_lock +from devcapsule.configuration.derivation import load_state +from devcapsule.configuration.file_formats import ProjectConfigurationError, render_toml +from devcapsule.configuration.storage import settings_path +from devcapsule.platforms import Platform +from devcapsule.resolution_matrix import MATRICES + +MANIFEST: dict[str, Any] = { + "devcapsule-schema-version": 2, + "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, + "capabilities": {"required": ["python"]}, +} + +ADMITTED_BY_ANY_LAUNCHER = {"devcapsule-settings-schema-version": 1, "minimum-devcapsule": "0.1.0"} +"""The two header fields of a settings document that every launcher release admits.""" + + +def project_in(directory: Path) -> Path: + """A project directory with ``MANIFEST`` and its linux-amd64 lock, and no checkout record anywhere.""" + root = directory / "order" + (root / ".devcapsule").mkdir(parents=True) + (root / ".devcapsule" / "devcapsule.toml").write_text(render_toml(MANIFEST), encoding="utf-8") + lock = generate_lock(CapabilityPolicy.read(MANIFEST), MATRICES[Platform.LINUX_AMD64]) + (root / ".devcapsule" / "devcapsule.linux-amd64.lock").write_text(render_toml(lock), encoding="utf-8") + return root + + +def test_a_settings_document_handed_in_is_the_states_home(tmp_path: Path) -> None: + """``load_state`` given a settings document holds that document as the home and reads no settings file: + a file in the home that says otherwise is not consulted.""" + root = project_in(tmp_path) + settings_path().parent.mkdir(parents=True) + settings_path().write_text(render_toml({**ADMITTED_BY_ANY_LAUNCHER, "defaults": {"cpus": 4}}), encoding="utf-8") + handed_in = {**ADMITTED_BY_ANY_LAUNCHER, "defaults": {"cpus": 2}} + + state = load_state(root, MANIFEST, home=handed_in) + + assert state.home == handed_in + + +def test_the_state_keeps_its_own_copy_of_a_document_handed_in(tmp_path: Path) -> None: + """A change the caller makes to its document after the read does not reach the state's home.""" + handed_in: dict[str, Any] = {**ADMITTED_BY_ANY_LAUNCHER, "defaults": {"cpus": 2}} + state = load_state(project_in(tmp_path), MANIFEST, home=handed_in) + + handed_in["defaults"]["cpus"] = 8 + + assert state.home["defaults"] == {"cpus": 2} + + +def test_without_a_document_the_homes_settings_file_is_read(tmp_path: Path) -> None: + """``load_state`` given no settings document reads the home's settings file.""" + root = project_in(tmp_path) + settings_path().parent.mkdir(parents=True) + settings_path().write_text(render_toml({**ADMITTED_BY_ANY_LAUNCHER, "defaults": {"cpus": 4}}), encoding="utf-8") + + state = load_state(root, MANIFEST) + + assert state.home["defaults"] == {"cpus": 4} + + +def test_an_empty_document_is_a_home_that_has_no_settings(tmp_path: Path) -> None: + """An empty settings document is taken as it is, as a home without a settings file reads: no trust, no + default, and no header to admit.""" + state = load_state(project_in(tmp_path), MANIFEST, home={}) + + assert state.home == {} + + +def test_a_document_this_launcher_is_too_old_for_is_refused(tmp_path: Path) -> None: + """A settings document handed in is admitted as a file is: one that requires a later launcher is refused, + naming the release it requires.""" + too_new = {"devcapsule-settings-schema-version": 1, "minimum-devcapsule": "9999.0.0"} + + with pytest.raises(ProjectConfigurationError, match="requires DevCapsule 9999.0.0"): + load_state(project_in(tmp_path), MANIFEST, home=too_new) + + +def test_an_unregistered_checkout_is_read_with_the_record_it_would_get(tmp_path: Path) -> None: + """A project with no checkout record is read as unregistered, with the empty record of its own identity + and the path of the default record in the home.""" + root = project_in(tmp_path) + + state = load_state(root, MANIFEST, home={}) + + assert state.registered is False + assert state.checkout["project"] == {"creator": "mailto:owner@example.test", "slug": "order"} + assert state.input_path is not None and state.input_path.name == "devcapsule.checkout.toml" + assert not state.input_path.exists() + assert state.platform is Platform.LINUX_AMD64 + assert state.shared_lock["platform"] == "linux-amd64" From 207bac95b5515f600c8f1d73e9d0325cd99023b3 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 14:41:43 +0000 Subject: [PATCH 31/75] Maintenance status: the run-flow file's eight failures fixed in memory Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 96172170..06fda57f 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -126,6 +126,31 @@ none of them is in this file. By that trial's log, the same line in the other five files would turn 14 of the 15 green; one test of `tests/test_run_flow.py` asserts the layout. +**`tests/test_run_flow.py`: its 8 failures fixed with the configuration in +memory, 2026-11-12.** The owner's correction of the fix above: a test says +what its home holds by constructing it, not through the environment. +`prepare_launch` takes the home's settings document as `home`, and passes +it through `read_launch_state` to `load_state`, which then does not read +the home's file. An empty document is a home with no settings file; any +other is admitted as a file is. The four failing tests pass `home={}` on +their five calls. This is the first use of rule 5's allowance, and the +checker accepts it. All 48 cases of the file pass in the capsule; the +standing failures are 7, in four files. Six new tests of `load_state` in +`tests/unit/devcapsule/configuration/test_derivation.py`. + +No command passes `home`: only tests do, which rule 2 of *Host Inputs* +forbids in general and the owner allowed here. The default, reading the +home, is still what the other 20 calls of the file run. Five planted +faults: two caught by the new mirror tests, one more after a test was +added, and two caught only by the four legacy tests inside a capsule. Those +two are the lines by which `prepare_launch` and `read_launch_state` pass +`home` on; on the hosted runner a home is empty either way, so the hosted +gate does not catch their loss. + +Of the 7 that remain, one calls `prepare_launch` and takes the same fix +(`tests/test_trust.py`); five go through `cli.main` and one calls +`write_settings`, which reads the mounted settings itself before it merges. + **`tests/test_ide_requirement_override.py`, ordered retired whole. It is not yet.** Of its 26 test functions, 12 now have a form that needs no file, no home and no patch: 10 in `test_launch_review.py`, 1 as three tests in the From 867265ad5275c9dca1120e3a8e382e7a2cc20b7b Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 14:54:11 +0000 Subject: [PATCH 32/75] Settings: a write can be given the document it merges onto; two trust tests say what their home holds - storage.py: write_settings takes current, the home's settings as the caller holds them. Left out, they are read at the write, as before. - _run_flow.py: accept_channel takes the home's settings as home and writes the acceptance onto that document. - tests/test_trust.py: the test of a staged terminal acceptance passes home={} to prepare_launch, and the test of the atomic write passes it to the file's accept helper, under the allowance of Unit Tests rule 5. The helper passes it on. - tests/unit/devcapsule/configuration/test_storage.py: three tests of the writer's new argument. Evidence: nox -s tests in the owner's capsule ends with 5 failed, 3078 passed; all five drive the command line. nox -s typecheck passes. Co-Authored-By: Claude --- .../devcapsule/commands/_run_flow.py | 15 ++++-- .../devcapsule/configuration/storage.py | 14 +++++- devcapsule-src/tests/test_trust.py | 14 ++++-- .../devcapsule/configuration/test_storage.py | 49 +++++++++++++++++-- 4 files changed, 78 insertions(+), 14 deletions(-) diff --git a/devcapsule-src/devcapsule/commands/_run_flow.py b/devcapsule-src/devcapsule/commands/_run_flow.py index 72a6b3f8..eb1bcbb8 100644 --- a/devcapsule-src/devcapsule/commands/_run_flow.py +++ b/devcapsule-src/devcapsule/commands/_run_flow.py @@ -180,11 +180,18 @@ def project_channel(root: Path, manifest: dict[str, Any], channel_id: str) -> Ch return channel_for(state.composed_lock(), channel_id) -def accept_channel(root: Path, manifest: dict[str, Any], channel_id: str) -> Path: - """Record the user's acceptance of one channel for this home now; return the record's path.""" - from devcapsule.configuration.storage import load_trust +def accept_channel(root: Path, manifest: dict[str, Any], channel_id: str, *, + home: Mapping[str, Any] | None = None) -> Path: + """Record the user's acceptance of one channel for this home now; return the record's path. + + ``home`` is the home's settings document when the caller holds it: the + acceptance is added to its trust and written onto it. Left out, the + home's settings are read. + """ + from devcapsule.configuration.storage import load_settings channel = project_channel(root, manifest, channel_id) - return write_settings({"trust": HomeTrust.read(load_trust()).with_channel(channel).document()}) + settings = load_settings() if home is None else home + return write_settings({"trust": HomeTrust.read(settings).with_channel(channel).document()}, current=settings) def _settle( diff --git a/devcapsule-src/devcapsule/configuration/storage.py b/devcapsule-src/devcapsule/configuration/storage.py index da579179..48003c60 100644 --- a/devcapsule-src/devcapsule/configuration/storage.py +++ b/devcapsule-src/devcapsule/configuration/storage.py @@ -168,14 +168,24 @@ def load_trust(env: Mapping[str, str] | None = None) -> dict[str, Any]: return dict(table(load_settings(env), "trust")) -def write_settings(document: Mapping[str, Any], env: Mapping[str, str] | None = None) -> Path: +def write_settings(document: Mapping[str, Any], env: Mapping[str, str] | None = None, *, + current: Mapping[str, Any] | None = None) -> Path: """Merge changed tables, retain headers, and replace only changed content. Atomic replacement prevents partial reads. Concurrent updates of the same table use the last writer's value; this is not a transaction across launchers. + + ``current`` is the home's settings as the caller holds them, the document + the changed tables are merged onto; an empty one is a home with no + settings file. Left out, the settings are read here, at the moment of the + write. Inside a capsule that read is of the launcher's mounted settings + until the capsule's home has a file of its own, so a first write starts + from what the launcher's home holds. Owner ruling of 2026-11-12: a legacy + test passes ``current`` through ``accept_channel`` to say what its home + held; no command passes it. """ path = settings_path(env) - before = load_settings(env) + before = load_settings(env) if current is None else dict(current) after = {**before, **document} after.setdefault("devcapsule-settings-schema-version", 1) after.setdefault("minimum-devcapsule", launcher_release()) diff --git a/devcapsule-src/tests/test_trust.py b/devcapsule-src/tests/test_trust.py index b8911c81..85230ca6 100644 --- a/devcapsule-src/tests/test_trust.py +++ b/devcapsule-src/tests/test_trust.py @@ -41,11 +41,15 @@ def config(root: Path, *arguments: str) -> int: -def accept(root: Path, channel: str) -> int: - """Seed the project channel for tests of lock-specific acceptance.""" +def accept(root: Path, channel: str, home: dict | None = None) -> int: + """Seed the project channel for tests of lock-specific acceptance. + + ``home`` is the settings the test's home holds before the acceptance, for + a test that says so; left out, the home is read. + """ from devcapsule.commands._run_flow import accept_channel try: - accept_channel(root, manifest_for(root)[1], channel) + accept_channel(root, manifest_for(root)[1], channel, home=home) except ProjectConfigurationError as exc: print(str(exc), file=sys.stderr) return 2 @@ -259,7 +263,7 @@ def test_inspection_and_pending_trust_leave_all_files_unchanged(project: Path, t def test_trust_write_is_private_atomic_and_keeps_previous_record_on_failure(project: Path, monkeypatch) -> None: from devcapsule.configuration.storage import write_settings - assert accept(project, BASE_CHANNEL) == 0 + assert accept(project, BASE_CHANNEL, home={}) == 0 before = settings_path().read_bytes() original = Path.replace replacements = [] @@ -339,7 +343,7 @@ def test_terminal_acceptance_stays_staged_if_a_later_answer_is_missing(project: before = snapshot(tmp_path) output = io.StringIO() with pytest.raises(DecisionPending, match="nothing was written"): - prepare_launch(project, RunFlags(), interactive=True, input_stream=io.StringIO("y\n"), output_stream=output) + prepare_launch(project, RunFlags(), interactive=True, input_stream=io.StringIO("y\n"), output_stream=output, home={}) assert "Trust will be saved when all required answers are complete" in output.getvalue() assert "this DevCapsule home" in output.getvalue() assert snapshot(tmp_path) == before diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_storage.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_storage.py index 935cc6d3..4b4a1606 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_storage.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_storage.py @@ -1,5 +1,5 @@ -"""Unit tests of ``devcapsule/configuration/storage.py``: which capsule platform a project runs as on a host, and the -admission of a settings file by its minimum launcher version. +"""Unit tests of ``devcapsule/configuration/storage.py``: which capsule platform a project runs as on a host, the +admission of a settings file by its minimum launcher version, and the document a settings write merges onto. Each test writes its project's lock files under ``tmp_path`` and names its host with ``on_host``. """ @@ -12,7 +12,7 @@ from devcapsule import cli from devcapsule.configuration import storage from devcapsule.configuration.file_formats import ProjectConfigurationError -from devcapsule.configuration.storage import locked_platforms, project_platform +from devcapsule.configuration.storage import load_toml, locked_platforms, project_platform, settings_path, write_settings from devcapsule.platforms import Platform from tests.unit.devcapsule.test_platforms import on_host @@ -71,3 +71,46 @@ def test_minimum_refusal_precedes_content_and_command_diagnoses(tmp_path: Path, storage.write_settings({"defaults": {"cpus": 2}}) assert (path.read_bytes(), path.stat().st_mtime_ns) == before assert list(tmp_path.iterdir()) == [path] + + +def named_home(directory: Path) -> dict[str, str]: + """The environment of a process whose DevCapsule home is named: ``directory / "home"``, which does not exist yet.""" + return {"DEVCAPSULE_CONFIG_HOME": str(directory / "home"), "HOME": str(directory)} + + +def test_a_settings_write_merges_onto_the_document_it_is_given(tmp_path: Path) -> None: + """``write_settings`` given the home's current settings writes those with the changed table laid over them, + and does not read the home's file: a table that only the file holds is not in the result.""" + env = named_home(tmp_path) + write_settings({"defaults": {"cpus": 4}}, env) + held = {key: value for key, value in load_toml(settings_path(env)).items() if key != "defaults"} + + write_settings({"trust": {"channels": {}}}, env, current=held) + + assert load_toml(settings_path(env)) == {**held, "trust": {"channels": {}}} + + +def test_a_settings_write_onto_an_empty_document_starts_a_new_file(tmp_path: Path) -> None: + """Given an empty current document, the write creates the home's file with the changed table and the two + header fields a settings file carries.""" + env = named_home(tmp_path) + + path = write_settings({"defaults": {"cpus": 2}}, env, current={}) + + written = load_toml(path) + assert path == settings_path(env) + assert written["defaults"] == {"cpus": 2} + assert set(written) == {"defaults", "devcapsule-settings-schema-version", "minimum-devcapsule"} + + +def test_a_settings_write_that_changes_nothing_of_the_given_document_writes_no_file(tmp_path: Path) -> None: + """When the changed table equals the one in the current document given, nothing is written, although the + home has no file.""" + env = named_home(tmp_path) + write_settings({"defaults": {"cpus": 2}}, env) + held = load_toml(settings_path(env)) + settings_path(env).unlink() + + write_settings({"defaults": {"cpus": 2}}, env, current=held) + + assert not settings_path(env).exists() From b229d1fef84014b6463da578d212ff8e28ba59a4 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 14:54:11 +0000 Subject: [PATCH 33/75] Maintenance status: two trust tests fixed in memory; five failures left, all through the command line Co-Authored-By: Claude --- .../2026-09-18-maintenance/CURRENT-STATUS.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 06fda57f..3e88f25d 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -151,6 +151,30 @@ Of the 7 that remain, one calls `prepare_launch` and takes the same fix (`tests/test_trust.py`); five go through `cli.main` and one calls `write_settings`, which reads the mounted settings itself before it merges. +**`tests/test_trust.py`: two of its three failures fixed in memory, +2026-11-12.** One test calls `prepare_launch` and now passes `home={}`. The +other tests the atomic write of the settings file and first accepts a +channel through the file's helper `accept`; inside a capsule the launcher's +mounted settings already hold that channel, so nothing was written and the +test found no file. `accept_channel` now takes the home's settings as +`home`, and `write_settings` takes the document it merges onto as +`current`; the test passes `home={}` to the helper. Three new tests of +`write_settings` in the storage mirror. Three planted faults: the mirror +tests catch the writer ignoring `current`; the legacy test catches +`accept_channel` ignoring `home`, inside a capsule only; nothing catches +`accept_channel` not passing `current` on, because the file it then writes +differs only in tables the test does not read. `accept_channel` has no +caller in the product; it is the tests' helper. + +One finding for the owner in the product: `write_settings` reads the +settings it merges onto, and inside a capsule with no settings file of its +own that read is of the launcher's mounted settings. So the first write in +a capsule copies the launcher's home into the capsule's own file, with the +one table changed. Its docstring now says so. + +The standing failures are 5, in four files, and all five drive `cli.main`. +No call in them can be handed a value. + **`tests/test_ide_requirement_override.py`, ordered retired whole. It is not yet.** Of its 26 test functions, 12 now have a form that needs no file, no home and no patch: 10 in `test_launch_review.py`, 1 as three tests in the From 1c7cac7dff0990ab0cfa7702b84ad61d8c9c012f Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 15:22:19 +0000 Subject: [PATCH 34/75] Tests: five legacy files name their own home; the unit session passes inside a capsule The five tests that still failed inside the owner's capsule drive the command line, where no call can be handed a value. On the owner's word the fixtures of their files set DEVCAPSULE_CONFIG_HOME under the test's directory: project in tests/test_trust.py, tests/test_capability_policy.py and tests/test_owner_commands.py, and a new autouse fixture in tests/configuration/test_contract.py. The project fixture of tests/test_capability_minimums.py does the same, for the test that downloaded vendor artifacts. No test function changed. Evidence: nox -s typecheck tests passes inside the owner's capsule, exit 0: 3083 passed, 10 expected to fail, 11 unexpectedly passed, 175 s; no unit test tried the network; 0 convention breaches. Co-Authored-By: Claude --- devcapsule-src/tests/configuration/test_contract.py | 11 +++++++++++ devcapsule-src/tests/test_capability_minimums.py | 4 ++++ devcapsule-src/tests/test_capability_policy.py | 4 ++++ devcapsule-src/tests/test_owner_commands.py | 4 ++++ devcapsule-src/tests/test_trust.py | 4 ++++ 5 files changed, 27 insertions(+) diff --git a/devcapsule-src/tests/configuration/test_contract.py b/devcapsule-src/tests/configuration/test_contract.py index 74bc78c8..25d394f4 100644 --- a/devcapsule-src/tests/configuration/test_contract.py +++ b/devcapsule-src/tests/configuration/test_contract.py @@ -47,6 +47,17 @@ pytestmark = pytest.mark.legacy +@pytest.fixture(autouse=True) +def named_home(tmp_path, monkeypatch): + """Name each test's home, before the imported ``checkout`` fixture places the record in it. + + A home that is only implied by HOME and the XDG variables, with no settings of its own yet, reads the + launcher's mounted settings when the suite runs inside a capsule, and then what the developer accepted + there answers the consents these tests expect to be pending. + """ + monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) + + def declare_values(project, extra=''): path = project / '.devcapsule/devcapsule.toml' path.write_text(path.read_text() + ''' diff --git a/devcapsule-src/tests/test_capability_minimums.py b/devcapsule-src/tests/test_capability_minimums.py index 189a1a5e..8fecd202 100644 --- a/devcapsule-src/tests/test_capability_minimums.py +++ b/devcapsule-src/tests/test_capability_minimums.py @@ -46,6 +46,10 @@ def snapshot(root: Path) -> dict[Path, bytes]: def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"): monkeypatch.setenv(key, str(tmp_path / key.lower())) + # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its + # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the + # developer accepted there answers the consents these tests expect to be pending. + monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" (root / ".devcapsule").mkdir(parents=True) return root diff --git a/devcapsule-src/tests/test_capability_policy.py b/devcapsule-src/tests/test_capability_policy.py index d5b21f4a..0934887e 100644 --- a/devcapsule-src/tests/test_capability_policy.py +++ b/devcapsule-src/tests/test_capability_policy.py @@ -38,6 +38,10 @@ def declaration(**capabilities: Any) -> dict[str, Any]: @pytest.fixture def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) + # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its + # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the + # developer accepted there answers the consents these tests expect to be pending. + monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" (root / ".devcapsule").mkdir(parents=True) manifest = declaration(need=["python", "python-ide"]) diff --git a/devcapsule-src/tests/test_owner_commands.py b/devcapsule-src/tests/test_owner_commands.py index a52d30e3..19dbd0c0 100644 --- a/devcapsule-src/tests/test_owner_commands.py +++ b/devcapsule-src/tests/test_owner_commands.py @@ -47,6 +47,10 @@ def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: """A project in the required form, created by init without an IDE.""" monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) monkeypatch.setenv("HOME", str(tmp_path / "home")) + # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its + # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the + # developer accepted there answers the consents these tests expect to be pending. + monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" root.mkdir() assert cli.main(["project", "--path", str(root), "init", "--require", "python", "--creator", "mailto:owner@example.test"]) == 0 diff --git a/devcapsule-src/tests/test_trust.py b/devcapsule-src/tests/test_trust.py index 85230ca6..6480d759 100644 --- a/devcapsule-src/tests/test_trust.py +++ b/devcapsule-src/tests/test_trust.py @@ -30,6 +30,10 @@ def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"): monkeypatch.setenv(key, str(tmp_path / key.lower())) + # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its + # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the + # developer accepted there answers the consents these tests expect to be pending. + monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" root.mkdir() assert cli.main(["project", "--path", str(root), "init", "--require", "node", "--creator", "mailto:owner@example.test"]) == 0 From be852264eb7de61f991ecf2c3eae56d89bb2f882 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 15:22:19 +0000 Subject: [PATCH 35/75] Records: the blocking bug is in fixing; the unit session is green in the capsule Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 31 ++++++++++++++++++- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 18 ++++++++++- 3 files changed, 48 insertions(+), 3 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 14fd3253..2ca55f12 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -1,5 +1,5 @@ --- -status: confirmed +status: fixing severity: blocking target: 0.3.1 owner: maintenance @@ -189,6 +189,35 @@ Not in this record: - A guard worth adding: one test that builds a mounted settings file with an accepted channel and asserts that a default test home does not see it. +## Progress, 2026-11-12 + +On `ws-maintenance/launch-phases`, pull request #29, not merged. The cause +stands: the shared fixture still gives a home that falls back to the mount. +What changed is that the tests which failed now say what their home is. + +- The 17 failing tests pass inside the owner's capsule. Seven, which call + `prepare_launch` or the file's `accept` helper, hand in the home's + settings as a value, `home={}`. `load_state`, `prepare_launch`, + `accept_channel` and `write_settings` take that value; left out, they + read the home as before. Ten, which drive the command line, get a named + home from their own file's fixture, `DEVCAPSULE_CONFIG_HOME` under the + test's directory, in five legacy files. +- The test that downloaded vendor artifacts uses a fixture of + `tests/test_capability_minimums.py`, which names its home too. It stops at + the consent it expects and opens no connection. The network guard of + `tests/conftest.py`, new in pull request #26, now fails any unit test that + tries. +- `nox -s tests` passes inside the owner's capsule: 3083 passed, 10 expected + to fail, 11 unexpectedly passed, in 175 seconds where it took 815. + +Against the close criteria: 1 holds for the owner's capsule as it is today. +2 and 3 do not. Fourteen marks of this cause remain; eleven of their tests +now pass. They are in mirror files whose legacy twins stand, so the gate +refuses a change to them until those twins are retired. 4 does not hold: +`private_user_directories` is unchanged, and a test that uses neither a +named home nor a handed-in one still reads the mount. The next channel the +developer accepts can turn other tests red. + ## Verification target and close criteria 1. `nox -s tests` passes inside a capsule whose mounted settings carry diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 5f504d71..dbe7fdf8 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | confirmed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; no fix started | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the shared fixture and 14 marks are still to do | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 3e88f25d..c0cd2670 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, no fix started; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; a first slice of the owner's read-then-decide direction on `ws-maintenance/launch-phases`, with the launch's decisions testable from values and the six legacy files of the 17 still to retire +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, in fixing: on pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, the shared fixture and 14 marks still to do; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; a first slice of the owner's read-then-decide direction on `ws-maintenance/launch-phases`, with the launch's decisions testable from values and the six legacy files of the 17 still to retire Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@e84d2678942b @@ -175,6 +175,22 @@ one table changed. Its docstring now says so. The standing failures are 5, in four files, and all five drive `cli.main`. No call in them can be handed a value. +**The last five, and the unit session green in the capsule, 2026-11-12.** +The five that remained drive `cli.main`, where no call can be handed a +value. On the owner's word their files' fixtures name the home, as the +IDE-override file's does: `project` in `tests/test_trust.py`, +`tests/test_capability_policy.py` and `tests/test_owner_commands.py`, and a +new autouse fixture in `tests/configuration/test_contract.py`, whose +`checkout` fixture is imported from another legacy file. For a test of the +command line the environment is input as `argv` is. One fixture beyond the +five: `project` in `tests/test_capability_minimums.py`, used by the test +that downloaded vendor artifacts; with it that test stops at its consent, +and the network guard no longer fails the session. `nox -s tests` passes +inside the owner's capsule for the first time since 2026-11-03: 3083 passed, +10 expected to fail, 11 unexpectedly passed, 175 seconds. The blocking bug's +record has a progress section and is `fixing`, not closed: the shared +fixture is unchanged and 14 marks remain. + **`tests/test_ide_requirement_override.py`, ordered retired whole. It is not yet.** Of its 26 test functions, 12 now have a form that needs no file, no home and no patch: 10 in `test_launch_review.py`, 1 as three tests in the From 550d356da16b5c1857c165056c612eef0b793699 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 15:22:42 +0000 Subject: [PATCH 36/75] Bug record: ten tests hand in their home, seven name it Co-Authored-By: Claude --- ...-unit-tests-read-the-capsules-mounted-launcher-settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 2ca55f12..2bf89245 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -195,11 +195,11 @@ On `ws-maintenance/launch-phases`, pull request #29, not merged. The cause stands: the shared fixture still gives a home that falls back to the mount. What changed is that the tests which failed now say what their home is. -- The 17 failing tests pass inside the owner's capsule. Seven, which call +- The 17 failing tests pass inside the owner's capsule. Ten, which call `prepare_launch` or the file's `accept` helper, hand in the home's settings as a value, `home={}`. `load_state`, `prepare_launch`, `accept_channel` and `write_settings` take that value; left out, they - read the home as before. Ten, which drive the command line, get a named + read the home as before. Seven, which drive the command line, get a named home from their own file's fixture, `DEVCAPSULE_CONFIG_HOME` under the test's directory, in five legacy files. - The test that downloaded vendor artifacts uses a fixture of From 55f953c7f0835205b9f5259a922af9313f0c3282 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 16:27:11 +0000 Subject: [PATCH 37/75] project run --print-command pulls, downloads and builds nothing Owner direction of 2026-11-12: whoever asks for the command to be printed did not ask for the environment to be brought to the machine. Until now --print-command prepared everything a launch prepares and stopped only before docker run. - materialization.py: ensure_materialized_surface takes fetch. False: an image that is here and needs nothing is returned; a missing image, or one whose boot configuration needs its rebuild, raises NotOnThisMachine, which names what a launch would download and build. - environment_realization.py: realize_environment takes fetch and passes it on. False: the base image is looked for locally and not pulled. - commands/project.py: --print-command asks for fetch=False, and ends with exit 2 and the launch command to run once when something is missing. The option's help says so. - docs/reference/cli.md and devcapsule-src/README.md: the same, where they said that printing may download and build. - tests/unit/devcapsule/test_materialization.py: three tests of the look without fetching. - tests/integration/test_print_command_cli.py, new: the built launcher with a stand-in where docker is; it asks only whether the base image is local. - tests/test_upgrade_recovery.py: the shared stand-in of the realization accepts the new keyword. No test function changed. Evidence: in the owner's capsule the real command on a project that was never launched ends in 0.4 s with exit 2, names the image and three artifacts, and downloads no file. Two planted faults in the wiring, each with the executable rebuilt, fail the integration test. nox -s typecheck tests passes; the integration tests that need no Docker: 124 passed, 3 skipped, 1 failed, the standing one of test_pex_runtime.py. Co-Authored-By: Claude --- devcapsule-src/README.md | 6 +- devcapsule-src/devcapsule/commands/project.py | 20 ++++- .../devcapsule/environment_realization.py | 25 +++++- devcapsule-src/devcapsule/materialization.py | 34 ++++++++ .../integration/test_print_command_cli.py | 83 +++++++++++++++++++ devcapsule-src/tests/test_upgrade_recovery.py | 3 +- .../unit/devcapsule/test_materialization.py | 76 +++++++++++++++++ docs/reference/cli.md | 9 +- 8 files changed, 243 insertions(+), 13 deletions(-) create mode 100644 devcapsule-src/tests/integration/test_print_command_cli.py diff --git a/devcapsule-src/README.md b/devcapsule-src/README.md index b6138857..a72fb7c6 100644 --- a/devcapsule-src/README.md +++ b/devcapsule-src/README.md @@ -1236,8 +1236,10 @@ This prepares the currently selected environment through ordinary configuration and authorization checks, then prints the shell-quoted Docker command, masking inline environment values from saved or one-off extra options. A redacted command is a preview; use `project run` to supply the actual saved values. -It may acquire/build the image and prepare state; it does not launch the project -container, open a desktop, check/select component updates or record successful use. +It pulls, downloads and builds nothing: when the environment is not on this +machine yet, it exits 2 and names what a launch would fetch. It does not launch +the project container, open a desktop, check/select component updates or record +successful use. Preparation messages go to stderr, keeping stdout suitable for a file or editor. Run-once configuration choices and accepted Docker passthrough options still apply. diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 01994c3f..cf383610 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -81,7 +81,7 @@ build_node_registry, ) from devcapsule.environment_realization import realize_environment, required_local_image, omit_unavailable_optional -from devcapsule.materialization import ArtifactUnavailable +from devcapsule.materialization import ArtifactUnavailable, NotOnThisMachine from devcapsule.display_client import select_display_transport from devcapsule.images.contract import WebConsoleAvailability, web_console_availability from devcapsule.materialization import ImageDetails, validate_base_image @@ -2180,7 +2180,9 @@ def configure(cls, parser: argparse.ArgumentParser) -> None: parser.add_argument("--no-update-check", action="store_true", help="Skip the daily interactive distribution refresh; cached critical notices still allow a decision.") parser.add_argument("--print-command", action="store_true", - help="Prepare and print the Docker command without launching; inline extra environment values are redacted and comments identify transient dependencies.") + help="Print the launch's Docker command without launching. Nothing is pulled, downloaded, built or " + "saved: an environment that is not on this machine yet is named, not fetched. Inline extra " + "environment values are redacted and comments identify transient dependencies.") parser.add_argument("--force", action="store_true", help="Launch with the IDE given by --ide although the project requires another IDE: this launch only, " "warned and recorded as a departure from the project's contract; the requirement and the saved IDE " @@ -2302,13 +2304,23 @@ def prepare_display(base: ImageDetails) -> None: if isinstance(lock.get("base"), dict) and isinstance(lock.get("materialization"), dict): while True: try: - if command_report is not None and flags.trust: + if command_report is not None: + # Printing the command brings nothing to this machine: the environment is looked + # for here, and what a launch would pull, download or build is named instead. from devcapsule.configuration.trust import HomeTrust + # A channel accepted with --trust for this printing is in the review's home, not on disk. + staged_trust = HomeTrust.read(prepared.home) if flags.trust else None realized = realize_environment(selected, report=print, prepare_base=prepare_display, - trust=HomeTrust.read(prepared.home)) + trust=staged_trust, fetch=False) else: realized = realize_environment(selected, report=print, prepare_base=prepare_display) break + except NotOnThisMachine as missing: + launch = shlex.join(["devcapsule", "project", "--path", str(root), "run"]) + raise CliError( + f"{missing} --print-command prints the command of an environment that is already here. " + f"Launch once with {launch}, then print." + ) from missing except ArtifactUnavailable as exc: smaller = omit_unavailable_optional(selected, exc.url) if smaller is None: diff --git a/devcapsule-src/devcapsule/environment_realization.py b/devcapsule-src/devcapsule/environment_realization.py index e92ec9be..f2205dcd 100644 --- a/devcapsule-src/devcapsule/environment_realization.py +++ b/devcapsule-src/devcapsule/environment_realization.py @@ -17,6 +17,7 @@ from devcapsule.materialization import ( ImageDetails, LockedEnvironment, + NotOnThisMachine, cache_root, ensure_materialized_surface, parse_locked_environment, @@ -66,8 +67,15 @@ def realize_environment( report: Callable[[str], None] | None = None, prepare_base: Callable[[ImageDetails], None] | None = None, trust: HomeTrust | None = None, + fetch: bool = True, ) -> RealizedEnvironment: - """Strictly reuse or materialize the canonical image for one resolved project.""" + """Strictly reuse or materialize the canonical image for one resolved project. + + With ``fetch`` false the environment is only looked for on this machine: + the base image is not pulled, no artifact is downloaded and no image is + built. What is missing raises :class:`NotOnThisMachine`, which says what a + launch would bring. ``project run --print-command`` asks for that. + """ from devcapsule.configuration.capabilities import CapabilityPolicy if (base_override is not None and "capabilities" in selected.manifest @@ -112,14 +120,16 @@ def realize_environment( selection.local_image_identity if local_authorization else locked.base_identity ) + inspect = inspect_image or optional_local_image + require = require_image or required_local_image if obtain_image is not None: obtain = obtain_image + elif not fetch: + obtain = lambda reference: _image_on_this_machine(reference, inspect) elif local_authorization: obtain = required_local_image else: obtain = lambda reference: ensure_local_image(reference, capsule_platform) - inspect = inspect_image or optional_local_image - require = require_image or required_local_image base = obtain(base_reference) validate_base_image( base, @@ -153,6 +163,7 @@ def realize_environment( "runtime_command": RuntimeCommand(runtime.get("devcapsule-command", RuntimeCommand.STANDARD)), "report": report, "list_formations": lambda: component_formations(locked.component_id), + "fetch": fetch, } ) canonical, created = materialize_environment( @@ -181,6 +192,14 @@ def realize_environment( ) +def _image_on_this_machine(reference: str, inspect: ImageLookup) -> ImageDetails: + """The base image at ``reference`` when the local daemon has it; no pull.""" + image = inspect(reference) + if image is None: + raise NotOnThisMachine(f"The base image {reference} is not on this machine. A launch pulls it; nothing was pulled now.") + return image + + def ensure_local_image(reference: str, platform: Platform) -> ImageDetails: """The local image at ``reference``, pulled for the lock's ``platform`` when absent.""" try: diff --git a/devcapsule-src/devcapsule/materialization.py b/devcapsule-src/devcapsule/materialization.py index 3f5ca616..dcf42391 100644 --- a/devcapsule-src/devcapsule/materialization.py +++ b/devcapsule-src/devcapsule/materialization.py @@ -74,6 +74,7 @@ "MATERIALIZATION_RECIPE_ID", "MATERIALIZATION_RECIPE_VERSION", "NPM_CACHE_PATH", + "NotOnThisMachine", "NPM_INSTALL_OPTIONS", "NpmProject", "RUNTIME_COMMAND_PATH", @@ -324,6 +325,16 @@ def __init__(self, url: str, reason: object) -> None: super().__init__(f"Cannot download locked artifact {url!r}: {reason}") +class NotOnThisMachine(CliError): + """A launch would have to pull, download or build something, and the caller asked for nothing to be fetched. + + The message names what is missing and what a launch does about it. It is + how ``project run --print-command`` ends on a machine that has not yet + launched the environment: it prints the command of what is here, and + brings nothing here. + """ + + def acquire_artifact(spec: ArtifactSpec, root: Path) -> Acquisition: algorithm = "sha256" expected = spec.sha256 @@ -773,7 +784,18 @@ def ensure_materialized_surface( list_formations: Callable[[], tuple[ImageDetails, ...]] | None = None, runtime_pex: Path | None = None, runtime_command: RuntimeCommand = RuntimeCommand.STANDARD, + fetch: bool = True, ) -> tuple[str, bool]: + """The canonical image of one environment, reused when it is on this machine and built when it is not. + + Returns the image's name and whether this call built it. Building + downloads the component's artifacts into ``cache_root`` and runs + ``build``. + + With ``fetch`` false nothing is downloaded and nothing is built: an image + that is here and needs nothing is returned, and anything else raises + :class:`NotOnThisMachine`, naming what a launch would do. + """ profile = surface_profile(component_id) descriptor = formation_descriptor( platform=platform, @@ -796,6 +818,11 @@ def ensure_materialized_surface( drift = runtime_config_drift(existing, descriptor) if not drift: return image, False + if not fetch: + raise NotOnThisMachine( + f"The {component_id} environment {image} needs its boot configuration rebuilt " + f"({'; '.join(drift)}). A launch rebuilds it; nothing was rebuilt now." + ) # The record is right and the image content is right; only the # boot configuration predates enforcement. Repair in place with a # configuration-only build (owner ruling 2026-09-05) instead of @@ -820,6 +847,13 @@ def ensure_materialized_surface( verify_materialized_image(repaired, descriptor=descriptor, canonical_name=image) return image, False + if not fetch: + downloads = [artifact.url, *(item.url for item in ancillary_artifacts)] + raise NotOnThisMachine( + f"The {component_id} environment {image} is not built on this machine. A launch downloads " + f"{len(downloads)} artifact{'s' if len(downloads) != 1 else ''} ({', '.join(downloads)}) " + "and builds it; nothing was downloaded or built now." + ) _explain_materialization(say, descriptor, image, component_id, list_formations) acquisition = acquire_artifact(artifact, cache_root) ancillary_acquisitions = tuple( diff --git a/devcapsule-src/tests/integration/test_print_command_cli.py b/devcapsule-src/tests/integration/test_print_command_cli.py new file mode 100644 index 00000000..fad8be02 --- /dev/null +++ b/devcapsule-src/tests/integration/test_print_command_cli.py @@ -0,0 +1,83 @@ +"""Integration tests of ``project run --print-command``: the built launcher, with a stand-in where ``docker`` is. + +Printing a launch's command brings nothing to the machine. Each test runs the +built executable in an environment it builds: a home and a project under the +test's directory, and a search path whose ``docker`` is a script the test +writes. The script records every call, answers that no image is local, and +refuses any other request, so a launcher that asked Docker to pull or build +would be seen and would fail. The proxy variables send every download to a +closed port of this machine: a launcher that tried one would fail at once and +receive nothing. +""" +from __future__ import annotations + +import os +from pathlib import Path +import stat +import subprocess + +import pytest + +pytestmark = pytest.mark.integration + +STAND_IN_DOCKER = """#!/bin/sh +# Stands where docker is. Every call is recorded; only a question about a local image is answered. +echo "$*" >> "$DOCKER_STAND_IN_CALLS" +if [ "$1 $2" = "image inspect" ]; then + echo "[]" + echo "Error response from daemon: No such image: $3" >&2 + exit 1 +fi +echo "the stand-in for docker was asked to: $*" >&2 +exit 97 +""" + +CLOSED_PORT = "http://127.0.0.1:9" + + +@pytest.fixture +def launcher(built_pex: Path, tmp_path: Path): + """Run the built launcher on ``tmp_path / "project"`` in the test's own environment; the calls made to + ``docker`` are the lines of ``tmp_path / "docker-calls"``.""" + tools = tmp_path / "tools" + tools.mkdir() + docker = tools / "docker" + docker.write_text(STAND_IN_DOCKER, encoding="utf-8") + docker.chmod(docker.stat().st_mode | stat.S_IXUSR) + (tmp_path / "project").mkdir() + environment = { + "PATH": f"{tools}{os.pathsep}{os.environ['PATH']}", + "HOME": str(tmp_path / "home"), + "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "devcapsule-home"), + "DOCKER_STAND_IN_CALLS": str(tmp_path / "docker-calls"), + "http_proxy": CLOSED_PORT, "https_proxy": CLOSED_PORT, "HTTP_PROXY": CLOSED_PORT, "HTTPS_PROXY": CLOSED_PORT, + # The executable unpacks itself once into these caches, which the suite keeps for the whole run. + **{name: os.environ[name] for name in ("PEX_ROOT", "SCIE_BASE") if name in os.environ}, + } + + def run(*arguments: str) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [str(built_pex), "project", "--path", str(tmp_path / "project"), *arguments], + cwd=tmp_path, env=environment, capture_output=True, text=True, timeout=300, check=False, + ) + + return run + + +def test_print_command_names_a_base_image_that_is_not_here_and_pulls_nothing(launcher, tmp_path: Path) -> None: + """On a machine whose Docker has no image, ``run --print-command`` exits 2 and says that a launch pulls the + base image. It asks Docker only whether the image is local, prints no command, and downloads no file.""" + created = launcher("init", "--require", "python", "--ide", "python-ide", + "--creator", "mailto:owner@example.test", "--authorize", "base-image", "default") + assert created.returncode == 0, created.stderr + + printed = launcher("run", "--print-command", "--no-update-check") + + assert printed.returncode == 2, printed.stdout + printed.stderr + assert printed.stdout == "" + assert "is not on this machine. A launch pulls it; nothing was pulled now." in printed.stderr + assert "--print-command prints the command of an environment that is already here" in printed.stderr + calls = (tmp_path / "docker-calls").read_text(encoding="utf-8").splitlines() + assert calls and all(call.startswith("image inspect ") for call in calls), calls + downloaded = [path for path in (tmp_path / "home").rglob("*") if path.is_file() and "artifacts" in path.parts] + assert downloaded == [] diff --git a/devcapsule-src/tests/test_upgrade_recovery.py b/devcapsule-src/tests/test_upgrade_recovery.py index 9cc3a23c..152b0166 100644 --- a/devcapsule-src/tests/test_upgrade_recovery.py +++ b/devcapsule-src/tests/test_upgrade_recovery.py @@ -106,7 +106,8 @@ def fake_base(reference): base = known_base_image(reference) return replace(base, contract=replace(base.contract, display="contained" if contained else "host-x11-only")) if base else None monkeypatch.setattr(derivation, "known_base_image", fake_base, raising=False) - def realize(selected, *, report, prepare_base, trust=None): + def realize(selected, *, report, prepare_base, trust=None, fetch=True): + # ``fetch`` is what --print-command passes. These stand-ins fetch nothing either way. def obtain(reference): events.append("obtain-base") return ImageDetails(reference, LOCAL_ID, { diff --git a/devcapsule-src/tests/unit/devcapsule/test_materialization.py b/devcapsule-src/tests/unit/devcapsule/test_materialization.py index c8e46822..9fecd5df 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_materialization.py +++ b/devcapsule-src/tests/unit/devcapsule/test_materialization.py @@ -26,6 +26,7 @@ canonical_json, component_runtime_template, descriptor_differences, + NotOnThisMachine, ensure_materialized_surface, formation_descriptor, formation_identity, @@ -1241,3 +1242,78 @@ def test_ensure_materialized_surface_refuses_runtime_pex_without_webconsole_bund build=lambda _spec: None, runtime_pex=incomplete_pex, ) + + +# A look without fetching: ``ensure_materialized_surface(fetch=False)``, which ``project run --print-command`` asks for. + +def test_a_look_without_fetching_returns_the_environment_that_is_on_this_machine(tmp_path: Path) -> None: + """With ``fetch`` false and the canonical image present, the image is returned as reused and nothing is built.""" + spec = artifact(tmp_path / "missing.tar.gz") + canonical, labels = expected_labels("sha256:base", spec) + builds: list[object] = [] + + image, created = ensure_materialized_surface( + base_reference="base:debug", + base_identity="sha256:base", + platform="linux-amd64", + artifact=spec, + cache_root=tmp_path / "cache", + inspect_image=lambda reference: image_details(reference, labels) if reference == canonical else None, + build=builds.append, + fetch=False, + ) + + assert (image, created) == (canonical, False) + assert builds == [] + + +def test_a_look_without_fetching_names_the_environment_it_does_not_find_and_downloads_nothing(tmp_path: Path) -> None: + """With ``fetch`` false and no canonical image, ``NotOnThisMachine`` names the image and the artifact a launch + would download. The artifact is not read, although it is there to be read, and nothing is built.""" + archive = tmp_path / "pycharm.tar.gz" + digest = hashlib.sha256(fixture_archive(archive)).hexdigest() + spec = artifact(archive, digest) + canonical, _labels = expected_labels("sha256:base", spec) + builds: list[object] = [] + + with pytest.raises(NotOnThisMachine) as missing: + ensure_materialized_surface( + base_reference="base:debug", + base_identity="sha256:base", + platform="linux-amd64", + artifact=spec, + cache_root=tmp_path / "cache", + inspect_image=lambda reference: None, + build=builds.append, + fetch=False, + ) + + message = str(missing.value) + assert f"environment {canonical} is not built on this machine" in message + assert f"A launch downloads 1 artifact ({archive.as_uri()}) and builds it" in message + assert "nothing was downloaded or built now" in message + assert builds == [] + assert not (tmp_path / "cache" / "artifacts").exists() + + +def test_a_look_without_fetching_does_not_rebuild_a_boot_configuration(tmp_path: Path) -> None: + """With ``fetch`` false, an image whose boot configuration differs from its record is not repaired: + ``NotOnThisMachine`` says a launch rebuilds it, and nothing is built.""" + spec = artifact(tmp_path / "missing.tar.gz") + canonical, labels = expected_labels("sha256:base", spec) + drifted = ImageDetails(canonical, "sha256:image", labels, "linux", "amd64", entrypoint=("/bin/another-entrypoint",)) + builds: list[object] = [] + + with pytest.raises(NotOnThisMachine, match="needs its boot configuration rebuilt .*A launch rebuilds it; nothing was rebuilt now"): + ensure_materialized_surface( + base_reference="base:debug", + base_identity="sha256:base", + platform="linux-amd64", + artifact=spec, + cache_root=tmp_path / "cache", + inspect_image=lambda reference: drifted if reference == canonical else None, + build=builds.append, + fetch=False, + ) + + assert builds == [] diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 04cb7fa6..a97ffc8f 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -152,9 +152,12 @@ Unanswered host-access recommendations fall back to secure defaults for a plain launch, whereas `config check` exits `3` until they are answered. `--print-command` stops before starting a container and never saves checkout -answers, though it can still download components, build images, and populate -caches. Printed secret and environment values are redacted. Use `config show` -or `config check` when you want pure offline inspection. +answers. It pulls no image, downloads no component and builds nothing: it +prints the command of an environment that is already on your machine. When +the base image or the environment's image is not there yet, it exits `2` and +names what a launch would pull, download and build; launch once with +`project run`, then print. Printed secret and environment values are +redacted. ## `devcapsule project config` From f3023d29de48e308399c74b689582929c886f4df Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 16:27:11 +0000 Subject: [PATCH 38/75] Tests: the offered-agent test moves to the launch review, in memory; its holding-pen file is deleted The one test of tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py drove the command line four times and, inside a capsule, downloaded 1.5 GB. It is now two tests of review_launch that build their checkout in memory: an offered agent still waits for its vendor's channel, and a checkout that omits it has no such component in its plan. - The holding-pen file and its empty target module, devcapsule/legacy_refactoring/capability_minimums.py, are deleted, as that module's docstring provides. - tests/command_line_debt.txt loses the file's line: 7 files in debt. - tests/test_capability_minimums.py: the fixture line added for that test is taken out again; the file is as on the base. Evidence: nox -s tests passes in the owner's capsule, 3088 passed in 175 s, with no unit test that tries the network. Co-Authored-By: Claude --- .../legacy_refactoring/capability_minimums.py | 12 ------ devcapsule-src/tests/command_line_debt.txt | 1 - .../tests/test_capability_minimums.py | 4 -- .../devcapsule/commands/test_launch_review.py | 38 +++++++++++++++++-- .../test_capability_minimums.py | 33 ---------------- 5 files changed, 35 insertions(+), 53 deletions(-) delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/capability_minimums.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py diff --git a/devcapsule-src/devcapsule/legacy_refactoring/capability_minimums.py b/devcapsule-src/devcapsule/legacy_refactoring/capability_minimums.py deleted file mode 100644 index 22973479..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/capability_minimums.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_capability_minimums.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/tests/command_line_debt.txt b/devcapsule-src/tests/command_line_debt.txt index aa49c10e..211bb448 100644 --- a/devcapsule-src/tests/command_line_debt.txt +++ b/devcapsule-src/tests/command_line_debt.txt @@ -10,7 +10,6 @@ tests/unit/devcapsule/commands/test_images.py tests/unit/devcapsule/configuration/test_owner_commands.py tests/unit/devcapsule/configuration/test_storage.py tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py -tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py tests/unit/devcapsule/legacy_refactoring/test_console_channel.py tests/unit/devcapsule/legacy_refactoring/test_project_init.py tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/devcapsule-src/tests/test_capability_minimums.py b/devcapsule-src/tests/test_capability_minimums.py index 8fecd202..189a1a5e 100644 --- a/devcapsule-src/tests/test_capability_minimums.py +++ b/devcapsule-src/tests/test_capability_minimums.py @@ -46,10 +46,6 @@ def snapshot(root: Path) -> dict[Path, bytes]: def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"): monkeypatch.setenv(key, str(tmp_path / key.lower())) - # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its - # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the - # developer accepted there answers the consents these tests expect to be pending. - monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" (root / ".devcapsule").mkdir(parents=True) return root diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index b09ede20..c5071fe9 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -63,11 +63,12 @@ def directory(name: str) -> HostDirectory: def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Host | None = None, - manifest_tables: dict[str, Any] | None = None) -> CheckoutState: + manifest_tables: dict[str, Any] | None = None, offered: tuple[str, ...] = ()) -> CheckoutState: """A registered checkout of a project that requires ``required``, in a home that has accepted nothing. Its host is ``a_host()`` unless ``host`` is given. ``manifest_tables`` are - further tables of the manifest, ``environment`` for instance. + further tables of the manifest, ``environment`` for instance. ``offered`` + are capabilities the project offers and does not require. It is what ``project init --require ... --ide IDE --authorize base-image default`` leaves, built with the operations that command uses and no file: @@ -77,7 +78,7 @@ def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Hos manifest: dict[str, Any] = { "devcapsule-schema-version": 2, "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, - "capabilities": {"required": sorted(required)}, + "capabilities": {"required": sorted(required), **({"optional": sorted(offered)} if offered else {})}, **(manifest_tables or {}), } state = CheckoutState( @@ -442,3 +443,34 @@ def test_a_schema_one_manifest_recommends_its_ide_and_another_needs_no_force() - assert review.selected.resolution["runtime"]["component"] == "codium" assert review.selected.departures == () and "departures" not in review.selected.resolution assert review.record.document == review.original + + +def offering_claude_code() -> CheckoutState: + """A checkout of a project that requires Python and offers the Claude Code agent, with VSCodium saved.""" + return checkout_of(("python",), ide="frontend-ide", offered=("claude-code-agent",)) + + +def test_an_offered_agent_still_waits_for_its_vendors_channel() -> None: + """An agent the project only offers is in the launch unless the checkout omits it, so printing the launch's + command ends pending on its vendor's channel, and the state's documents are as they were.""" + state = offering_claude_code() + before = deepcopy((state.checkout, state.home)) + + with pytest.raises(DecisionPending, match="trust claude-code"): + review_launch(state, RunFlags(), ask=None, announce=never_announced, print_only=True) + + assert (state.checkout, state.home) == before + + +def test_an_offered_agent_the_checkout_omits_is_not_in_the_plan() -> None: + """When the checkout omits the offered agent, the launch is planned without a question and the agent's + component is not in its lock.""" + state = offering_claude_code() + selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) + selection.without.add("claude-code-agent") + state.checkout = state.with_selection(selection) + + review = review_launch(state, RunFlags(), ask=None, announce=never_announced, print_only=True) + + assert review.selected.resolution["runtime"]["component"] == "codium" + assert "claude-code" not in review.selected.lock["components"] diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py deleted file mode 100644 index 6dff360a..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py +++ /dev/null @@ -1,33 +0,0 @@ -"""Legacy tests of ``tests/test_capability_minimums.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/capability_minimums.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -from pathlib import Path -import pytest -from devcapsule import cli -from devcapsule.commands._run_flow import RunFlags, prepare_launch -from devcapsule.configuration import owner_commands -from tests.test_capability_minimums import MANIFEST, project, snapshot, write_project -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_offered_agent_still_needs_consent_and_can_be_omitted(project: Path, tmp_path: Path, capsys) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - write_project(project, MANIFEST.replace('"python>=3.14", ', '')) - assert cli.main(["project", "--path", str(project), "init", "--ide", "frontend-ide", "--authorize", "base-image", "default"]) == 0 - owner_commands.offer_tools(project, ["claude-code-agent"]) - before = snapshot(tmp_path) - assert cli.main(["project", "--path", str(project), "run", "--print-command", "--no-update-check"]) == 3 - assert "claude-code" in capsys.readouterr().err - assert snapshot(tmp_path) == before - assert cli.main(["project", "--path", str(project), "config", "omit", "claude-code-agent"]) == 0 - prepared = prepare_launch(project, RunFlags(), interactive=False, print_only=True) - assert "claude-code" not in prepared.selected.lock["components"] From b84823959553ccfe5d6441edd129226398917f46 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 16:27:32 +0000 Subject: [PATCH 39/75] Records: print-command fetches nothing; the downloading test is rewritten Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 21 +++++---- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 44 +++++++++++++++++++ 3 files changed, 58 insertions(+), 9 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 2bf89245..9ae5c736 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -202,16 +202,21 @@ What changed is that the tests which failed now say what their home is. read the home as before. Seven, which drive the command line, get a named home from their own file's fixture, `DEVCAPSULE_CONFIG_HOME` under the test's directory, in five legacy files. -- The test that downloaded vendor artifacts uses a fixture of - `tests/test_capability_minimums.py`, which names its home too. It stops at - the consent it expects and opens no connection. The network guard of - `tests/conftest.py`, new in pull request #26, now fails any unit test that - tries. -- `nox -s tests` passes inside the owner's capsule: 3083 passed, 10 expected - to fail, 11 unexpectedly passed, in 175 seconds where it took 815. +- The test that downloaded vendor artifacts is rewritten. It was the one + test of `tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py` + and drove the command line. It is now two tests of the launch review that + build their checkout in memory, and its file is deleted. The network guard + of `tests/conftest.py`, new in pull request #26, fails any unit test that + tries the network. +- The product changed too, on the owner's word: `project run + --print-command` no longer pulls the base image, downloads artifacts or + builds the environment. It prints the command of an environment that is + on the machine, and otherwise names what a launch would fetch and exits 2. +- `nox -s tests` passes inside the owner's capsule: 3088 passed, 10 expected + to fail, 10 unexpectedly passed, in 175 seconds where it took 815. Against the close criteria: 1 holds for the owner's capsule as it is today. -2 and 3 do not. Fourteen marks of this cause remain; eleven of their tests +2 and 3 do not. Thirteen marks of this cause remain; ten of their tests now pass. They are in mirror files whose legacy twins stand, so the gate refuses a change to them until those twins are retired. 4 does not hold: `private_user_directories` is unchanged, and a test that uses neither a diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index dbe7fdf8..8d6a3c6c 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the shared fixture and 14 marks are still to do | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 13 marks are still to do | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index c0cd2670..e6339bda 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -175,6 +175,50 @@ one table changed. Its docstring now says so. The standing failures are 5, in four files, and all five drive `cli.main`. No call in them can be handed a value. +**`project run --print-command` fetches nothing, 2026-11-12.** Owner +direction: whoever asks for the command to be printed did not ask for the +environment to be downloaded. Until now `--print-command` did all a launch +does before `docker run`: it pulled the base image, downloaded the +artifacts and built the environment's image, and `docs/reference/cli.md` +said so. Now `realize_environment` and `ensure_materialized_surface` take +`fetch`; `--print-command` passes false. An environment that is on the +machine has its command printed. A missing base image, a missing +environment image, or one whose boot configuration needs its rebuild ends +the command with exit 2 and a message that names what a launch would pull, +download and build, and the launch command to run once. The option's help, +the reference page and the package README say the same. + +- Tests: three mirror tests of the look without fetching in + `test_materialization.py`; one integration test, + `tests/integration/test_print_command_cli.py`, that runs the built launcher + with a stand-in script where `docker` is and proxies that point at a closed + port. The launcher asks the stand-in one thing, whether the base image is + local. +- Evidence: the real command in the owner's capsule, on a project never + launched, ends in 0.4 s with exit 2, names the image and three artifacts, + and writes no file to the cache. Two faults planted in the wiring, each + with the executable rebuilt, fail the integration test. +- Not covered by an automated test: the one line by which + `realize_environment` hands `fetch` to the materializer. Its mirror file + has a legacy twin, and the function finds the runtime executable through + the environment. The capsule run above is its evidence. +- Not done: printing the command of an environment that is not built. Its + image name follows from the lock alone, but the display and the console + are read from image labels, so that preview could differ from the launch. + +**The downloading test, rewritten.** The owner's second point: the test +that reached that download was the only test of its holding-pen file, and +belongs in a proper unit test that downloads nothing. It is now two tests +of `review_launch` in `test_launch_review.py`, in memory. The file +`tests/unit/devcapsule/legacy_refactoring/test_capability_minimums.py` and +its empty target module are deleted, and the command-line debt list has 7 +files. The fixture line added to `tests/test_capability_minimums.py` for +that test is taken out again. `nox -s tests` in the capsule: 3088 passed, +10 expected to fail, 10 unexpectedly passed. The integration tests that +need no Docker: 124 passed, 3 skipped, 1 failed; the failure is the +standing one of `test_pex_runtime.py`, which builds its environment in the +test's body from `os.environ` and so reads the mounted settings. + **The last five, and the unit session green in the capsule, 2026-11-12.** The five that remained drive `cli.main`, where no call can be handed a value. On the owner's word their files' fixtures name the home, as the From 1311379ece309e509ea5c81bb24abb74c31fb40c Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 16:28:10 +0000 Subject: [PATCH 40/75] Bug record: the marks that remain, counted by case Co-Authored-By: Claude --- ...nit-tests-read-the-capsules-mounted-launcher-settings.md | 6 ++++-- .../wip/2026-09-18-maintenance/CURRENT-STATUS.md | 3 ++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 9ae5c736..f5188d8f 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -216,8 +216,10 @@ What changed is that the tests which failed now say what their home is. to fail, 10 unexpectedly passed, in 175 seconds where it took 815. Against the close criteria: 1 holds for the owner's capsule as it is today. -2 and 3 do not. Thirteen marks of this cause remain; ten of their tests -now pass. They are in mirror files whose legacy twins stand, so the gate +2 and 3 do not. Thirteen marks remain, on 18 cases. Nine +cases pass now. Six still fail inside the capsule for this cause, behind +their mark, because they take fixtures from legacy files that were not +changed; three fail for another cause, the repository's own manifest. They are in mirror files whose legacy twins stand, so the gate refuses a change to them until those twins are retired. 4 does not hold: `private_user_directories` is unchanged, and a test that uses neither a named home nor a handed-in one still reads the mount. The next channel the diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index e6339bda..0180473d 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -233,7 +233,8 @@ and the network guard no longer fails the session. `nox -s tests` passes inside the owner's capsule for the first time since 2026-11-03: 3083 passed, 10 expected to fail, 11 unexpectedly passed, 175 seconds. The blocking bug's record has a progress section and is `fixing`, not closed: the shared -fixture is unchanged and 14 marks remain. +fixture is unchanged and the expected-to-fail marks remain; the record +counts them. **`tests/test_ide_requirement_override.py`, ordered retired whole. It is not yet.** Of its 26 test functions, 12 now have a form that needs no file, no From f5225dbaddb1d334121b7e392f2746a59cc77498 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 16:43:56 +0000 Subject: [PATCH 41/75] Tests: the console-channel holding-pen test becomes unit tests in memory and integration tests as processes The one test of tests/unit/devcapsule/legacy_refactoring/test_console_channel.py sent nine requests through the launcher's channel, each answered by a config command run as a process, and then asked the listing whether the vendors' consents were still pending. Inside a capsule it failed on that last claim, behind its mark. - tests/unit/devcapsule/configuration/test_derivation.py: five tests of a checkout's selection, in memory. - tests/unit/devcapsule/commands/test_launch_review.py: a checkout that adds an agent and chooses a vendor's IDE ends pending on both channels. - tests/integration/test_console_channel_cli.py, new: four tests that send requests through a channel directory and let the launcher sweep it in a process whose environment the test builds, with a named home. - The holding-pen file and its empty target module are deleted; tests/command_line_debt.txt has 6 files. No product code changed. Evidence: five planted faults, three in the channel and two in the selection, each caught. nox -s typecheck tests passes in the owner's capsule, 3095 passed; the integration tests that need no Docker, 128 passed, 3 skipped, 1 failed, the standing one. Co-Authored-By: Claude --- .../legacy_refactoring/console_channel.py | 12 -- devcapsule-src/tests/command_line_debt.txt | 1 - .../integration/test_console_channel_cli.py | 135 ++++++++++++++++++ .../devcapsule/commands/test_launch_review.py | 18 +++ .../configuration/test_derivation.py | 81 ++++++++++- .../test_console_channel.py | 52 ------- 6 files changed, 228 insertions(+), 71 deletions(-) delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/console_channel.py create mode 100644 devcapsule-src/tests/integration/test_console_channel_cli.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_console_channel.py diff --git a/devcapsule-src/devcapsule/legacy_refactoring/console_channel.py b/devcapsule-src/devcapsule/legacy_refactoring/console_channel.py deleted file mode 100644 index 06eb586f..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/console_channel.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_console_channel.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_console_channel.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/tests/command_line_debt.txt b/devcapsule-src/tests/command_line_debt.txt index 211bb448..7ade8cf1 100644 --- a/devcapsule-src/tests/command_line_debt.txt +++ b/devcapsule-src/tests/command_line_debt.txt @@ -10,6 +10,5 @@ tests/unit/devcapsule/commands/test_images.py tests/unit/devcapsule/configuration/test_owner_commands.py tests/unit/devcapsule/configuration/test_storage.py tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py -tests/unit/devcapsule/legacy_refactoring/test_console_channel.py tests/unit/devcapsule/legacy_refactoring/test_project_init.py tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/devcapsule-src/tests/integration/test_console_channel_cli.py b/devcapsule-src/tests/integration/test_console_channel_cli.py new file mode 100644 index 00000000..47cb9422 --- /dev/null +++ b/devcapsule-src/tests/integration/test_console_channel_cli.py @@ -0,0 +1,135 @@ +"""Integration tests of the console's configuration channel: real requests, answered by real ``config`` commands. + +The launcher answers a request file by running ``devcapsule project config`` +as a process of its own. So these tests run processes: the launcher's sweep +of a request directory, and the commands it starts, in an environment the +test builds. The home is named and lies under the test's directory, with +nothing accepted in it; the project is created there by ``project init``. + +No command here needs Docker or the network. +""" +from __future__ import annotations + +import json +import os +from pathlib import Path +import subprocess +import sys +from typing import Any + +import pytest + +from devcapsule.configuration.capabilities import LocalCapabilities +from devcapsule.configuration.console_channel import read_document, write_complete +from devcapsule.configuration.storage import load_toml + +pytestmark = pytest.mark.integration + +SWEEP = """ +import sys +from pathlib import Path +from devcapsule.commands._console_channel import sweep +print(sweep(Path(sys.argv[1]), Path(sys.argv[2]), Path(sys.argv[3]))) +""" +"""The launcher's side of the channel, as a program: answer the requests in a directory and print how many.""" + + +class Capsule: + """One project with its home and its channel directory, and the processes that act on them.""" + + def __init__(self, directory: Path) -> None: + self.project = directory / "project" + self.home = directory / "devcapsule-home" + self.channel = directory / "channel" + self.project.mkdir() + self.channel.mkdir() + self.environment = { + "PATH": os.defpath, "HOME": str(directory / "home"), "DEVCAPSULE_CONFIG_HOME": str(self.home), + "PYTHONDONTWRITEBYTECODE": "1", + } + + def run(self, *command: str) -> subprocess.CompletedProcess[str]: + """Start a Python program in the capsule's environment; standard error is joined to standard output.""" + return subprocess.run( + [sys.executable, *command], cwd=self.project, env=self.environment, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, timeout=300, check=False, + ) + + def config(self, *arguments: str) -> subprocess.CompletedProcess[str]: + """``devcapsule project config ARGUMENTS`` for the project, as the developer would run it on the host.""" + return self.run("-m", "devcapsule", "project", "--path", str(self.project), "config", *arguments) + + @property + def record(self) -> Path: + """The checkout's record in the named home.""" + (found,) = self.home.rglob("devcapsule.checkout.toml") + return found + + def selection(self) -> LocalCapabilities: + """The capabilities the checkout's record selects, omits and chooses providers for.""" + return LocalCapabilities.read(load_toml(self.record)) + + def send(self, identifier: str, *arguments: str) -> dict[str, Any]: + """Put one request in the channel as the console writes it, let the launcher sweep, and return its result.""" + write_complete(self.channel / f"{identifier}.request.json", + {"format": 1, "requested": "2026-10-24T10:00:00+00:00", "arguments": list(arguments)}) + swept = self.run("-c", SWEEP, str(self.channel), str(self.project), str(self.record)) + assert swept.returncode == 0 and swept.stdout.strip() == "1", swept.stdout + return read_document(self.channel / f"{identifier}.result.json") + + +@pytest.fixture +def capsule(tmp_path: Path) -> Capsule: + """A project that requires Node and offers browser automation, registered in a home that has accepted nothing.""" + capsule = Capsule(tmp_path) + created = capsule.run("-m", "devcapsule", "project", "--path", str(capsule.project), "init", + "--require", "node", "--creator", "mailto:owner@example.test") + assert created.returncode == 0, created.stdout + offered = capsule.config("offer", "browser-automation") + assert offered.returncode == 0, offered.stdout + return capsule + + +def test_capability_choices_sent_through_the_channel_are_recorded_on_the_checkout(capsule: Capsule) -> None: + """Each capability choice the console sends is applied at once and reported as recorded: an agent added, an + offered capability omitted and restored, an IDE selected, and a provider chosen for it. The record holds + each choice after its request, and no request is kept for a confirmation.""" + assert capsule.send("000001-add", "add", "claude-code-agent")["status"] == "recorded" + assert "claude-code-agent" in capsule.selection().selected + assert capsule.send("000002-omit", "omit", "browser-automation")["status"] == "recorded" + assert "browser-automation" in capsule.selection().without + assert capsule.send("000003-restore", "restore", "browser-automation")["status"] == "recorded" + assert "browser-automation" not in capsule.selection().without + assert capsule.send("000004-ide", "ide", "frontend-ide")["status"] == "recorded" + assert capsule.send("000005-use", "use", "frontend-ide", "vscode")["status"] == "recorded" + assert capsule.selection().providers == {"frontend-ide": "vscode"} + assert list(capsule.home.rglob("requests.json")) == [] + + +@pytest.mark.parametrize(("capability", "component"), [("python-ide", "pycharm"), ("vscode-ide", "vscode")]) +def test_a_choice_the_command_refuses_is_refused_through_the_channel_in_the_commands_words( + capsule: Capsule, capability: str, component: str, +) -> None: + """A provider choice for a capability with one provider, which ``config use`` refuses with exit 2, comes back + through the channel as refused, with the text the command printed.""" + direct = capsule.config("use", capability, component) + assert direct.returncode == 2 and "choice" in direct.stdout, direct.stdout + + refused = capsule.send("000001-use", "use", capability, component) + + assert refused["status"] == "refused" + assert direct.stdout.strip() in refused["text"] + + +def test_choices_recorded_through_the_channel_leave_their_vendors_consents_pending(capsule: Capsule) -> None: + """After the console adds the Claude Code agent and chooses Visual Studio Code, ``config show`` still lists + both vendors' downloads as pending: the channel records a selection and accepts nothing for it.""" + assert capsule.send("000001-add", "add", "claude-code-agent")["status"] == "recorded" + assert capsule.send("000002-ide", "ide", "frontend-ide")["status"] == "recorded" + assert capsule.send("000003-use", "use", "frontend-ide", "vscode")["status"] == "recorded" + + shown = capsule.config("show", "--json") + + assert shown.returncode == 0, shown.stdout + pending = {row["name"] for row in json.loads(shown.stdout)["rows"] if row["pending"]} + assert {"claude-code-download", "vscode-download"} <= pending diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index c5071fe9..9bc3d5cf 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -26,6 +26,7 @@ from devcapsule.configuration.file_formats import ProjectConfigurationError, canonical_digest, render_checkout, render_toml from devcapsule.configuration.listing import Decision from devcapsule.configuration.manifest import current_manifest +from devcapsule.configuration.manifest_document import Recommendations from devcapsule.configuration.operations import CheckoutRecord from devcapsule.configuration.values import memory_size_bytes from devcapsule.platforms import Platform @@ -474,3 +475,20 @@ def test_an_offered_agent_the_checkout_omits_is_not_in_the_plan() -> None: assert review.selected.resolution["runtime"]["component"] == "codium" assert "claude-code" not in review.selected.lock["components"] + + +def test_choosing_an_agent_and_a_vendors_ide_accepts_neither_vendors_channel() -> None: + """A checkout that adds the Claude Code agent and chooses Visual Studio Code for its IDE, in a home that has + accepted nothing, ends pending on Anthropic's channel and on Microsoft's: a selection is not a consent.""" + state = checkout_of(("node",), ide="frontend-ide") + selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) + selection.extra.add("claude-code-agent") + selection.use(state.matrix, CapabilityPolicy.read(state.manifest), Recommendations.read(state.manifest), "frontend-ide", "vscode") + state.checkout = state.with_selection(selection) + + with pytest.raises(DecisionPending) as pending: + review_launch(state, RunFlags(), ask=None, announce=never_announced) + + assert "trust claude-code: Trust Anthropic to supply Claude Code" in str(pending.value) + assert "trust vscode: Trust Microsoft to supply Visual Studio Code" in str(pending.value) + diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py index 62b9f680..bc18b50f 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py @@ -1,8 +1,9 @@ -"""Unit tests of ``devcapsule/configuration/derivation.py``: reading a checkout into memory. +"""Unit tests of ``devcapsule/configuration/derivation.py``: reading a checkout into memory, and a checkout's selection. -Each test writes its project under ``tmp_path``: a manifest and the lock the -product derives from it. The home is the private one the suite gives every -test; a test that needs a settings file there writes it. +Each test of the reading writes its project under ``tmp_path``: a manifest +and the lock the product derives from it. The home is the private one the +suite gives every test; a test that needs a settings file there writes it. +The tests of the selection use values alone. """ from __future__ import annotations @@ -11,10 +12,11 @@ import pytest -from devcapsule.configuration.capabilities import CapabilityPolicy +from devcapsule.configuration.capabilities import CapabilityPolicy, LocalCapabilities from devcapsule.configuration.capability_selection import generate_lock -from devcapsule.configuration.derivation import load_state +from devcapsule.configuration.derivation import Selection, load_state from devcapsule.configuration.file_formats import ProjectConfigurationError, render_toml +from devcapsule.configuration.manifest_document import Recommendations from devcapsule.configuration.storage import settings_path from devcapsule.platforms import Platform from devcapsule.resolution_matrix import MATRICES @@ -103,3 +105,70 @@ def test_an_unregistered_checkout_is_read_with_the_record_it_would_get(tmp_path: assert not state.input_path.exists() assert state.platform is Platform.LINUX_AMD64 assert state.shared_lock["platform"] == "linux-amd64" + + +# A checkout's selection: the IDE, the capabilities added and omitted, and the provider chosen where several +# can supply a capability. ``project config ide``, ``add``, ``omit``, ``restore`` and ``use`` edit one of these. + +AMD64 = MATRICES[Platform.LINUX_AMD64] +SURFACES = {name: AMD64.resolve_provider(name) or name for name in AMD64.ide_capabilities()} +POLICY = CapabilityPolicy.read(MANIFEST) +NO_RECOMMENDATION = Recommendations.read(MANIFEST) + + +def choose_provider(selection: Selection, capability: str, component: str) -> None: + """``project config use CAPABILITY COMPONENT`` on a selection of ``MANIFEST``'s project.""" + selection.use(AMD64, POLICY, NO_RECOMMENDATION, capability, component) + + +def test_a_provider_is_chosen_for_the_selected_ide_and_recorded_with_it() -> None: + """With the front-end IDE selected, which VSCodium and Visual Studio Code both supply, choosing Visual Studio + Code is recorded as that capability's provider, beside the IDE and an added agent.""" + selection = Selection(LocalCapabilities(), SURFACES) + selection.ide = "frontend-ide" + selection.extra.add("claude-code-agent") + + choose_provider(selection, "frontend-ide", "vscode") + + assert selection.local() == LocalCapabilities(("claude-code-agent", "frontend-ide"), (), {"frontend-ide": "vscode"}) + + +@pytest.mark.parametrize(("capability", "component"), [("python-ide", "pycharm"), ("vscode-ide", "vscode")]) +def test_a_capability_with_one_provider_offers_no_choice(capability: str, component: str) -> None: + """Choosing a provider for a capability that one component supplies is refused, even when the component + named is that one, and the selection is unchanged.""" + selection = Selection(LocalCapabilities((capability,)), SURFACES) + + with pytest.raises(ProjectConfigurationError, match=f"'{capability}' has no provider choice; supplied by {component}"): + choose_provider(selection, capability, component) + + assert selection.local() == LocalCapabilities((capability,)) + + +def test_a_provider_cannot_be_chosen_for_a_capability_that_is_not_selected() -> None: + """Choosing a provider for the front-end IDE while no IDE is selected is refused, naming the commands that + select it.""" + selection = Selection(LocalCapabilities(), SURFACES) + + with pytest.raises(ProjectConfigurationError, match="'frontend-ide' is not selected; use 'config add frontend-ide' or 'config ide frontend-ide' first"): + choose_provider(selection, "frontend-ide", "vscode") + + +def test_the_default_provider_is_chosen_by_forgetting_the_choice() -> None: + """``default`` as the component removes a recorded provider choice and leaves the capability selected.""" + selection = Selection(LocalCapabilities(("frontend-ide",), (), {"frontend-ide": "vscode"}), SURFACES) + + choose_provider(selection, "frontend-ide", "default") + + assert selection.local() == LocalCapabilities(("frontend-ide",)) + + +def test_selecting_another_ide_forgets_the_provider_chosen_for_the_one_it_replaces() -> None: + """Changing the IDE from the front-end IDE to PyCharm drops the provider chosen for the front-end IDE and + keeps the capabilities that are not IDEs.""" + selection = Selection(LocalCapabilities(("claude-code-agent", "frontend-ide"), (), {"frontend-ide": "vscode"}), SURFACES) + + selection.ide = "python-ide" + + assert selection.local() == LocalCapabilities(("claude-code-agent", "python-ide")) + diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_console_channel.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_console_channel.py deleted file mode 100644 index 2f7713e2..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_console_channel.py +++ /dev/null @@ -1,52 +0,0 @@ -"""Legacy tests of ``tests/test_console_channel.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/console_channel.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -import json -import pytest -from devcapsule.commands._console_channel import run_config, sweep -from devcapsule.configuration.console_requests import deferred_requests -from devcapsule.configuration.storage import load_toml -from tests.test_console_channel import config, project, record_path, request, result -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_channel_records_capability_choices_and_preserves_vendor_consent(project, tmp_path, capsys): - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - from devcapsule.configuration.capabilities import LocalCapabilities - assert config(project, "offer", "browser-automation") == 0 - channel = tmp_path / "channel" - channel.mkdir() - def send(identifier, *arguments): - request(channel, identifier, *arguments) - assert sweep(channel, project, record_path(project)) == 1 - return result(channel, identifier) - assert send("000001-add", "add", "claude-code-agent")["status"] == "recorded" - assert "claude-code-agent" in LocalCapabilities.read(load_toml(record_path(project))).selected - assert send("000002-omit", "omit", "browser-automation")["status"] == "recorded" - assert "browser-automation" in LocalCapabilities.read(load_toml(record_path(project))).without - assert send("000003-restore", "restore", "browser-automation")["status"] == "recorded" - assert "browser-automation" not in LocalCapabilities.read(load_toml(record_path(project))).without - assert send("000004-ide", "ide", "frontend-ide")["status"] == "recorded" - assert send("000005-use", "use", "frontend-ide", "vscode")["status"] == "recorded" - assert LocalCapabilities.read(load_toml(record_path(project))).providers == {"frontend-ide": "vscode"} - # Single-provider capabilities still refuse `use` through the same command path. - for index, (capability, component) in enumerate((("python-ide", "pycharm"), ("vscode-ide", "vscode")), start=6): - expected_status, expected_text = run_config(project, ["use", capability, component]) - assert expected_status == 2 and "choice" in expected_text - refused = send(f"00000{index}-use", "use", capability, component) - assert refused["status"] == "refused" and expected_text.strip() in refused["text"] - capsys.readouterr() - assert config(project, "show", "--json") == 0 - listing = json.loads(capsys.readouterr().out) - assert any(row["name"] == "claude-code-download" and row["pending"] for row in listing["rows"]) - assert any(row["name"] == "vscode-download" and row["pending"] for row in listing["rows"]) - assert deferred_requests(record_path(project)) == [] From 88d63c370bdea8959e03b83924bb491f42106a12 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 16:43:56 +0000 Subject: [PATCH 42/75] Records: the console-channel holding-pen test rewritten Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 4 +-- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 30 +++++++++++++++++++ 3 files changed, 33 insertions(+), 3 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index f5188d8f..239cb271 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -216,8 +216,8 @@ What changed is that the tests which failed now say what their home is. to fail, 10 unexpectedly passed, in 175 seconds where it took 815. Against the close criteria: 1 holds for the owner's capsule as it is today. -2 and 3 do not. Thirteen marks remain, on 18 cases. Nine -cases pass now. Six still fail inside the capsule for this cause, behind +2 and 3 do not. Twelve marks remain, on 17 cases. Nine +cases pass now. Five still fail inside the capsule for this cause, behind their mark, because they take fixtures from legacy files that were not changed; three fail for another cause, the repository's own manifest. They are in mirror files whose legacy twins stand, so the gate refuses a change to them until those twins are retired. 4 does not hold: diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 8d6a3c6c..89639192 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 13 marks are still to do | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 12 marks are still to do | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 0180473d..b2ec75ce 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -175,6 +175,36 @@ one table changed. Its docstring now says so. The standing failures are 5, in four files, and all five drive `cli.main`. No call in them can be handed a value. +**The console-channel holding-pen test, rewritten, 2026-11-12.** The one +test of `tests/unit/devcapsule/legacy_refactoring/test_console_channel.py` +was three tests in one, and an integration test by nature: the launcher +answers each request by running `project config` as a process. Inside a +capsule it failed, behind its mark, on its last claim, that the vendors' +consents stay pending. It is now: + +- in memory, in `test_derivation.py`: five tests of a checkout's selection, + the provider chosen for an IDE, the refusal where one component supplies + a capability, the refusal for a capability not selected, `default`, and + the IDE change that forgets the old provider; +- in memory, in `test_launch_review.py`: a checkout that adds the Claude + Code agent and chooses Visual Studio Code ends pending on both vendors' + channels; +- as processes, in the new `tests/integration/test_console_channel_cli.py`: + four tests that send requests through a real channel directory, let the + launcher sweep it in a process whose environment the test builds, with a + named home, and read the record, the results and `config show`. + +The mirror of `commands/_console_channel.py` and of +`configuration/console_channel.py` would both be named +`test_console_channel.py`, which the gate pairs with the legacy file of +that name; so no test of those two modules could be added, and none was +needed. The holding-pen file and its empty target module are deleted; the +command-line debt list has 6 files. Five planted faults, three in the +channel and two in the selection, are each caught. `nox -s tests` in the +capsule: 3095 passed, 9 expected to fail, 10 unexpectedly passed. The +integration tests that need no Docker: 128 passed, 3 skipped, and the one +standing failure. + **`project run --print-command` fetches nothing, 2026-11-12.** Owner direction: whoever asks for the command to be printed did not ask for the environment to be downloaded. Until now `--print-command` did all a launch From a7087c4b4a772ecec8703e07ff842077bbfabc98 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 17:58:17 +0000 Subject: [PATCH 43/75] Tests: the capability-commands holding-pen test becomes four tests of the launch review, in memory The one test of tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py had three cases, expected to fail inside a capsule: it read the launcher's mounted settings, drove seven config commands through the command line and patched the platform's capability table. Its claim is now tested on values, on the real table: Visual Studio Code chosen for frontend-ide by the project's recommendation, on the checkout, or with --provider for one run leaves a saving launch pending on Microsoft's channel, with the state's record and home as they were. A fourth test plans the same launch with no choice, on VSCodium. The holding-pen file and its empty target module are deleted; the command-line debt list has 5 files. No product code changed. Evidence: five planted faults each caught; nox -s typecheck tests in the capsule, 3099 passed, 6 expected to fail, 10 unexpectedly passed. Co-Authored-By: Claude --- .../capability_commands_v2.py | 12 ---- devcapsule-src/tests/command_line_debt.txt | 1 - .../devcapsule/commands/test_launch_review.py | 61 +++++++++++++++++-- .../test_capability_commands_v2.py | 36 ----------- 4 files changed, 56 insertions(+), 54 deletions(-) delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/capability_commands_v2.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py diff --git a/devcapsule-src/devcapsule/legacy_refactoring/capability_commands_v2.py b/devcapsule-src/devcapsule/legacy_refactoring/capability_commands_v2.py deleted file mode 100644 index 01f3f640..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/capability_commands_v2.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_capability_commands_v2.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/tests/command_line_debt.txt b/devcapsule-src/tests/command_line_debt.txt index 7ade8cf1..9d3ae10b 100644 --- a/devcapsule-src/tests/command_line_debt.txt +++ b/devcapsule-src/tests/command_line_debt.txt @@ -9,6 +9,5 @@ tests/unit/devcapsule/commands/test_images.py tests/unit/devcapsule/configuration/test_owner_commands.py tests/unit/devcapsule/configuration/test_storage.py -tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py tests/unit/devcapsule/legacy_refactoring/test_project_init.py tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index 9bc3d5cf..d356efec 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -20,7 +20,9 @@ from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value from devcapsule.configuration.bindings import HostDirectory -from devcapsule.configuration.capabilities import IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture +from devcapsule.configuration.capabilities import ( + IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture, resolution_recommendations, +) from devcapsule.configuration.capability_selection import generate_lock from devcapsule.configuration.derivation import CheckoutState, Host, Selection from devcapsule.configuration.file_formats import ProjectConfigurationError, canonical_digest, render_checkout, render_toml @@ -64,12 +66,15 @@ def directory(name: str) -> HostDirectory: def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Host | None = None, - manifest_tables: dict[str, Any] | None = None, offered: tuple[str, ...] = ()) -> CheckoutState: + manifest_tables: dict[str, Any] | None = None, offered: tuple[str, ...] = (), + recommended: dict[str, str] | None = None) -> CheckoutState: """A registered checkout of a project that requires ``required``, in a home that has accepted nothing. Its host is ``a_host()`` unless ``host`` is given. ``manifest_tables`` are further tables of the manifest, ``environment`` for instance. ``offered`` - are capabilities the project offers and does not require. + are capabilities the project offers and does not require. ``recommended`` + are the components the project recommends, by capability, as ``config + recommend`` records them. It is what ``project init --require ... --ide IDE --authorize base-image default`` leaves, built with the operations that command uses and no file: @@ -79,13 +84,15 @@ def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Hos manifest: dict[str, Any] = { "devcapsule-schema-version": 2, "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, - "capabilities": {"required": sorted(required), **({"optional": sorted(offered)} if offered else {})}, + "capabilities": {"required": sorted(required), **({"optional": sorted(offered)} if offered else {}), + **({"resolution": dict(recommended)} if recommended else {})}, **(manifest_tables or {}), } state = CheckoutState( root=ROOT, manifest=manifest, platform=Platform.LINUX_AMD64, lock_path=ROOT / ".devcapsule" / "devcapsule.linux-amd64.lock", - shared_lock=generate_lock(CapabilityPolicy.read(manifest), MATRICES[Platform.LINUX_AMD64]), + shared_lock=generate_lock(CapabilityPolicy.read(manifest), MATRICES[Platform.LINUX_AMD64], + recommendations=resolution_recommendations(manifest)), home={}, home_path=HOME, input_path=RECORD, registered=True, host=host or a_host(), checkout=tomllib.loads(render_checkout(manifest, ROOT, {}, {})), @@ -492,3 +499,47 @@ def test_choosing_an_agent_and_a_vendors_ide_accepts_neither_vendors_channel() - assert "trust claude-code: Trust Anthropic to supply Claude Code" in str(pending.value) assert "trust vscode: Trust Microsoft to supply Visual Studio Code" in str(pending.value) + + +def recommended_by_the_project() -> tuple[CheckoutState, RunFlags]: + """The project recommends Visual Studio Code for ``frontend-ide``; the checkout selects that IDE and chooses nothing.""" + return checkout_of(("python",), ide="frontend-ide", recommended={"frontend-ide": "vscode"}), RunFlags(memory="6g", save=True) + + +def chosen_on_the_checkout() -> tuple[CheckoutState, RunFlags]: + """The checkout's record chooses Visual Studio Code for ``frontend-ide``, as ``config use`` leaves it.""" + state = checkout_of(("python",), ide="frontend-ide") + selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) + selection.use(state.matrix, CapabilityPolicy.read(state.manifest), Recommendations.read(state.manifest), "frontend-ide", "vscode") + state.checkout = state.with_selection(selection) + return state, RunFlags(memory="6g", save=True) + + +def named_for_this_run() -> tuple[CheckoutState, RunFlags]: + """Neither the project nor the checkout chooses; ``--provider frontend-ide=vscode`` does, on the command line.""" + return checkout_of(("python",), ide="frontend-ide"), RunFlags(providers=(("frontend-ide", "vscode"),), memory="6g", save=True) + + +@pytest.mark.parametrize("chosen", [recommended_by_the_project, chosen_on_the_checkout, named_for_this_run]) +def test_a_provider_choice_accepts_no_channel_and_a_pending_save_stages_nothing(chosen: Any) -> None: + """Visual Studio Code, whether the project recommends it, the checkout chose it or the command line names it, + leaves a launch with ``--memory 6g --save`` pending on Microsoft's channel: choosing a provider accepts + nothing. The state's record and home are as they were, the memory included, so there is no part of the save + to write.""" + state, flags = chosen() + before = deepcopy((state.checkout, state.home)) + + with pytest.raises(DecisionPending, match="trust vscode: Trust Microsoft to supply Visual Studio Code"): + review_launch(state, flags, ask=None, announce=never_announced) + + assert (state.checkout, state.home) == before + + +def test_with_no_provider_chosen_the_same_saving_launch_is_planned_with_the_default_one() -> None: + """With no recommendation, choice or flag, ``frontend-ide`` is VSCodium, which waits for no channel: the + launch with ``--memory 6g --save`` is planned and the memory is staged on the record.""" + review = review_launch(checkout_of(("python",), ide="frontend-ide"), RunFlags(memory="6g", save=True), + ask=None, announce=never_announced) + + assert review.selected.resolution["runtime"]["component"] == "codium" + assert memory_size_bytes(str(review.record.values["memory"])) == 6 * 1024 ** 3 diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py deleted file mode 100644 index ba51d22e..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py +++ /dev/null @@ -1,36 +0,0 @@ -"""Legacy tests of ``tests/test_capability_commands_v2.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/capability_commands_v2.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -import pytest -from devcapsule.commands._run_flow import RunFlags, prepare_launch -from devcapsule.compat import DecisionPending -from tests.test_run_flow import project, config -from tests.test_capability_commands_v2 import matrix, snapshot -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.parametrize("origin", ["project", "checkout", "run"]) -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_resolution_grants_no_consent_and_no_partial_save(project, matrix, tmp_path, origin): - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - assert config(project, "ide", "frontend-ide") == 0 - assert config(project, "authorize", "base-image", "default") == 0 - assert config(project, "add", "assistant") == 0 - if origin == "project": - assert config(project, "recommend", "assistant", "claude-code") == 0 - assert config(project, "use", "assistant", "default") == 0 - elif origin == "checkout": - assert config(project, "use", "assistant", "claude-code") == 0 - before = snapshot(tmp_path) - flags = RunFlags(providers=(("assistant", "claude-code"),) if origin == "run" else (), memory="6g", save=True) - with pytest.raises(DecisionPending, match="claude"): - prepare_launch(project, flags, interactive=False) - assert snapshot(tmp_path) == before From c53f4f94ec187cb40d6a62c39ce7263db0632e31 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 17:58:17 +0000 Subject: [PATCH 44/75] Records: the capability-commands holding-pen test rewritten Status section, the bug record's progress and the 0.3.1 bug table: 11 marks remain on 14 cases in five holding-pen files; 9 pass, 2 fail inside a capsule for the mounted settings, 3 for the repository's own manifest. Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 22 ++++++++---- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 35 +++++++++++++++++++ 3 files changed, 52 insertions(+), 7 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 239cb271..332434eb 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -212,15 +212,25 @@ What changed is that the tests which failed now say what their home is. --print-command` no longer pulls the base image, downloads artifacts or builds the environment. It prints the command of an environment that is on the machine, and otherwise names what a launch would fetch and exits 2. -- `nox -s tests` passes inside the owner's capsule: 3088 passed, 10 expected - to fail, 10 unexpectedly passed, in 175 seconds where it took 815. +- Two more marked tests are rewritten and their holding-pen files deleted. + The one test of `test_console_channel.py` became six tests in memory and + four integration tests that run the channel as processes. The one test + of `test_capability_commands_v2.py`, three cases, became four tests of + the launch review in memory: a provider the project recommends, the + checkout chose or the command line names accepts no channel, and a + pending save stages nothing. +- `nox -s tests` passes inside the owner's capsule: 3099 passed, 6 expected + to fail, 10 unexpectedly passed, in 173 seconds where it took 815. Against the close criteria: 1 holds for the owner's capsule as it is today. -2 and 3 do not. Twelve marks remain, on 17 cases. Nine -cases pass now. Five still fail inside the capsule for this cause, behind +2 and 3 do not. Eleven marks remain, on 14 cases, in five files. Nine +cases pass now. Two still fail inside the capsule for this cause, behind their mark, because they take fixtures from legacy files that were not -changed; three fail for another cause, the repository's own manifest. They are in mirror files whose legacy twins stand, so the gate -refuses a change to them until those twins are retired. 4 does not hold: +changed: one in `test_environment_realization.py`, one in +`test_project_init.py`. Three fail for another cause, the repository's own +manifest. They are in mirror files whose legacy twins stand, so the gate +refuses a change to them until those twins are retired; it accepts the +deletion of a whole holding-pen file whose tests are rewritten elsewhere. 4 does not hold: `private_user_directories` is unchanged, and a test that uses neither a named home nor a handed-in one still reads the mount. The next channel the developer accepts can turn other tests red. diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 89639192..f500a785 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 12 marks are still to do | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 11 marks, on 14 cases of which 2 still fail for this cause, are still to do | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index b2ec75ce..445faf4e 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -205,6 +205,41 @@ capsule: 3095 passed, 9 expected to fail, 10 unexpectedly passed. The integration tests that need no Docker: 128 passed, 3 skipped, and the one standing failure. +**The capability-commands holding-pen test, rewritten, 2026-11-12.** The +one test of +`tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py` +had three cases, all failing inside a capsule behind their mark. Its claim: +a provider chosen for a capability, by the project's recommendation, on the +checkout, or with `--provider` for one run, accepts no vendor's channel, and +a launch with `--save` that ends pending writes no part of the save. It +set its checkout up through seven `config` commands and replaced the +platform's capability table with a patched one, to have an agent +capability with two providers. + +It is now four tests in `test_launch_review.py`, in memory, on the platform's +real table: `frontend-ide` is supplied by VSCodium, which waits for no +channel, and by Visual Studio Code, which waits for Microsoft's. Three cases +build the choice of Visual Studio Code in each of the three places and end +pending on that channel with the state's record and home as they were; the +fourth is the same saving launch with no choice, planned with VSCodium and +the memory staged. `checkout_of` in that file takes what the project +recommends. No product code changed. + +Five planted faults are each caught: the command line's provider ignored, +the project's recommendation ignored, the checkout's choice dropped, the +memory left on the state by a pending save, a named provider's channel +counted as accepted. What the four tests do not hold: that `prepare_launch` +calls the writer only after the review returns. That is three lines, and +two legacy tests of `tests/test_run_flow.py` hold it on files, among them +`test_missing_pass_through_variable_blocks_and_does_not_save`: a saving +launch ends pending and the test's whole directory is as it was. + +The holding-pen file and its empty target module are deleted; the +command-line debt list has 5 files. `nox -s typecheck tests` in the +capsule: 3099 passed, 6 expected to fail, 10 unexpectedly passed. The +holding pen has five files with 11 marks on 14 cases: 9 pass, 2 fail for +the mounted settings, 3 for the repository's own manifest. + **`project run --print-command` fetches nothing, 2026-11-12.** Owner direction: whoever asks for the command to be printed did not ask for the environment to be downloaded. Until now `--print-command` did all a launch From bbeac23f8e369a81bd92b8d3afe12c6cdc40b032 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 22:16:35 +0000 Subject: [PATCH 45/75] Tests: the two repository-manifest-compatibility files become one test file of the offline check, on frozen projects tests/test_repository_manifest_compatibility.py and its holding-pen twin read this repository's own .devcapsule files. Three of their four tests compared those files with vocabulary copied from v0.2.15: the rule of 2026-10-04, which the owner superseded on 2026-10-05. They tested no code. The fourth claimed that the launch still reads a lock an earlier matrix wrote, and read whatever lock the working tree held. All three marked tests failed wherever a 0.3 launcher had rewritten the repository's configuration. Both files and the empty target module are deleted, on the owner's word. tests/unit/devcapsule/configuration/test_capability_commands.py tests check_documents, the work of 'project config check', on projects kept under tests/resources/compat: v026.2, v0.2.11 and repository-2026-10-25, a byte copy of this repository's manifest and lock as committed. The captures pass and are left as given; a locked component nothing needs is passed over; an unknown needed capability, an unknown runtime-effect and a locked component without its version are refused by name. capability_commands.py declares __all__, as Unit Tests rule 4 requires of a tested module. Evidence: seven planted faults each caught; nox -s typecheck tests in the capsule, 3105 passed, 3 expected to fail, 10 unexpectedly passed. Co-Authored-By: Claude --- .github/ci-python-inputs.yml | 2 +- .../configuration/capability_commands.py | 6 ++ .../repository_manifest_compatibility.py | 12 --- .../tests/resources/compat/README.md | 10 ++ .../.devcapsule/devcapsule.linux-amd64.lock | 77 +++++++++++++ .../project/.devcapsule/devcapsule.toml | 46 ++++++++ .../test_repository_manifest_compatibility.py | 51 --------- .../configuration/test_capability_commands.py | 93 ++++++++++++++++ .../test_repository_manifest_compatibility.py | 101 ------------------ 9 files changed, 233 insertions(+), 165 deletions(-) delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/repository_manifest_compatibility.py create mode 100644 devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.linux-amd64.lock create mode 100644 devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.toml delete mode 100644 devcapsule-src/tests/test_repository_manifest_compatibility.py create mode 100644 devcapsule-src/tests/unit/devcapsule/configuration/test_capability_commands.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_repository_manifest_compatibility.py diff --git a/.github/ci-python-inputs.yml b/.github/ci-python-inputs.yml index a7aaccf6..2f6f55e4 100644 --- a/.github/ci-python-inputs.yml +++ b/.github/ci-python-inputs.yml @@ -17,7 +17,7 @@ python: - '.github/**' # Read by unit tests that predate Unit Tests rule 2 of WORKFLOW-LOCAL.md. # Each entry leaves when its reader builds its own input. - - '.devcapsule/**' # tests/test_base_contract.py, tests/test_repository_manifest_compatibility.py + - '.devcapsule/**' # tests/test_base_contract.py - 'component-status/**' # tests/test_component_status.py - 'docs/**' # the [docs] case of tests/unit/devcapsule/legacy_refactoring/test_home.py walks all of docs/; # tests/test_release_docs.py reads docs/versions.yaml diff --git a/devcapsule-src/devcapsule/configuration/capability_commands.py b/devcapsule-src/devcapsule/configuration/capability_commands.py index 9fbaaffe..c429ddba 100644 --- a/devcapsule-src/devcapsule/configuration/capability_commands.py +++ b/devcapsule-src/devcapsule/configuration/capability_commands.py @@ -27,6 +27,12 @@ project_platform, require_settled, ) +__all__ = [ + "canonical_tool_name", "check", "check_documents", "check_formation", "configure", "configure_local", + "configure_project", "parse_tool_names", "paths", "project_locks", "promote", "recover", "regenerate_locks", + "release_deselected", +] + def paths(root: Path) -> tuple[Path, Path, Path]: """Return manifest, current-platform lock and recovery-journal paths. diff --git a/devcapsule-src/devcapsule/legacy_refactoring/repository_manifest_compatibility.py b/devcapsule-src/devcapsule/legacy_refactoring/repository_manifest_compatibility.py deleted file mode 100644 index 7d41d586..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/repository_manifest_compatibility.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_repository_manifest_compatibility.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_repository_manifest_compatibility.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/tests/resources/compat/README.md b/devcapsule-src/tests/resources/compat/README.md index 0c7db2d6..90cd572d 100644 --- a/devcapsule-src/tests/resources/compat/README.md +++ b/devcapsule-src/tests/resources/compat/README.md @@ -30,6 +30,16 @@ action for a project, checkout, or platform lock created by an earlier one. checkout path and its resulting checkout-input digest are templated, as above. `test_upgrade_recovery.py` exercises unchanged-client inputs and separately introduces project-side changes into copies of these artifacts. +- `repository-2026-10-25/` is this repository's own project, copied on + 2026-11-12 from `.devcapsule/` at commit `c53f4f94`, byte for byte: Git + blobs `1ebb222f` (manifest) and `8ea6c67a` (lock). The manifest is the + schema-1 one last changed in commit `3dbe4cb9` of 2026-10-04. The lock was + regenerated in commit `dedb485b` of 2026-10-25 from the resolution matrix + `embedded-28`, by the source that became `v0.3.0-rc7`; it pins PyCharm and + the three agents on the recipe-11 base. It is here because the suite used + to read the live files, which change whenever a launcher rewrites them. + `tests/unit/devcapsule/configuration/test_capability_commands.py` reads + this copy, with `v026.2/` and `v0.2.11/`. When a release changes what these artifacts would contain, add a new directory for that release; do not update these. diff --git a/devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.linux-amd64.lock b/devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.linux-amd64.lock new file mode 100644 index 00000000..8ea6c67a --- /dev/null +++ b/devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.linux-amd64.lock @@ -0,0 +1,77 @@ +"capabilities-digest" = "5a8581f94902def37cc35f11e607c81bf0ecce7cd8b2d70417a3502d24fc4468" +"devcapsule-lock-format-version" = 1 +"platform" = "linux-amd64" +"resolution-matrix-version" = "embedded-28" + +["base"] +"build-mnemonic" = "v0.3.0-rc6" +"contract" = "ubuntu-24.04@11" +"recipe-source" = "devcapsule-src/devcapsule/images/base.py" +"reference" = "docker.io/mycodespaceai/devcapsule-base@sha256:8c97d308b4ac8172ce91ef4f96406063bfcd85a55efb09d4a23e795b10a834a3" + +["capability-providers"] +"antigravity-agent" = ["antigravity-cli"] +"claude-code-agent" = ["claude-code"] +"codex-agent" = ["codex"] +"docker-cli" = [] +"python" = [] +"python-ide" = ["pycharm"] + +["components"] +"interactive-surface" = "pycharm" + +["components"."antigravity-cli"] +"acquisition-authorization" = "antigravity-download" +"delivery-policy" = "local-materialization" +"distribution" = "user-acquired-not-redistributed" +"license" = "Proprietary" +"terms-url" = "https://antigravity.google/terms/" +"version" = "1.4.2" + +["components"."antigravity-cli"."artifacts"] + +["components"."antigravity-cli"."artifacts"."linux-amd64"] +"archive-member" = "antigravity" +"sha256" = "6395837ac0e193dd3fe50f1228e1c4aea345ca99636d54404ab7e74397d4091c" +"upstream-sha512" = "4a393afc1369cee94e817c1b430c9128d02b12ebd4d5703ace5cd47b2333e216d673fb0097cbf7195f757b110163ba9850e9eea3fdbbaddd4b25668b82c03f05" +"url" = "https://storage.googleapis.com/antigravity-public/antigravity-cli/1.4.2-4835981233356800/linux-x64/cli_linux_x64.tar.gz" + +["components"."claude-code"] +"acquisition-authorization" = "claude-code-download" +"delivery-policy" = "local-materialization" +"distribution" = "user-acquired-not-redistributed" +"license" = "Proprietary" +"terms-url" = "https://www.anthropic.com/legal/commercial-terms" +"version" = "2.1.302" + +["components"."claude-code"."artifacts"] + +["components"."claude-code"."artifacts"."linux-amd64"] +"sha256" = "60d7eb7f12fbb28a52533fe8be5884097403562aa02dc73991a021c7067e29a5" +"url" = "https://downloads.claude.ai/claude-code-releases/2.1.302/linux-x64/claude" + +["components"."codex"] +"delivery-policy" = "local-materialization" +"license" = "Apache-2.0" +"npm-package" = "@openai/codex" +"sha256" = "1a71db36560bb446d2c2e63ae675c4a3018c38ace38ca533f8d1b25d3e6555b4" +"url" = "https://registry.npmjs.org/@openai/codex/-/codex-0.163.0.tgz" +"version" = "0.163.0" + +["components"."codex"."artifacts"] + +["components"."codex"."artifacts"."linux-amd64"] +"npm-package" = "@openai/codex-linux-x64" +"sha256" = "30efc97738b975940d78b59a9bea115fa34040b732807d54ec35ae6b7528de94" +"url" = "https://registry.npmjs.org/@openai/codex/-/codex-0.163.0-linux-x64.tgz" + +["components"."pycharm"] +"delivery-policy" = "local-materialization" +"sha256" = "4a37cb2d15703553c61e814d8e014bfa47308508470de5f968c4e9645b771675" +"url" = "https://download.jetbrains.com/python/pycharm-2026.2.0.1.tar.gz" +"variant" = "professional" +"version" = "2026.2.0.1" + +["materialization"] +"recipe" = "jetbrains-local-materialization" +"recipe-version" = "1" diff --git a/devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.toml b/devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.toml new file mode 100644 index 00000000..1ebb222f --- /dev/null +++ b/devcapsule-src/tests/resources/compat/repository-2026-10-25/project/.devcapsule/devcapsule.toml @@ -0,0 +1,46 @@ +devcapsule-schema-version = 1 +workflow-type = "multiple-streams" + +[workflow] +definition = "devcapsule" +version = "0.2.14.dev0" +mode = "multiple-streams" + +[capabilities] +need = ["antigravity-agent", "claude-code-agent", "codex-agent", "docker-cli", "python", "python-ide"] + +[project] +name = "DevCapsule" +slug = "devcapsule" +creator = "https://github.com/ccozianu" +mount = "/workspace/301e4208ef81-ChatGPT_Codex" + +[configuration.values."runtime.memory-limit"] +type = "memory-size" +runtime-effect = "docker.memory-limit" +description = "Hard memory limit applied to the checkout's project container." + +# Keep the public devcapsule name available for our development installation. +# Other projects omit this recommendation and receive the shipped devcapsule. +# No runtime-effect attribute: the name is reserved and carries the effect, +# and released clients that predate the effect vocabulary reject any +# attribute they do not know. +[configuration.values."runtime.devcapsule-command"] +type = "string" +recommended = "devcapsule0" +description = "Name of the shipped CLI inside the capsule; devcapsule0 leaves devcapsule for a development build." + +[host.docker.mode.recommended] +value = "host-socket" +justification = "Required to run peer DevCapsule instances during the full test suite." +enables = ["full-test-suite"] + +[host.network.mode.recommended] +value = "host" +justification = "Temporary dogfood compatibility for host-bound development services." +enables = ["legacy-dogfood-host-services"] + +[host.privilege.development-sudo.recommended] +value = true +justification = "Required by the current dogfood development and validation workflow." +enables = ["dogfood-development-administration"] diff --git a/devcapsule-src/tests/test_repository_manifest_compatibility.py b/devcapsule-src/tests/test_repository_manifest_compatibility.py deleted file mode 100644 index 260d8d32..00000000 --- a/devcapsule-src/tests/test_repository_manifest_compatibility.py +++ /dev/null @@ -1,51 +0,0 @@ -"""The repository's own manifest must stay readable by the latest released client. - -Released clients validate ``runtime-effect`` by exact membership in the -vocabulary they shipped with, and refuse the whole manifest otherwise. -Locked components likewise need runtime templates in that released client. A -declaration added here therefore strands every contributor who installed the -release the guides point at, and the refusal cannot explain itself (bug -2026-09-24, released launchers reject the repository manifest). Move the -pinned vocabulary only when a final release ships with the new entry. -""" - -from pathlib import Path -import tomllib - -import pytest - -from devcapsule.materialization import parse_locked_environment - -pytestmark = pytest.mark.legacy - - -# Frozen from final v0.2.15, commit a15ff8b58f4af93845c17eaca22f9c9d29c8e000: -# configuration/values.py, resolution_matrix.py and components/catalog.py. -# Do not import the development catalog: that would accept the very additions -# this bootstrap guard must catch before they ship in a final release. -LATEST_RELEASED_CLIENT = "v0.2.15" -RELEASED_RUNTIME_EFFECTS = {"docker.memory-limit", "devcapsule.command-name"} -RELEASED_CAPABILITIES = { - "antigravity-agent", "claude-code-agent", "codex-agent", "docker-cli", - "frontend-ide", "java", "maven", "node", "postgresql-client", "python", - "python-ide", -} -RELEASED_SURFACES = {"pycharm", "codium"} -RELEASED_COMPONENTS = RELEASED_SURFACES | { - "antigravity-cli", "claude-code", "codex", "postgresql-client", -} - -REPOSITORY_MANIFEST = Path(__file__).resolve().parents[2] / ".devcapsule" / "devcapsule.toml" - - -@pytest.mark.skipif(not REPOSITORY_MANIFEST.is_file(), reason="not a repository checkout") -def test_repository_manifest_declares_only_released_runtime_effects(): - manifest = tomllib.loads(REPOSITORY_MANIFEST.read_text(encoding="utf-8")) - values = manifest.get("configuration", {}).get("values", {}) - assert values, "the repository manifest declares configuration values" - for name, declaration in values.items(): - effect = declaration.get("runtime-effect") - assert effect is None or effect in RELEASED_RUNTIME_EFFECTS, ( - f"{name} declares runtime-effect {effect!r}, which {LATEST_RELEASED_CLIENT} " - "rejects; rely on a reserved name or wait for the release that knows it" - ) diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_commands.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_commands.py new file mode 100644 index 00000000..0f60b927 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_capability_commands.py @@ -0,0 +1,93 @@ +"""Unit tests of ``devcapsule/configuration/capability_commands.py``: the offline check of a project's shared documents. + +``check_documents`` is the work of ``project config check``. It takes a +project's manifest and one platform lock, as documents, and refuses the pair +that this launcher cannot launch. A launcher must go on accepting the +projects that earlier launchers wrote. So these tests give it such projects, +kept under ``tests/resources/compat`` as their writers left them, and then +the same documents with one thing changed in memory. + +No test reads this repository's own ``.devcapsule`` directory. What a +developer's launcher has written there is not an input of a test. +""" + +from __future__ import annotations + +from copy import deepcopy +from pathlib import Path +import tomllib +from typing import Any + +import pytest + +from devcapsule.compat import CliError +from devcapsule.configuration.capability_commands import check_documents +from devcapsule.configuration.file_formats import ProjectConfigurationError + +CAPTURES = Path(__file__).resolve().parents[3] / "resources" / "compat" +"""Projects written by earlier launchers. ``README.md`` there says which launcher wrote each, and when.""" + +THIS_REPOSITORY = "repository-2026-10-25" +"""DevCapsule's own project as committed on that day: a schema-1 manifest and a lock that pins PyCharm and three agents.""" + + +def captured(name: str) -> tuple[dict[str, Any], dict[str, Any]]: + """The manifest and the ``linux-amd64`` lock of the captured project ``name``, as documents.""" + directory = CAPTURES / name / "project" / ".devcapsule" + return (tomllib.loads((directory / "devcapsule.toml").read_text(encoding="utf-8")), + tomllib.loads((directory / "devcapsule.linux-amd64.lock").read_text(encoding="utf-8"))) + + +@pytest.mark.parametrize("name", ["v026.2", "v0.2.11", THIS_REPOSITORY]) +def test_a_project_an_earlier_launcher_wrote_passes_the_check(name: str) -> None: + """The manifest and the lock that an earlier launcher wrote pass this launcher's check with no warning, and + the check leaves both documents as it was given them.""" + manifest, lock = captured(name) + before = deepcopy((manifest, lock)) + + assert check_documents(manifest, lock) == () + + assert (manifest, lock) == before + + +def test_a_locked_component_that_nothing_needs_and_this_launcher_does_not_know_is_passed_over() -> None: + """A lock may carry a component of a newer launcher. When no capability of the project needs it, the check + passes with no warning although this launcher cannot install that component.""" + manifest, lock = captured(THIS_REPOSITORY) + lock["components"]["fortran-compiler"] = {"version": "1"} + + assert check_documents(manifest, lock) == () + + +def test_a_needed_capability_that_this_launcher_does_not_know_is_refused_by_name() -> None: + """A manifest that needs a capability this launcher has never had is refused. The refusal names the + capability and says that this launcher does not support it.""" + manifest, lock = captured(THIS_REPOSITORY) + manifest["capabilities"]["need"].append("fortran") + + with pytest.raises(ProjectConfigurationError, match="Required capability 'fortran' is unavailable: this launcher does not support it"): + check_documents(manifest, lock) + + +def test_a_runtime_effect_that_this_launcher_does_not_know_is_refused_as_a_newer_launchers() -> None: + """A configuration value whose ``runtime-effect`` this launcher does not know is refused. The refusal names + the value and the effect, and says that the project may require a newer DevCapsule.""" + manifest, lock = captured(THIS_REPOSITORY) + manifest["configuration"]["values"]["runtime.memory-limit"]["runtime-effect"] = "docker.cpu-limit" + + with pytest.raises(ProjectConfigurationError) as refused: + check_documents(manifest, lock) + + message = str(refused.value) + assert "configuration.values.runtime.memory-limit.runtime-effect 'docker.cpu-limit' is not supported" in message + assert "The project may require a newer DevCapsule." in message + + +def test_a_locked_component_that_the_launch_installs_is_read_and_a_missing_version_refused() -> None: + """The check reads every locked component that the launch would install: a lock whose Codex component has + an empty version is refused, and the refusal names ``components.codex.version``.""" + manifest, lock = captured(THIS_REPOSITORY) + lock["components"]["codex"]["version"] = "" + + with pytest.raises(CliError, match="components\\.codex\\.version must be a non-empty string"): + check_documents(manifest, lock) diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_repository_manifest_compatibility.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_repository_manifest_compatibility.py deleted file mode 100644 index 41392327..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_repository_manifest_compatibility.py +++ /dev/null @@ -1,101 +0,0 @@ -"""Legacy tests of ``tests/test_repository_manifest_compatibility.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/repository_manifest_compatibility.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -import tomllib -import pytest -from devcapsule.materialization import parse_locked_environment -from tests.test_repository_manifest_compatibility import LATEST_RELEASED_CLIENT, RELEASED_CAPABILITIES, RELEASED_COMPONENTS, RELEASED_SURFACES, REPOSITORY_MANIFEST -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.skipif(not REPOSITORY_MANIFEST.is_file(), reason="not a repository checkout") -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_repository_needs_are_supported_by_released_launcher(): - """Legacy test, moved verbatim and expected to fail: it reads this checkout's live .devcapsule configuration instead of constructing its input.""" - manifest = tomllib.loads(REPOSITORY_MANIFEST.read_text(encoding="utf-8")) - unknown = set(manifest["capabilities"]["need"]) - RELEASED_CAPABILITIES - assert not unknown, ( - f"repository needs {sorted(unknown)}, unsupported by {LATEST_RELEASED_CLIENT}; " - "test unreleased capabilities in a disposable project instead" - ) - - - -@pytest.mark.skipif(not REPOSITORY_MANIFEST.is_file(), reason="not a repository checkout") -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_repository_locks_have_released_runtime_templates(): - """Legacy test, moved verbatim and expected to fail: it reads this checkout's live .devcapsule configuration instead of constructing its input.""" - locks = sorted(REPOSITORY_MANIFEST.parent.glob("devcapsule.*.lock")) - assert locks, "the repository commits its platform lock" - for path in locks: - lock = tomllib.loads(path.read_text(encoding="utf-8")) - components = lock["components"] - assert components["interactive-surface"] in RELEASED_SURFACES, ( - f"{path.name} selects a surface unknown to {LATEST_RELEASED_CLIENT}" - ) - unknown = set(components) - {"interactive-surface"} - RELEASED_COMPONENTS - assert not unknown, ( - f"{path.name} needs runtime templates for {sorted(unknown)} missing from " - f"{LATEST_RELEASED_CLIENT}; restoring only the manifest is insufficient" - ) - - - -@pytest.mark.skipif(not REPOSITORY_MANIFEST.is_file(), reason="not a repository checkout") -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_repository_lock_is_launchable_by_this_launcher(): - """The committed lock, written by an earlier matrix, still launches here. - - Precondition: ``.devcapsule/devcapsule.linux-amd64.lock`` as committed, - generated by whatever matrix the launcher of its day embedded; as a rule - an earlier generation than the development matrix in this tree. - - Action: read it the way ``project run`` does before it touches Docker, - ``parse_locked_environment``, which validates every artifact declaration - and looks up every component's runtime template. - - Postcondition: no error; the environment names the lock's interactive - surface and base, and one validated artifact set for every other - locally materialized component the lock lists. - - The lock carries its own URLs and checksums, so the embedded matrix plays - no part: a lock may lag the catalog, or pin versions the catalog has since - retired, and must still launch. Nothing here asserts that the lock is the - matrix's newest selection; that is repository housekeeping, done by a - launcher command on the host. This test imports the development reader on - purpose: it is the reader that must stay liberal. - - TODO: this proves only that this repository's own lock still reads. The - contract is wider: every project initialized by an earlier release must - keep launching with a new one, manifest, lock and checkout record alike. - The test that enforces it, over configurations captured from each - released client, is the work item - engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md. - """ - - locks = sorted(REPOSITORY_MANIFEST.parent.glob("devcapsule.*.lock")) - assert locks, "the repository commits its platform lock" - for path in locks: - lock = tomllib.loads(path.read_text(encoding="utf-8")) - components = lock["components"] - surface = components["interactive-surface"] - materialized = { - component_id - for component_id, table in components.items() - if component_id not in ("interactive-surface", surface) - and table.get("delivery-policy") == "local-materialization" - } - - environment = parse_locked_environment(lock) - - assert environment.component_id == surface, path.name - assert environment.base_reference == lock["base"]["reference"], path.name - assert {item.component_id for item in environment.ancillary_artifacts} == materialized, path.name From 1aa52c731caa1e0fd0147bd2e171332aaf8abf21 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 22:16:35 +0000 Subject: [PATCH 46/75] Records: the repository-manifest-compatibility tests replaced Status section; the mounted-settings record now counts 8 marks on 11 cases in four holding-pen files; the 2026-10-18 record says what the new test holds and which captures are still missing. Co-Authored-By: Claude --- ...s-old-projects-launch-with-new-releases.md | 25 ++++++++++++ ...-the-capsules-mounted-launcher-settings.md | 21 ++++++---- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 38 +++++++++++++++++++ 4 files changed, 78 insertions(+), 8 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md b/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md index 915ff9e7..61e4fa83 100644 --- a/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md +++ b/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md @@ -61,3 +61,28 @@ release ships and retired when the version leaves support. Opened 2026-10-18 by `maintenance` at the owner's direction, during the 0.3.0 cycle. No target: it is validation work for the next planning, not a 0.3.0 gate. + +## Progress, 2026-11-12 + +On `ws-maintenance/launch-phases`, pull request #29, not merged. + +`test_repository_lock_is_launchable_by_this_launcher` is deleted. It read +the lock in the working tree, and since 0.3 a project whose IDE is +recommended has a shared lock without one, which the launch's reader +rightly refuses alone; the test failed wherever a 0.3 launcher had +rewritten this repository's configuration. Its claim is now held on frozen +inputs by `tests/unit/devcapsule/configuration/test_capability_commands.py`: +the offline check of `project config check`, `check_documents`, accepts the +manifest and lock of three captured projects, `v026.2`, `v0.2.11` and +`repository-2026-10-25`, the last being this repository's own project as +committed, written from matrix `embedded-28`. + +Still open, against the expected behaviour above: + +- No capture was written by a released 0.2.14, 0.2.15 or 0.3.0 client. +- No checkout record or authorization of a capture is read by the new + test; `tests/test_upgrade_recovery.py` does that for `v0.2.11` only. +- The release runbook names no capture step. +- `v026-formation`, the hand-authored adopter shape, does not pass the + check: `components.codex.npm-package must be '@openai/codex'`. Not + judged here; the standing test of that capture covers inspection only. diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 332434eb..1b98ce2a 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -219,18 +219,25 @@ What changed is that the tests which failed now say what their home is. the launch review in memory: a provider the project recommends, the checkout chose or the command line names accepts no channel, and a pending save stages nothing. -- `nox -s tests` passes inside the owner's capsule: 3099 passed, 6 expected - to fail, 10 unexpectedly passed, in 173 seconds where it took 815. +- The three marked tests of `test_repository_manifest_compatibility.py` + never failed for this cause. They read this repository's own + `.devcapsule` files and failed wherever a launcher had rewritten them, + in a capsule or not. They are deleted with their legacy file, on the + owner's word, and replaced by + `tests/unit/devcapsule/configuration/test_capability_commands.py`, which + reads frozen copies. +- `nox -s tests` passes inside the owner's capsule: 3105 passed, 3 expected + to fail, 10 unexpectedly passed, in 170 seconds where it took 815. Against the close criteria: 1 holds for the owner's capsule as it is today. -2 and 3 do not. Eleven marks remain, on 14 cases, in five files. Nine +2 and 3 do not. Eight marks remain, on 11 cases, in four files. Nine cases pass now. Two still fail inside the capsule for this cause, behind their mark, because they take fixtures from legacy files that were not changed: one in `test_environment_realization.py`, one in -`test_project_init.py`. Three fail for another cause, the repository's own -manifest. They are in mirror files whose legacy twins stand, so the gate -refuses a change to them until those twins are retired; it accepts the -deletion of a whole holding-pen file whose tests are rewritten elsewhere. 4 does not hold: +`test_project_init.py`. They are in mirror files whose legacy twins stand, +so the gate refuses a change to them until those twins are retired; it +accepts the deletion of a whole holding-pen file whose tests are rewritten +elsewhere. 4 does not hold: `private_user_directories` is unchanged, and a test that uses neither a named home nor a handed-in one still reads the mount. The next channel the developer accepts can turn other tests red. diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index f500a785..18167ef0 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 11 marks, on 14 cases of which 2 still fail for this cause, are still to do | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 8 marks, on 11 cases of which 2 still fail for this cause, are still to do | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 445faf4e..69e34f62 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -205,6 +205,44 @@ capsule: 3095 passed, 9 expected to fail, 10 unexpectedly passed. The integration tests that need no Docker: 128 passed, 3 skipped, and the one standing failure. +**The two `test_repository_manifest_compatibility.py` files, replaced by +one, 2026-11-12.** Owner direction: delete what tests nothing real, +consolidate the rest in one properly written file. + +The three marked tests did not fail because of the capsule. They read this +repository's own `.devcapsule` files, and the owner's working tree holds the +schema-2 files a 0.3 launcher wrote; each test ended in a `KeyError` of its +own. The hosted run passed because the commit still holds the schema-1 +files. Of the four tests in the two files: + +- three compared the repository's manifest and lock with vocabulary copied + by hand from v0.2.15. That is the 2026-10-04 rule, one frozen release must + read every shared declaration, which the owner superseded on 2026-10-05 + in *Keep The Development Checkout Launchable*. They tested no code. +- one, `test_repository_lock_is_launchable_by_this_launcher`, had a real + claim, that the launch still reads a lock an earlier matrix wrote, on a + live input. + +Both files and the empty target module are deleted. The new +`tests/unit/devcapsule/configuration/test_capability_commands.py` tests +`check_documents`, the work of `project config check`, on frozen projects +under `tests/resources/compat`: `v026.2`, `v0.2.11`, and +`repository-2026-10-25`, a byte copy of this repository's manifest and lock +as committed. Seven cases: the three captures pass with no warning and are +left as given; a locked component this launcher does not know and nothing +needs is passed over; an unknown needed capability, an unknown +`runtime-effect` and a locked component without its version are each +refused by name. `capability_commands.py` gained `__all__`, which *Unit +Tests* rule 4 requires before a module is tested. Seven planted faults are +each caught. + +`nox -s typecheck tests` in the capsule: 3105 passed, 3 expected to fail, +10 unexpectedly passed. The holding pen has four files with 8 marks on 11 +cases: 9 pass, 2 fail for the mounted settings. The open record of +2026-10-18 says what is still missing: captures written by 0.2.14, 0.2.15 +and 0.3.0. One observation there for the owner: the `v026-formation` +capture does not pass the check. + **The capability-commands holding-pen test, rewritten, 2026-11-12.** The one test of `tests/unit/devcapsule/legacy_refactoring/test_capability_commands_v2.py` From 1da39ae1e04e8ff8c34113dc5bff4eea1c36771a Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 22:49:53 +0000 Subject: [PATCH 47/75] Records: owner ruling on compatibility, 2026-11-12 Compatibility with 0.2.14, 0.2.15 and earlier may be dropped. The promise to users needs a defined story and a packaging, targeted for after 0.3.1. The pre-0.3 captures and their tests stand until then without being a promise. Co-Authored-By: Claude --- ...s-old-projects-launch-with-new-releases.md | 22 ++++++++++++++++++- .../2026-09-18-maintenance/CURRENT-STATUS.md | 12 ++++++++-- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md b/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md index 61e4fa83..0f9104cb 100644 --- a/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md +++ b/engineering-docs/bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md @@ -79,10 +79,30 @@ committed, written from matrix `embedded-28`. Still open, against the expected behaviour above: -- No capture was written by a released 0.2.14, 0.2.15 or 0.3.0 client. +- No capture was written by a released 0.3.0 client. For 0.2.14 and 0.2.15 + see the ruling below. - No checkout record or authorization of a capture is read by the new test; `tests/test_upgrade_recovery.py` does that for `v0.2.11` only. - The release runbook names no capture step. - `v026-formation`, the hand-authored adopter shape, does not pass the check: `components.codex.npm-package must be '@openai/codex'`. Not judged here; the standing test of that capture covers inspection only. + +## Owner ruling, 2026-11-12 + +Compatibility with 0.2.14, 0.2.15 and earlier releases may be dropped. No +capture from them is required, and the expected behaviour above no longer +names them. + +What DevCapsule promises its users about compatibility is not yet defined. +It needs a story, which releases a project and a checkout stay usable +across and what a user does when they do not, and a packaging, how the +promise is stated, shipped and tested. The owner targets that for after +0.3.1. Until it exists: + +- R-COMPAT-001 and R-CONFIG-001 stand as written; the story revises them. +- The captures `v026.2`, `v0.2.11` and `v026-formation` and the tests that + read them stand. They are not a promise. A change that has to break one + retires the capture and says so; it is not blocked by it. +- This record stays open as the test half of that work. Its close criteria + are rewritten when the story is. diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 69e34f62..e5069eb2 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -239,8 +239,10 @@ each caught. `nox -s typecheck tests` in the capsule: 3105 passed, 3 expected to fail, 10 unexpectedly passed. The holding pen has four files with 8 marks on 11 cases: 9 pass, 2 fail for the mounted settings. The open record of -2026-10-18 says what is still missing: captures written by 0.2.14, 0.2.15 -and 0.3.0. One observation there for the owner: the `v026-formation` +2026-10-18 says what is still missing. The owner then ruled that +compatibility with 0.2.14, 0.2.15 and earlier may be dropped, and that the +compatibility promise gets a defined story and packaging after 0.3.1; see +Open Threads. One observation there for the owner: the `v026-formation` capture does not pass the check. **The capability-commands holding-pen test, rewritten, 2026-11-12.** The @@ -5288,6 +5290,12 @@ claimed. No final release or graphical/end-user acceptance is claimed yet. ## Open Threads +- Owner ruling, 2026-11-12: compatibility with 0.2.14, 0.2.15 and earlier + may be dropped. The compatibility promise to users needs a defined story + and a packaging, targeted for after 0.3.1; not started and not yet + planned with project-management. Until then the pre-0.3 captures and + their tests stand without being a promise. Recorded in + [the 2026-10-18 record](../../bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md). - Paused for owner travel on 2026-10-31. No work continues during the break. - On return, confirm the first 0.3.1 slice; release-independent test fixtures are proposed. The nine documentation proposals still need item-level From e74e52402f9e7c91683109df9bfe30a6f83f0842 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 22:55:01 +0000 Subject: [PATCH 48/75] Records: the compatibility promise sent to project-management Co-Authored-By: Claude --- .../wip/2026-09-18-maintenance/CURRENT-STATUS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index e5069eb2..0e41c9e5 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -5292,8 +5292,10 @@ claimed. No final release or graphical/end-user acceptance is claimed yet. - Owner ruling, 2026-11-12: compatibility with 0.2.14, 0.2.15 and earlier may be dropped. The compatibility promise to users needs a defined story - and a packaging, targeted for after 0.3.1; not started and not yet - planned with project-management. Until then the pre-0.3 captures and + and a packaging, targeted for after 0.3.1; not started. Sent to + project-management the same day as + `2026-11-12-maintenance-compatibility-promise-story-and-packaging.md`, + coordination `d615b0a1ff41`; routing is theirs. Until then the pre-0.3 captures and their tests stand without being a promise. Recorded in [the 2026-10-18 record](../../bugs/devcapsule/2026-10-18-no-test-proves-old-projects-launch-with-new-releases.md). - Paused for owner travel on 2026-10-31. No work continues during the break. From 17176c95579a0b32a33bdf4b9162e3605b218db8 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 23:25:53 +0000 Subject: [PATCH 49/75] Tests: no unit test sees the capsule it runs in; the last two failing marked cases rewritten in memory The shared fixture private_user_directories now sets the two fixed paths by which the product knows a capsule, CONTEXT_PATH and CHANNEL_PATH of devcapsule.runtime_configuration, to places that do not exist. A test's home no longer falls back to the launcher's mounted settings, and a command no longer reads the live configuration channel, wherever the suite runs. The five per-file fixtures that named the home are removed again: one mechanism. The calls that hand in home={} stay. The two cases that still failed inside a capsule behind their mark: - the Claude Code download refused by realize_environment is four tests of review_authorizations, where the decision is taken: unanswered, answered by the home's trust, denied by the checkout over that trust, granted by the checkout alone; - the agent that brings its own acquisition gate is two tests of the launch review. Both holding-pen files and their empty target modules are deleted; the command-line debt list has 4 files. No product code changed. Evidence: five planted faults each caught; with the fixture's lines removed its own test and the seven command-line tests fail in the capsule; nox -s typecheck tests in the capsule, 3112 passed, 1 expected to fail, 10 unexpectedly passed; with marks ignored 3122 pass and one workflow test fails behind its own mark. Co-Authored-By: Claude --- .../environment_realization.py | 12 --- .../legacy_refactoring/project_init.py | 12 --- devcapsule-src/tests/command_line_debt.txt | 1 - .../tests/configuration/test_contract.py | 11 --- devcapsule-src/tests/conftest.py | 20 ++++- .../tests/test_capability_policy.py | 4 - .../tests/test_ide_requirement_override.py | 4 - devcapsule-src/tests/test_owner_commands.py | 4 - devcapsule-src/tests/test_trust.py | 4 - .../devcapsule/commands/test_launch_review.py | 36 +++++++++ .../configuration/test_authorization.py | 81 ++++++++++++++++++- .../test_environment_realization.py | 35 -------- .../legacy_refactoring/test_project_init.py | 40 --------- .../tests/unit/tests/test_conftest.py | 12 +++ engineering-docs/development/unit-tests.md | 14 +++- 15 files changed, 157 insertions(+), 133 deletions(-) delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/environment_realization.py delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/project_init.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_environment_realization.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_project_init.py diff --git a/devcapsule-src/devcapsule/legacy_refactoring/environment_realization.py b/devcapsule-src/devcapsule/legacy_refactoring/environment_realization.py deleted file mode 100644 index 446daa41..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/environment_realization.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_environment_realization.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_environment_realization.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/devcapsule/legacy_refactoring/project_init.py b/devcapsule-src/devcapsule/legacy_refactoring/project_init.py deleted file mode 100644 index e61e042e..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/project_init.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_project_init.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_project_init.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/tests/command_line_debt.txt b/devcapsule-src/tests/command_line_debt.txt index 9d3ae10b..845a490c 100644 --- a/devcapsule-src/tests/command_line_debt.txt +++ b/devcapsule-src/tests/command_line_debt.txt @@ -9,5 +9,4 @@ tests/unit/devcapsule/commands/test_images.py tests/unit/devcapsule/configuration/test_owner_commands.py tests/unit/devcapsule/configuration/test_storage.py -tests/unit/devcapsule/legacy_refactoring/test_project_init.py tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/devcapsule-src/tests/configuration/test_contract.py b/devcapsule-src/tests/configuration/test_contract.py index 25d394f4..74bc78c8 100644 --- a/devcapsule-src/tests/configuration/test_contract.py +++ b/devcapsule-src/tests/configuration/test_contract.py @@ -47,17 +47,6 @@ pytestmark = pytest.mark.legacy -@pytest.fixture(autouse=True) -def named_home(tmp_path, monkeypatch): - """Name each test's home, before the imported ``checkout`` fixture places the record in it. - - A home that is only implied by HOME and the XDG variables, with no settings of its own yet, reads the - launcher's mounted settings when the suite runs inside a capsule, and then what the developer accepted - there answers the consents these tests expect to be pending. - """ - monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) - - def declare_values(project, extra=''): path = project / '.devcapsule/devcapsule.toml' path.write_text(path.read_text() + ''' diff --git a/devcapsule-src/tests/conftest.py b/devcapsule-src/tests/conftest.py index 644ee43f..519203bc 100644 --- a/devcapsule-src/tests/conftest.py +++ b/devcapsule-src/tests/conftest.py @@ -154,9 +154,13 @@ def inherited_cache_home() -> Path: return Path(os.environ.get("XDG_CACHE_HOME") or Path(os.environ.get("HOME", "~")).expanduser() / ".cache") +CAPSULE_PATHS = ("CONTEXT_PATH", "CHANNEL_PATH") +"""The names in ``devcapsule.runtime_configuration`` of the fixed paths by which the product knows it is in a capsule.""" + + @pytest.fixture(autouse=True) def private_user_directories(request: pytest.FixtureRequest, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: - """Give non-Docker tests private user-directory paths under their tmp_path. + """Give non-Docker tests private user-directory paths under their tmp_path, on a machine that is no capsule. Override HOME and each XDG directory: changing HOME alone leaves exported XDG paths active. This keeps artifact retention and restoration, config, @@ -165,6 +169,14 @@ def private_user_directories(request: pytest.FixtureRequest, tmp_path: Path, mon real artifact cache. A test or function-scoped fixture can set its own paths after this autouse fixture runs. Leave directory creation to the tested code so refusal tests can still assert that nothing was written. + + The suite is often run inside a capsule. There the product finds the + launch's context and its configuration channel at two fixed paths, and a + home with no settings of its own then reads the launcher's settings, + mounted beside them: what the developer has accepted would answer the + consents a test expects to be pending. So both paths are moved to places + that do not exist, and the test runs as on a plain host. A test of the + capsule's side builds its own capsule by setting them after this fixture. """ if any(request.node.get_closest_marker(marker) for marker in DOCKER_MARKERS): @@ -188,6 +200,12 @@ def private_user_directories(request: pytest.FixtureRequest, tmp_path: Path, mon ("XDG_RUNTIME_DIR", "runtime"), ): monkeypatch.setenv(variable, str(tmp_path / "user" / leaf)) + # The product reads these two as attributes of the module at each call, so setting them here reaches every + # reader. HOME_PATH stays: it is read only once CONTEXT_PATH is found, and it is also the place where the + # launcher mounts the settings in a capsule that it starts, which tests of the launcher expect unchanged. + from devcapsule import runtime_configuration + for name in CAPSULE_PATHS: + monkeypatch.setattr(runtime_configuration, name, tmp_path / "no-capsule" / name.lower()) @pytest.fixture diff --git a/devcapsule-src/tests/test_capability_policy.py b/devcapsule-src/tests/test_capability_policy.py index 0934887e..d5b21f4a 100644 --- a/devcapsule-src/tests/test_capability_policy.py +++ b/devcapsule-src/tests/test_capability_policy.py @@ -38,10 +38,6 @@ def declaration(**capabilities: Any) -> dict[str, Any]: @pytest.fixture def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) - # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its - # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the - # developer accepted there answers the consents these tests expect to be pending. - monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" (root / ".devcapsule").mkdir(parents=True) manifest = declaration(need=["python", "python-ide"]) diff --git a/devcapsule-src/tests/test_ide_requirement_override.py b/devcapsule-src/tests/test_ide_requirement_override.py index 754bd2f6..44c6393e 100644 --- a/devcapsule-src/tests/test_ide_requirement_override.py +++ b/devcapsule-src/tests/test_ide_requirement_override.py @@ -49,10 +49,6 @@ def shared_bytes(root: Path) -> dict[str, bytes]: def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME"): monkeypatch.setenv(key, str(tmp_path / key.lower())) - # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its - # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the - # developer accepted there answers the consents these tests expect to be pending. - monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) return tmp_path diff --git a/devcapsule-src/tests/test_owner_commands.py b/devcapsule-src/tests/test_owner_commands.py index 19dbd0c0..a52d30e3 100644 --- a/devcapsule-src/tests/test_owner_commands.py +++ b/devcapsule-src/tests/test_owner_commands.py @@ -47,10 +47,6 @@ def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: """A project in the required form, created by init without an IDE.""" monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config")) monkeypatch.setenv("HOME", str(tmp_path / "home")) - # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its - # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the - # developer accepted there answers the consents these tests expect to be pending. - monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" root.mkdir() assert cli.main(["project", "--path", str(root), "init", "--require", "python", "--creator", "mailto:owner@example.test"]) == 0 diff --git a/devcapsule-src/tests/test_trust.py b/devcapsule-src/tests/test_trust.py index 6480d759..85230ca6 100644 --- a/devcapsule-src/tests/test_trust.py +++ b/devcapsule-src/tests/test_trust.py @@ -30,10 +30,6 @@ def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"): monkeypatch.setenv(key, str(tmp_path / key.lower())) - # Name the home. A home that is only implied by HOME and the XDG variables, with no settings of its - # own yet, reads the launcher's mounted settings when the suite runs inside a capsule, and then what the - # developer accepted there answers the consents these tests expect to be pending. - monkeypatch.setenv("DEVCAPSULE_CONFIG_HOME", str(tmp_path / "devcapsule-home")) root = tmp_path / "project" root.mkdir() assert cli.main(["project", "--path", str(root), "init", "--require", "node", "--creator", "mailto:owner@example.test"]) == 0 diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index d356efec..87e012ff 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -543,3 +543,39 @@ def test_with_no_provider_chosen_the_same_saving_launch_is_planned_with_the_defa assert review.selected.resolution["runtime"]["component"] == "codium" assert memory_size_bytes(str(review.record.values["memory"])) == 6 * 1024 ** 3 + + +def adding_claude_code() -> CheckoutState: + """The order's checkout after its developer added the Claude Code agent, which the project neither requires nor offers.""" + state = checkout_of(REQUIRING_PYCHARM) + selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) + selection.extra.add("claude-code-agent") + state.checkout = state.with_selection(selection) + return state + + +def test_an_agent_the_developer_added_waits_for_its_vendors_channel_and_names_both_ways_to_accept() -> None: + """An agent added on the checkout brings its vendor's channel with it: the launch ends pending on Anthropic's, + and the message names the flag for this launch and the ``home trust accept`` command.""" + with pytest.raises(DecisionPending) as pending: + review_launch(adding_claude_code(), RunFlags(), ask=None, announce=never_announced) + + message = str(pending.value) + assert "trust claude-code: Trust Anthropic to supply Claude Code" in message + assert "--trust claude-code | devcapsule home trust accept claude-code" in message + + +def test_the_checkouts_own_authorization_of_a_vendors_download_settles_it_without_the_home() -> None: + """When the checkout's record authorizes the Claude Code download itself, the launch is planned with Claude + Code in its lock. No channel is accepted for the home, and the home's settings are as they were.""" + state = adding_claude_code() + record = CheckoutRecord.staged(RECORD, state.checkout) + download = authorization_declarations(state.manifest, state.composed_lock())["claude-code-download"] + record.authorize(download, normalize_authorization_value(download, "true")) + state.checkout = record.export() + + review = review_launch(state, RunFlags(), ask=None, announce=never_announced) + + assert review.selected.lock["components"]["claude-code"]["version"] + assert review.accepted == [] + assert review.state.home == {} diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py index 92f49bda..faf4c1ca 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py @@ -8,8 +8,10 @@ from typing import Any -from devcapsule.configuration.authorization import authorization_declarations +from devcapsule.components.claude_code import CLAUDE_CODE_AUTHORIZATION, CLAUDE_CODE_TERMS_URL +from devcapsule.configuration.authorization import AuthorizationReview, authorization_declarations, review_authorizations from devcapsule.configuration.file_formats import canonical_digest +from devcapsule.configuration.trust import HomeTrust, channels_for from devcapsule.images.contract import LEGACY_RECIPE_SOURCE_PATH, RECIPE_SOURCE_PATH, REPOSITORY REFERENCE = "registry.example.test/devcapsule/base@sha256:" + "ab" * 32 @@ -67,3 +69,80 @@ def test_a_lock_without_a_base_declares_no_base_image_decision() -> None: """Precondition: a lock with no base table. Action: build the declarations. Postcondition: there is no base-image declaration to answer.""" assert "base-image" not in authorization_declarations({}, {"components": {}}) + + +def _lock_with_claude_code() -> dict[str, Any]: + """A platform lock that pins Claude Code, downloaded from its vendor, on the base at ``REFERENCE``.""" + lock = _lock() + lock["platform"] = "linux-amd64" + lock["components"]["claude-code"] = { + "version": "2.1.227", "delivery-policy": "local-materialization", + "acquisition-authorization": CLAUDE_CODE_AUTHORIZATION, "terms-url": CLAUDE_CODE_TERMS_URL, + "artifacts": {"linux-amd64": {"url": "https://downloads.claude.ai/example/claude", "sha256": "c" * 64}}, + } + return lock + + +def _checkout_answering(lock: dict[str, Any], download: bool | None) -> dict[str, Any]: + """A checkout record that authorizes the lock's base, and answers the Claude Code download unless ``download`` is None.""" + authorization: dict[str, Any] = {"base-image": {"reference": REFERENCE, "lock-digest": canonical_digest(lock)}} + if download is not None: + digest = authorization_declarations({}, lock)[CLAUDE_CODE_AUTHORIZATION].recommendation_digest + authorization[CLAUDE_CODE_AUTHORIZATION] = {"value": download, "recommendation-digest": digest} + return {"authorization": authorization} + + +def _trusting_every_channel_of(lock: dict[str, Any]) -> HomeTrust: + """The trust record of a home whose user accepted each channel the lock's software comes through.""" + trust = HomeTrust() + for channel in channels_for(lock).values(): + trust = trust.with_channel(channel) + return trust + + +def _download_review(lock: dict[str, Any], checkout: dict[str, Any], trust: HomeTrust) -> AuthorizationReview: + """The review of the Claude Code download among all the reviews of the checkout.""" + (review,) = (item for item in review_authorizations({}, lock, checkout, trust) if item.name == CLAUDE_CODE_AUTHORIZATION) + return review + + +def test_a_vendor_download_that_neither_the_home_nor_the_checkout_answered_stops_the_launch() -> None: + """With Claude Code in the lock, a home that trusts no channel and a checkout that says nothing of the + download, the review of the download is unanswered and carries a problem: the environment cannot run.""" + lock = _lock_with_claude_code() + + review = _download_review(lock, _checkout_answering(lock, download=None), HomeTrust()) + + assert (review.status, review.recorded, review.trusted_channel) == ("missing-required", "unanswered", None) + assert review.problem is not None and "An explicit decision is required" in review.problem + + +def test_a_vendor_download_is_answered_by_the_home_that_trusts_its_channel() -> None: + """The same checkout under a home that accepted Anthropic's channel has the download answered by the + home: no problem, and the review names the channel.""" + lock = _lock_with_claude_code() + + review = _download_review(lock, _checkout_answering(lock, download=None), _trusting_every_channel_of(lock)) + + assert (review.status, review.recorded, review.trusted_channel, review.problem) == ("trusted", "home", "claude-code", None) + + +def test_a_checkouts_denial_of_a_vendor_download_outranks_the_homes_trust() -> None: + """A checkout that recorded a denial of the download keeps it under a home that trusts the channel: the + review is a denial with a problem, and the home's channel does not answer it.""" + lock = _lock_with_claude_code() + + review = _download_review(lock, _checkout_answering(lock, download=False), _trusting_every_channel_of(lock)) + + assert (review.status, review.trusted_channel) == ("denied", None) + assert review.problem is not None and "The selected Claude Code acquisition is denied" in review.problem + + +def test_a_checkouts_own_grant_answers_a_vendor_download_under_a_home_that_trusts_nothing() -> None: + """A checkout that recorded its own grant of the download needs no channel accepted for the home: the + review is authorized, with no problem.""" + lock = _lock_with_claude_code() + + review = _download_review(lock, _checkout_answering(lock, download=True), HomeTrust()) + + assert (review.status, review.value, review.problem) == ("authorized", True, None) diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_environment_realization.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_environment_realization.py deleted file mode 100644 index 982bdd63..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_environment_realization.py +++ /dev/null @@ -1,35 +0,0 @@ -"""Legacy tests of ``tests/test_environment_realization.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/environment_realization.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -from pathlib import Path -from unittest.mock import Mock -import pytest -from devcapsule.compat import CliError -from devcapsule.environment_realization import realize_environment -from tests.test_environment_realization import resolved_project, select_claude_code -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_realize_environment_requires_explicit_claude_download_authorization( - tmp_path: Path, -) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - selected = resolved_project(tmp_path) - select_claude_code(selected, authorized=False) - obtain = Mock() - materialize = Mock() - - with pytest.raises(CliError, match="claude-code-download"): - realize_environment(selected, obtain_image=obtain, materialize=materialize) - - obtain.assert_not_called() - materialize.assert_not_called() diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_project_init.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_project_init.py deleted file mode 100644 index f91d5668..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_project_init.py +++ /dev/null @@ -1,40 +0,0 @@ -"""Legacy tests of ``tests/test_project_init.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/project_init.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -from tests.launch_preparation import run_until_prepared -import os -from pathlib import Path -from unittest.mock import patch -import pytest -from devcapsule import cli -from tests.test_project_init import full_init_command, isolated_env, read_toml -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_a_selected_agent_brings_its_own_acquisition_gate(tmp_path: Path, capsys) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - project = tmp_path / "fresh-project" - project.mkdir() - with patch.dict(os.environ, isolated_env(tmp_path), clear=False): - assert cli.main(full_init_command(project)) == 0 - capsys.readouterr() - - # The agent is the developer's; resolving without its vendor's channel names the channel (D-0011). - assert cli.main(["project", "--path", str(project), "config", "add", "claude-code-agent"]) == 0 - assert run_until_prepared(project) == 3 - assert "home trust accept claude-code" in capsys.readouterr().err - - assert cli.main(["project", "--path", str(project), "config", "authorize", "claude-code-download", "true"]) == 0 - assert run_until_prepared(project) == 0 - from devcapsule.configuration.storage import lock_for - lock = lock_for(project, read_toml(project / ".devcapsule" / "devcapsule.toml"))[1] - assert lock["components"]["claude-code"]["version"] diff --git a/devcapsule-src/tests/unit/tests/test_conftest.py b/devcapsule-src/tests/unit/tests/test_conftest.py index 8ee4fb81..d62a8a1d 100644 --- a/devcapsule-src/tests/unit/tests/test_conftest.py +++ b/devcapsule-src/tests/unit/tests/test_conftest.py @@ -330,3 +330,15 @@ def test_the_network_guard_in_force_is_not_replaced_by_a_later_one() -> None: another returns the one in force: an audit hook cannot be removed, so a process keeps its first.""" in_force = install_network_guard(NetworkGuard()) assert install_network_guard(NetworkGuard()) is in_force + + +def test_a_test_runs_on_no_capsule_wherever_the_suite_runs(tmp_path: Path) -> None: + """Under the suite's fixture, each fixed path by which the product knows a capsule lies under the test's own + directory and does not exist. So the product finds no launcher's settings to read, in a capsule as on a + plain host.""" + from devcapsule import runtime_configuration + + for name in conftest.CAPSULE_PATHS: + path = getattr(runtime_configuration, name) + assert path.is_relative_to(tmp_path) and not path.exists(), name + assert runtime_configuration.mounted_settings_path() is None diff --git a/engineering-docs/development/unit-tests.md b/engineering-docs/development/unit-tests.md index 3957b07a..dd0cf5e4 100644 --- a/engineering-docs/development/unit-tests.md +++ b/engineering-docs/development/unit-tests.md @@ -174,10 +174,16 @@ so prefer the existing laws and an acceptance step for what the user sees. stays open. Tests of the heavier suites are not held to it. It cannot see the network use of a program a test starts. - `private_user_directories`, autouse: moves `HOME` and every XDG directory - under the test's `tmp_path` for non-Docker tests. Inside a capsule this is - not yet a private home: a home with no settings of its own reads the - launcher's mounted settings, so tests that assume no accepted vendor - channel fail there. Recorded on 2026-11-03 for the 0.3.1 fixture slice. + under the test's `tmp_path` for non-Docker tests, and makes the test's + machine no capsule. The product knows a capsule by two fixed paths, the + launch context and the configuration channel, `CONTEXT_PATH` and + `CHANNEL_PATH` of `devcapsule.runtime_configuration`; the fixture sets + both to places that do not exist. So a test's home is private inside a + capsule too: it does not read the launcher's mounted settings, and a + command does not read the live channel. A test of the capsule's side + builds its own capsule by setting the paths after the fixture. The + fixture does not reach a program that a test starts; such a test builds + that program's environment, with a named home. - `built_pex`: the executable under test, `DEVCAPSULE_PEX_UNDER_TEST` when set, otherwise `dist/devcapsule-local.pex`; it fails with the Nox session to run when the file is missing. The integration and end-to-end suites use From cd786959bfe245188c5c2a3bf1fa4796f1046324 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 23:25:53 +0000 Subject: [PATCH 50/75] Records: the shared fixture fixed; what still keeps the mounted-settings bug open Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 48 +++++++++++++++---- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 39 +++++++++++++++ 3 files changed, 79 insertions(+), 10 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 1b98ce2a..3641bb9a 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -229,15 +229,45 @@ What changed is that the tests which failed now say what their home is. - `nox -s tests` passes inside the owner's capsule: 3105 passed, 3 expected to fail, 10 unexpectedly passed, in 170 seconds where it took 815. -Against the close criteria: 1 holds for the owner's capsule as it is today. -2 and 3 do not. Eight marks remain, on 11 cases, in four files. Nine -cases pass now. Two still fail inside the capsule for this cause, behind -their mark, because they take fixtures from legacy files that were not -changed: one in `test_environment_realization.py`, one in -`test_project_init.py`. They are in mirror files whose legacy twins stand, -so the gate refuses a change to them until those twins are retired; it -accepts the deletion of a whole holding-pen file whose tests are rewritten -elsewhere. 4 does not hold: +- The shared fixture is fixed. `private_user_directories` sets the two + fixed paths by which the product knows a capsule, `CONTEXT_PATH` and + `CHANNEL_PATH` of `devcapsule.runtime_configuration`, to places that do + not exist, so no test of the unit suite sees the capsule it runs in. The + lever queued on 2026-11-03, naming the home, was tried with a diagnostic + plugin and breaks 31 tests that assert the home's layout. A test of the + conftest holds the fixture; with the fixture's lines removed, that test + and the seven command-line tests fail inside the capsule. The five + per-file fixtures that named the home are removed again: one mechanism. + The ten calls that hand in `home={}` stay; they are values. +- The last two cases that still failed behind a mark are rewritten in + memory and their holding-pen files deleted: four tests of + `review_authorizations` in the authorization mirror, two of the launch + review. +- `nox -s tests` inside the owner's capsule: 3112 passed, 1 expected to + fail, 10 unexpectedly passed, in 146 seconds. With the marks ignored, + 3122 pass and one fails, a workflow test with a mark of its own. + +Against the close criteria: + +1. Holds, for the owner's capsule as it is today. +2. Does not hold yet. Every outcome is now the same as on the hosted run + but for nine cases that pass behind a mark which applies only inside a + capsule, so the counts differ by nine. +3. Does not hold yet. Six marks remain, on those nine cases, in two + holding-pen files: five in `test_trust.py`, whose stated reason is the + mounted settings, and one in `test_home.py`, a walk of the repository + for a retired word, another cause. Their legacy twins stand, so the + gate refuses the removal of a mark; each file goes when its tests are + rewritten elsewhere or judged not worth keeping. +4. Holds: `engineering-docs/development/unit-tests.md` describes the + fixture as a private home on a machine that is no capsule. + +No unit test opens a network connection: the guard records none. + +Outside the unit suite, one integration test still reads the mounted +settings, `tests/integration/test_pex_runtime.py::test_built_pex_authors_shared_policy_and_keeps_personal_selection_local`: +it starts the built launcher with the environment of the test process, +which inside a capsule names no home. 4 does not hold: `private_user_directories` is unchanged, and a test that uses neither a named home nor a handed-in one still reads the mount. The next channel the developer accepts can turn other tests red. diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 18167ef0..1b31be36 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture and 8 marks, on 11 cases of which 2 still fail for this cause, are still to do | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture is fixed there too, so no unit test sees the capsule it runs in; 6 stale marks on 9 passing cases, in two holding-pen files, are still to do | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 0e41c9e5..73eb2387 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -205,6 +205,45 @@ capsule: 3095 passed, 9 expected to fail, 10 unexpectedly passed. The integration tests that need no Docker: 128 passed, 3 skipped, and the one standing failure. +**The shared fixture fixed and the last two failing marked cases +rewritten, 2026-11-12.** Owner direction: go at the first item of the +debt list. + +- `private_user_directories` in `tests/conftest.py` now makes the test's + machine no capsule: it sets `CONTEXT_PATH` and `CHANNEL_PATH` of + `devcapsule.runtime_configuration` to places that do not exist. The + product reads both as attributes of the module at each call. `HOME_PATH` + is left: it is read only behind `CONTEXT_PATH`, and it is also where the + launcher mounts the settings in a capsule it starts, which a launcher + test expects unchanged; setting it failed that test. Naming the home in + the fixture instead breaks 31 tests that assert the layout. +- The five per-file fixtures that named the home, added earlier the same + day, are removed: one mechanism. The ten `home={}` calls stay. +- `test_realize_environment_requires_explicit_claude_download_authorization` + became four tests of `review_authorizations`, where the decision is + taken, in `tests/unit/devcapsule/configuration/test_authorization.py`: + unanswered, answered by the home's trust, denied by the checkout over + the home's trust, granted by the checkout alone. It could not go to the + mirror of `environment_realization.py`: the legacy twin stands, and + retiring it breaks `tests/test_trust.py`, one of whose tests imports a + helper from it. That `realize_environment` refuses before it obtains + anything is still held by the legacy test of the base authorization. +- `test_a_selected_agent_brings_its_own_acquisition_gate` became two tests + of the launch review: an added agent waits for its vendor's channel and + the message names both ways to accept; the checkout's own authorization + of the download settles it without the home. +- Both holding-pen files and their empty target modules are deleted; the + command-line debt list has 4 files. +- Five planted faults are each caught. With the fixture's lines removed, + its own test and the seven command-line tests fail in the capsule. +- `nox -s typecheck tests` in the capsule: 3112 passed, 1 expected to + fail, 10 unexpectedly passed, 146 seconds. + +The blocking bug stays `fixing`. What is left is six stale marks on nine +passing cases in two holding-pen files, `test_trust.py` (five tests that +drive the command line) and `test_home.py` (a walk of the repository for a +retired word). The owner decides whether the second is worth keeping. + **The two `test_repository_manifest_compatibility.py` files, replaced by one, 2026-11-12.** Owner direction: delete what tests nothing real, consolidate the rest in one properly written file. From 8af31910967b0dfafdeef362f4d2ee89ad9fdd8f Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Thu, 12 Nov 2026 23:56:12 +0000 Subject: [PATCH 51/75] Tests: the holding pen is empty; the trust tests rewritten in memory, as processes and on a terminal The five marked tests of tests/unit/devcapsule/legacy_refactoring/test_trust.py drove the command line and patched the upgrade offer. They are now: - in memory, the launch review: an unaccepted base channel is pending and names --trust; the flag accepts for the home and plans the published base; a home that trusts plans without a question; the flag beside another unanswered decision still ends pending; a channel the project does not use is refused; a channel is accepted as the checkout's saved version set names it, by flag and by question; the flags of the second review after an upgrade; a channel an upgrade moved is pending there and the acceptance is not widened; - in memory, the review of authorizations: an artifact moved to another origin is not covered, another version from the same origin is; - in memory, the trust listing: not yet, trusted, not covered with what was accepted, accepted and not used by the checkout; - as processes, tests/integration/test_home_trust_cli.py: accept settles the pending base, withdraw asks again, and on a pseudo-terminal a developer who answers no is told how to accept later and nothing is recorded; in test_print_command_cli.py, printing with --trust records no acceptance. Two extractions in the product, behaviour unchanged: the rows and lines of 'config trust list' move from the command class to configuration/trust_listing.py, and the flags of the second review become flags_after_upgrade in the launch review module. The one marked test of test_home.py, a walk of the repository for a retired word, is deleted on the owner's word. With its reader gone the Python route's input 'docs/**' narrows to docs/versions.yaml, and the routing table of the workflow test follows. The holding pen and its package of empty target modules are removed; the command-line debt list has 3 files. Evidence: twelve planted faults each caught; nox -s typecheck tests in the capsule, 3129 passed, 1 expected to fail, 1 unexpectedly passed, no mark that depends on the capsule; integration tests that need no Docker, 132 passed, 3 skipped, 1 standing failure. Co-Authored-By: Claude --- .github/ci-python-inputs.yml | 3 +- .../devcapsule/commands/_launch_review.py | 25 ++- devcapsule-src/devcapsule/commands/project.py | 38 +--- .../devcapsule/configuration/trust_listing.py | 53 ++++++ .../devcapsule/legacy_refactoring/__init__.py | 1 - .../devcapsule/legacy_refactoring/home.py | 12 -- .../devcapsule/legacy_refactoring/trust.py | 12 -- devcapsule-src/tests/command_line_debt.txt | 1 - .../tests/integration/test_ci_workflow.py | 2 +- .../tests/integration/test_home_trust_cli.py | 168 ++++++++++++++++++ .../integration/test_print_command_cli.py | 18 ++ .../devcapsule/commands/test_launch_review.py | 159 ++++++++++++++++- .../configuration/test_authorization.py | 26 +++ .../configuration/test_trust_listing.py | 90 ++++++++++ .../devcapsule/legacy_refactoring/__init__.py | 0 .../legacy_refactoring/test_home.py | 38 ---- .../legacy_refactoring/test_trust.py | 157 ---------------- 17 files changed, 538 insertions(+), 265 deletions(-) create mode 100644 devcapsule-src/devcapsule/configuration/trust_listing.py delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/__init__.py delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/home.py delete mode 100644 devcapsule-src/devcapsule/legacy_refactoring/trust.py create mode 100644 devcapsule-src/tests/integration/test_home_trust_cli.py create mode 100644 devcapsule-src/tests/unit/devcapsule/configuration/test_trust_listing.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/__init__.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_home.py delete mode 100644 devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/.github/ci-python-inputs.yml b/.github/ci-python-inputs.yml index 2f6f55e4..a3208a34 100644 --- a/.github/ci-python-inputs.yml +++ b/.github/ci-python-inputs.yml @@ -19,6 +19,5 @@ python: # Each entry leaves when its reader builds its own input. - '.devcapsule/**' # tests/test_base_contract.py - 'component-status/**' # tests/test_component_status.py - - 'docs/**' # the [docs] case of tests/unit/devcapsule/legacy_refactoring/test_home.py walks all of docs/; - # tests/test_release_docs.py reads docs/versions.yaml + - 'docs/versions.yaml' # tests/test_release_docs.py - 'engineering-docs/releases/v0.2.14/notes.md' # tests/test_release_docs.py diff --git a/devcapsule-src/devcapsule/commands/_launch_review.py b/devcapsule-src/devcapsule/commands/_launch_review.py index 43c31750..f25a96ba 100644 --- a/devcapsule-src/devcapsule/commands/_launch_review.py +++ b/devcapsule-src/devcapsule/commands/_launch_review.py @@ -26,13 +26,15 @@ from __future__ import annotations from copy import deepcopy -from dataclasses import dataclass, field +from dataclasses import dataclass, field, replace from pathlib import Path import shlex from typing import Any, Callable, Mapping from devcapsule.compat import DecisionPending -from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value +from devcapsule.configuration.authorization import ( + authorization_declarations, normalize_authorization_value, render_authorization_value, +) from devcapsule.configuration.capabilities import ( IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture, capability_notes, ) @@ -48,7 +50,8 @@ __all__ = [ "BLOCKING_KINDS", "Ask", "LaunchReview", "Prepared", "RunFlags", "capability", "channel_for", - "refuse_contradictory_flags", "render_pending", "requested_ide", "review_launch", "stage_trust", + "flags_after_upgrade", "refuse_contradictory_flags", "render_pending", "requested_ide", "review_launch", + "stage_trust", ] BLOCKING_KINDS = {"ide", "env", "renew", "trust", "consent", "value", "secret"} @@ -132,6 +135,22 @@ def prepared(self) -> Prepared: """ +def flags_after_upgrade(flags: RunFlags, host_overrides: Mapping[str, Any]) -> RunFlags: + """The flags of a launch's second review, made after an upgrade may have changed what the checkout selects. + + The first review is complete and written. Saved flags are in the record + now, so they are not given again; flags for this launch only are, and with + them the host accesses that the developer allowed once at the terminal, + ``host_overrides``. ``--trust`` is never given again: it accepted the + channel that the first review showed, and an upgrade can change a + channel. A channel that changed is then a pending decision. + """ + again = RunFlags(allow_unverified=flags.allow_unverified) if flags.save else flags + return replace(again, save=False, trust=(), authorize=tuple( + (name, render_authorization_value(value)) for name, value in host_overrides.items() + )) + + def refuse_contradictory_flags(flags: RunFlags) -> None: """Refuse a command line that contradicts itself. It needs nothing but the flags.""" if flags.force and flags.ide is None: diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index cf383610..1bff5ffa 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -37,6 +37,7 @@ from devcapsule.components.catalog import COMPONENTS from devcapsule.commands._versions import VersionsGroup from devcapsule.commands._upgrade_prompt import offer_upgrades +from devcapsule.commands._launch_review import flags_after_upgrade from devcapsule.commands._run_flow import RunFlags, launch_listing_document, load_launch_state, prepare_launch from devcapsule.display_client import has_contained_display from devcapsule.commands._software_approvals import ( @@ -1304,37 +1305,17 @@ def run(cls, arguments: argparse.Namespace, context: object | None) -> int: from devcapsule.configuration.derivation import load_state from devcapsule.configuration.storage import load_trust, settings_path from devcapsule.configuration.trust import HomeTrust, channels_for + from devcapsule.configuration.trust_listing import render_trust_rows, trust_rows root, manifest = manifest_for(_project_context(context).start_path()) lock = load_state(root, manifest).composed_lock() - trust = HomeTrust.read(load_trust()) - channels = channels_for(lock) - rows: list[dict[str, Any]] = [ - {"channel": channel.id, "vendor": channel.vendor, "product": channel.product, - "origins": list(channel.origins), "terms-url": channel.terms_url, - "integrity": channel.integrity, "accepted": trust.channels.get(channel.id), - "trusted": trust.covers(channel), "note": channel.note} for channel in channels.values()] - for channel_id, entry in trust.channels.items(): - if channel_id not in channels: - rows.append({"channel": channel_id, "vendor": entry["vendor"], "product": "", "origins": entry["origins"], - "terms-url": entry["terms-url"], "integrity": entry["integrity"], "accepted": entry, - "trusted": bool(entry["integrity"]), "note": "not used by this checkout"}) + rows = trust_rows(channels_for(lock), HomeTrust.read(load_trust())) if arguments.as_json: print(json.dumps({"schema-version": 1, "path": str(settings_path()), "channels": rows}, indent=2, sort_keys=True)) return 0 print(f"Trust record: {settings_path()}") print(f"Scope: this DevCapsule home, {config_root()}. Anyone who uses this home uses this acceptance.") - for row in rows: - state = "trusted" if row["trusted"] else ("not covered" if row["accepted"] else "not yet") - origins = ", ".join(str(item) for item in row["origins"]) or "the lock" - terms = f"; terms {row['terms-url']}" if row["terms-url"] else "" - print(f"{row['channel']:<18} {state:<11} {row['vendor']} — {row['product'] or '(not used by this checkout)'}; " - f"from {origins}; integrity {row['integrity'] or 'not recorded'}{terms}") - if row["accepted"] and not row["trusted"]: - entry = row["accepted"] - print(f"{'':<18} Accepted origins: {', '.join(entry['origins'])}; " - f"integrity {entry['integrity'] or 'not recorded'}; terms {entry['terms-url'] or 'none'}") - if row["note"]: - print(f"{'':<18} {row['note']}") + for line in render_trust_rows(rows): + print(line) return 0 @@ -2244,14 +2225,7 @@ def _run(cls, arguments: argparse.Namespace, context: object | None, return 1 # An upgrade may have changed the selection: derive again from the record. if command_report is None: - # Saved flags are now record inputs. Reapply only launch overrides, - # including terminal "once" answers, when checking the new selection. - again = RunFlags(allow_unverified=flags.allow_unverified) if flags.save else flags - # Trust accepted the channel shown in the first review. Never - # replay that acceptance against a different channel after an upgrade. - again = replace(again, save=False, trust=(), authorize=tuple( - (name, render_authorization_value(value)) for name, value in prepared.host_overrides.items() - )) + again = flags_after_upgrade(flags, prepared.host_overrides) prepared.selected = prepare_launch(start, again, interactive=False).selected selected = prepared.selected review = review_configuration(selected.manifest, selected.lock, selected.checkout, diff --git a/devcapsule-src/devcapsule/configuration/trust_listing.py b/devcapsule-src/devcapsule/configuration/trust_listing.py new file mode 100644 index 00000000..a43a3d61 --- /dev/null +++ b/devcapsule-src/devcapsule/configuration/trust_listing.py @@ -0,0 +1,53 @@ +"""What ``project config trust list`` shows: each channel of a checkout against the home's trust record. + +Pure: the command reads the lock and the home, and prints. The rows are +also the ``channels`` array of the command's JSON document, so their keys +are a stable interface. +""" + +from __future__ import annotations + +from typing import Any, Mapping + +from .trust import Channel, HomeTrust + +__all__ = ["render_trust_rows", "trust_rows"] + + +def trust_rows(channels: Mapping[str, Channel], trust: HomeTrust) -> list[dict[str, Any]]: + """One row per channel of the checkout's lock, then one per accepted channel that the lock does not use. + + ``trusted`` says whether the home's acceptance covers the channel as the + lock names it now. ``accepted`` is the home's entry for the channel, or + None: a channel that is accepted and not trusted has left what was + accepted, by a new origin, other terms or another integrity method. + """ + rows: list[dict[str, Any]] = [ + {"channel": channel.id, "vendor": channel.vendor, "product": channel.product, + "origins": list(channel.origins), "terms-url": channel.terms_url, + "integrity": channel.integrity, "accepted": trust.channels.get(channel.id), + "trusted": trust.covers(channel), "note": channel.note} for channel in channels.values()] + for channel_id, entry in trust.channels.items(): + if channel_id not in channels: + rows.append({"channel": channel_id, "vendor": entry["vendor"], "product": "", "origins": entry["origins"], + "terms-url": entry["terms-url"], "integrity": entry["integrity"], "accepted": entry, + "trusted": bool(entry["integrity"]), "note": "not used by this checkout"}) + return rows + + +def render_trust_rows(rows: list[dict[str, Any]]) -> list[str]: + """The lines of the listing: a channel's state and channel, what was accepted when that no longer covers it, its note.""" + lines: list[str] = [] + for row in rows: + state = "trusted" if row["trusted"] else ("not covered" if row["accepted"] else "not yet") + origins = ", ".join(str(item) for item in row["origins"]) or "the lock" + terms = f"; terms {row['terms-url']}" if row["terms-url"] else "" + lines.append(f"{row['channel']:<18} {state:<11} {row['vendor']} — {row['product'] or '(not used by this checkout)'}; " + f"from {origins}; integrity {row['integrity'] or 'not recorded'}{terms}") + if row["accepted"] and not row["trusted"]: + entry = row["accepted"] + lines.append(f"{'':<18} Accepted origins: {', '.join(entry['origins'])}; " + f"integrity {entry['integrity'] or 'not recorded'}; terms {entry['terms-url'] or 'none'}") + if row["note"]: + lines.append(f"{'':<18} {row['note']}") + return lines diff --git a/devcapsule-src/devcapsule/legacy_refactoring/__init__.py b/devcapsule-src/devcapsule/legacy_refactoring/__init__.py deleted file mode 100644 index 914d0eda..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""Temporary target modules for legacy tests under refactoring; see each module's docstring. Deleted when empty.""" diff --git a/devcapsule-src/devcapsule/legacy_refactoring/home.py b/devcapsule-src/devcapsule/legacy_refactoring/home.py deleted file mode 100644 index 6b25bc8f..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/home.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_home.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_home.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/devcapsule/legacy_refactoring/trust.py b/devcapsule-src/devcapsule/legacy_refactoring/trust.py deleted file mode 100644 index cf32283c..00000000 --- a/devcapsule-src/devcapsule/legacy_refactoring/trust.py +++ /dev/null @@ -1,12 +0,0 @@ -"""Temporary target module while the legacy tests of ``tests/test_trust.py`` are refactored. - -This module serves only as the mirror target of -``tests/unit/devcapsule/legacy_refactoring/test_trust.py`` under *Unit Tests* -rule 1 of ``WORKFLOW-LOCAL.md``. It holds no code. The tests mirrored here are -the ones marked expected to fail on 2026-11-04 with the reason -``TODO: fix the wrong approach to testing``; each is rewritten against its -real unit as the maintenance workstream refactors it, and this module is -deleted when the last one leaves. -""" - -__all__: list[str] = [] diff --git a/devcapsule-src/tests/command_line_debt.txt b/devcapsule-src/tests/command_line_debt.txt index 845a490c..755bcfdb 100644 --- a/devcapsule-src/tests/command_line_debt.txt +++ b/devcapsule-src/tests/command_line_debt.txt @@ -9,4 +9,3 @@ tests/unit/devcapsule/commands/test_images.py tests/unit/devcapsule/configuration/test_owner_commands.py tests/unit/devcapsule/configuration/test_storage.py -tests/unit/devcapsule/legacy_refactoring/test_trust.py diff --git a/devcapsule-src/tests/integration/test_ci_workflow.py b/devcapsule-src/tests/integration/test_ci_workflow.py index 13d20136..b0d81277 100644 --- a/devcapsule-src/tests/integration/test_ci_workflow.py +++ b/devcapsule-src/tests/integration/test_ci_workflow.py @@ -60,7 +60,7 @@ def match(parts: list[str], segments: list[str]) -> bool: (".devcapsule/devcapsule.toml", True), ("component-status/policy-v1.json", True), ("docs/versions.yaml", True), - ("docs/guide.md", True), # walked by a legacy scan; see the filter file + ("docs/guide.md", False), ("engineering-docs/releases/v0.2.14/notes.md", True), ("engineering-docs/releases/v0.3.1/bugs.md", False), ("engineering-docs/pile-of-ideas/an-idea.md", False), diff --git a/devcapsule-src/tests/integration/test_home_trust_cli.py b/devcapsule-src/tests/integration/test_home_trust_cli.py new file mode 100644 index 00000000..793959c8 --- /dev/null +++ b/devcapsule-src/tests/integration/test_home_trust_cli.py @@ -0,0 +1,168 @@ +"""Integration tests of the home's trust as a developer meets it: real commands, and a real terminal. + +A channel is accepted once per home, and every command that asks about a +checkout reads that home. So these tests run the launcher as processes, in +an environment the test builds: a project created by ``project init``, and a +named home under the test's directory that has accepted nothing. The last +test puts the launch on a pseudo-terminal, because the launch asks only when +its input is a terminal. + +No command here needs Docker or the network: each ends before the launch +reaches either. +""" +from __future__ import annotations + +import json +import os +from pathlib import Path +import pty +import select +import subprocess +import sys +import time + +import pytest + +from devcapsule.configuration.storage import load_toml + +pytestmark = pytest.mark.integration + +ACCEPT_COMMAND = "devcapsule home trust accept devcapsule-base" + + +class Checkout: + """One project with a named home, and the launcher run on them as a process.""" + + def __init__(self, directory: Path) -> None: + self.project = directory / "project" + self.home = directory / "devcapsule-home" + self.project.mkdir() + self.environment = { + "PATH": os.defpath, "HOME": str(directory / "home"), "DEVCAPSULE_CONFIG_HOME": str(self.home), + "PYTHONDONTWRITEBYTECODE": "1", + } + + @property + def settings(self) -> Path: + """The home's settings file, which holds what the home trusts.""" + return self.home / "settings.toml" + + def launcher(self, *arguments: str) -> subprocess.CompletedProcess[str]: + """``devcapsule ARGUMENTS`` with no terminal; standard error is joined to standard output.""" + return subprocess.run( + [sys.executable, "-m", "devcapsule", *arguments], cwd=self.project, env=self.environment, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, timeout=300, check=False, + ) + + def project_command(self, *arguments: str) -> subprocess.CompletedProcess[str]: + """``devcapsule project ARGUMENTS`` for this project.""" + return self.launcher("project", "--path", str(self.project), *arguments) + + def at_a_terminal(self, answers: list[tuple[str, str]], *arguments: str) -> tuple[int, str]: + """Run ``devcapsule ARGUMENTS`` on a pseudo-terminal; return its exit status and all it showed. + + ``answers`` are the developer's, in order: each is typed when the + terminal's output ends with the prompt paired with it. + """ + terminal, launcher_side = pty.openpty() + process = subprocess.Popen( + [sys.executable, "-m", "devcapsule", *arguments], cwd=self.project, env=self.environment, + stdin=launcher_side, stdout=launcher_side, stderr=launcher_side, close_fds=True, + ) + os.close(launcher_side) + shown = b"" + waiting = list(answers) + deadline = time.monotonic() + 300 + try: + while time.monotonic() < deadline: + readable, _, _ = select.select([terminal], [], [], 0.2) + if readable: + try: + chunk = os.read(terminal, 4096) + except OSError: # Linux reports the launcher's closed side as an error, not as an empty read. + break + if not chunk: + break + shown += chunk + if waiting and shown.rstrip().endswith(waiting[0][0].encode()): + os.write(terminal, waiting.pop(0)[1].encode()) + elif process.poll() is not None: + break + status = process.wait(timeout=30) + finally: + if process.poll() is None: + process.kill() + os.close(terminal) + return status, shown.decode(errors="replace") + + +@pytest.fixture +def checkout(tmp_path: Path) -> Checkout: + """A project that requires Node, with PyCharm chosen on its checkout, in a home that has accepted nothing. + + The checkout has not authorized its base image, so the base is for the + home's trust of DevCapsule's channel to answer. + """ + checkout = Checkout(tmp_path) + created = checkout.project_command("init", "--require", "node", "--creator", "mailto:owner@example.test") + assert created.returncode == 0, created.stdout + chosen = checkout.project_command("config", "ide", "python-ide") + assert chosen.returncode == 0, chosen.stdout + return checkout + + +def test_accepting_the_base_channel_for_the_home_settles_the_checkouts_pending_base(checkout: Checkout) -> None: + """Before the acceptance ``config check`` exits 3 and names the command that accepts, and ``config trust + list`` shows the channel as not yet accepted in this home's settings file. ``home trust accept`` states what + is trusted and records it in that file. After it ``config check`` exits 0, ``config show`` gives the home's + trust as the source of the base, and the JSON listing shows the channel trusted.""" + pending = checkout.project_command("config", "check") + assert pending.returncode == 3 and ACCEPT_COMMAND in pending.stdout, pending.stdout + listed = checkout.project_command("config", "trust", "list") + assert listed.returncode == 0, listed.stdout + assert f"Trust record: {checkout.settings}" in listed.stdout + assert any(line.split()[:3] == ["devcapsule-base", "not", "yet"] for line in listed.stdout.splitlines()), listed.stdout + + accepted = checkout.launcher("home", "trust", "accept", "devcapsule-base", "--yes") + + assert accepted.returncode == 0, accepted.stdout + assert "Trust DevCapsule to supply the base images" in accepted.stdout + assert f"Recorded for this DevCapsule home: {checkout.settings}" in accepted.stdout + assert load_toml(checkout.settings)["trust"]["channels"]["devcapsule-base"]["vendor"] == "DevCapsule" + settled = checkout.project_command("config", "check") + assert settled.returncode == 0, settled.stdout + shown = checkout.project_command("config", "show") + assert shown.returncode == 0 and "home trust (devcapsule-base)" in shown.stdout, shown.stdout + as_json = checkout.project_command("config", "trust", "list", "--json") + assert as_json.returncode == 0, as_json.stdout + assert [(row["channel"], row["trusted"]) for row in json.loads(as_json.stdout)["channels"]] == [("devcapsule-base", True)] + + +def test_withdrawing_the_channel_leaves_the_base_pending_again_and_a_second_withdrawal_changes_nothing(checkout: Checkout) -> None: + """``home trust withdraw`` removes the acceptance from the home: ``config check`` exits 3 again. Withdrawing + a channel that is not accepted exits 0 and says so.""" + assert checkout.launcher("home", "trust", "accept", "devcapsule-base", "--yes").returncode == 0 + assert checkout.project_command("config", "check").returncode == 0 + + withdrawn = checkout.launcher("home", "trust", "withdraw", "devcapsule-base") + + assert withdrawn.returncode == 0 and "Withdrew devcapsule-base" in withdrawn.stdout, withdrawn.stdout + assert "devcapsule-base" not in load_toml(checkout.settings).get("trust", {}).get("channels", {}) + assert checkout.project_command("config", "check").returncode == 3 + again = checkout.launcher("home", "trust", "withdraw", "devcapsule-base") + assert again.returncode == 0 and "No acceptance recorded for devcapsule-base" in again.stdout, again.stdout + + +def test_a_developer_who_answers_no_at_the_terminal_is_told_how_to_accept_later_and_nothing_is_recorded(checkout: Checkout) -> None: + """``project run`` on a terminal asks whether to accept DevCapsule's channel for the home. Answered no, it + says how to accept later, ends with exit status 3 before anything is launched, and writes no settings file.""" + status, shown = checkout.at_a_terminal( + [("Accept for this DevCapsule home? [y/N]:", "n\n")], + "project", "--path", str(checkout.project), "run", "--no-update-check", + ) + + assert status == 3, shown + assert "Trust DevCapsule to supply the base images" in shown + assert f"Not accepted. Accept later: {ACCEPT_COMMAND}" in shown + assert "Nothing was written." in shown + assert not checkout.settings.exists() diff --git a/devcapsule-src/tests/integration/test_print_command_cli.py b/devcapsule-src/tests/integration/test_print_command_cli.py index fad8be02..d9594995 100644 --- a/devcapsule-src/tests/integration/test_print_command_cli.py +++ b/devcapsule-src/tests/integration/test_print_command_cli.py @@ -81,3 +81,21 @@ def test_print_command_names_a_base_image_that_is_not_here_and_pulls_nothing(lau assert calls and all(call.startswith("image inspect ") for call in calls), calls downloaded = [path for path in (tmp_path / "home").rglob("*") if path.is_file() and "artifacts" in path.parts] assert downloaded == [] + + +def test_print_command_with_a_trust_flag_records_no_acceptance(launcher, tmp_path: Path) -> None: + """A checkout whose base waits for the home's trust: ``run --print-command`` alone ends pending, exit 3. + With ``--trust devcapsule-base`` the review passes and the command goes on to look for the base image, so + the flag was taken; and the home still has no settings file, because printing records no acceptance.""" + created = launcher("init", "--require", "python", "--creator", "mailto:owner@example.test") + assert created.returncode == 0, created.stderr + chosen = launcher("config", "ide", "python-ide") + assert chosen.returncode == 0, chosen.stderr + pending = launcher("run", "--print-command", "--no-update-check") + assert pending.returncode == 3 and "--trust devcapsule-base" in pending.stderr, pending.stdout + pending.stderr + + printed = launcher("run", "--print-command", "--trust", "devcapsule-base", "--no-update-check") + + assert printed.returncode == 2, printed.stdout + printed.stderr + assert "is not on this machine. A launch pulls it; nothing was pulled now." in printed.stderr + assert not (tmp_path / "devcapsule-home" / "settings.toml").exists() diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index 87e012ff..61a8b9d1 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -16,7 +16,7 @@ import pytest -from devcapsule.commands._launch_review import RunFlags, review_launch, stage_trust +from devcapsule.commands._launch_review import RunFlags, flags_after_upgrade, review_launch, stage_trust from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value from devcapsule.configuration.bindings import HostDirectory @@ -30,6 +30,7 @@ from devcapsule.configuration.manifest import current_manifest from devcapsule.configuration.manifest_document import Recommendations from devcapsule.configuration.operations import CheckoutRecord +from devcapsule.configuration.trust import BASE_CHANNEL, BASE_REPOSITORY, HomeTrust, base_channel, channels_for from devcapsule.configuration.values import memory_size_bytes from devcapsule.platforms import Platform from devcapsule.resolution_matrix import MATRICES @@ -65,9 +66,9 @@ def directory(name: str) -> HostDirectory: environment={name: "a value no decision reads" for name in variables}, directory=directory) -def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Host | None = None, +def checkout_of(required: tuple[str, ...], *, ide: str | None = "python-ide", host: Host | None = None, manifest_tables: dict[str, Any] | None = None, offered: tuple[str, ...] = (), - recommended: dict[str, str] | None = None) -> CheckoutState: + recommended: dict[str, str] | None = None, base_authorized: bool = True) -> CheckoutState: """A registered checkout of a project that requires ``required``, in a home that has accepted nothing. Its host is ``a_host()`` unless ``host`` is given. ``manifest_tables`` are @@ -79,7 +80,9 @@ def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Hos It is what ``project init --require ... --ide IDE --authorize base-image default`` leaves, built with the operations that command uses and no file: the lock derived from the policy, the IDE pinned on the record, the base - image authorized for this checkout. + image authorized for this checkout. With ``ide`` None the checkout has + chosen no IDE. With ``base_authorized`` false the checkout has not + authorized the base, which is then for the home's trust to answer. """ manifest: dict[str, Any] = { "devcapsule-schema-version": 2, @@ -100,8 +103,9 @@ def checkout_of(required: tuple[str, ...], *, ide: str = "python-ide", host: Hos selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) selection.ide = ide record = CheckoutRecord.staged(RECORD, state.with_selection(selection)) - base_image = authorization_declarations(manifest, state.composed_lock(record.document))["base-image"] - record.authorize(base_image, normalize_authorization_value(base_image, "default")) + if base_authorized: + base_image = authorization_declarations(manifest, state.composed_lock(record.document))["base-image"] + record.authorize(base_image, normalize_authorization_value(base_image, "default")) state.checkout = record.export() return state @@ -579,3 +583,146 @@ def test_the_checkouts_own_authorization_of_a_vendors_download_settles_it_withou assert review.selected.lock["components"]["claude-code"]["version"] assert review.accepted == [] assert review.state.home == {} + + +def leaving_the_base_to_the_home(*, ide: str | None = "python-ide") -> CheckoutState: + """A checkout of a project that requires Node, which has not authorized its base image: DevCapsule's + published base, for the home's trust of the channel ``devcapsule-base`` to answer.""" + return checkout_of(("node",), ide=ide, base_authorized=False) + + +def test_a_base_channel_the_home_has_not_accepted_leaves_the_launch_pending_naming_the_trust_flag() -> None: + """With the base neither authorized on the checkout nor trusted by the home, the launch ends pending on + DevCapsule's channel and names ``--trust devcapsule-base``. The home's settings are as they were.""" + state = leaving_the_base_to_the_home() + + with pytest.raises(DecisionPending, match="--trust devcapsule-base"): + review_launch(state, RunFlags(), ask=None, announce=never_announced) + + assert state.home == {} + + +def test_the_trust_flag_accepts_the_channel_for_the_home_and_the_published_base_is_planned() -> None: + """``--trust devcapsule-base`` settles the base without a terminal: the plan authorizes DevCapsule's + published base, the acceptance is staged for the home with the time the host tells, and nothing about the + base is staged on the checkout's record.""" + review = review_launch(leaving_the_base_to_the_home(), RunFlags(trust=(BASE_CHANNEL,)), ask=None, announce=never_announced) + + assert review.selected.resolution["authorization"]["base-image"]["reference"].startswith(BASE_REPOSITORY + "@") + assert review.accepted == [BASE_CHANNEL] + assert review.state.home["trust"]["channels"][BASE_CHANNEL]["accepted"] == "2026-01-02T03:04:05+00:00" + assert "base-image" not in review.record.document.get("authorization", {}) + assert review.record.document == review.original + + +def test_a_home_that_trusts_the_base_channel_plans_the_launch_without_a_question() -> None: + """In a home that has accepted DevCapsule's channel, the same checkout is planned with nothing asked and + nothing newly accepted.""" + state = leaving_the_base_to_the_home() + state.home = {"trust": HomeTrust().with_channel(base_channel(), accepted_at=ACCEPTED_AT).document()} + + review = review_launch(state, RunFlags(), ask=never_asked, announce=never_announced) + + assert review.selected.resolution["authorization"]["base-image"]["reference"].startswith(BASE_REPOSITORY + "@") + assert review.accepted == [] + + +def test_a_trust_flag_beside_another_unanswered_decision_still_ends_pending() -> None: + """With no IDE chosen and no terminal, ``--trust devcapsule-base`` answers the channel and the launch + still ends pending on the IDE alone: the message says nothing was written.""" + state = leaving_the_base_to_the_home(ide=None) + + with pytest.raises(DecisionPending) as pending: + review_launch(state, RunFlags(trust=(BASE_CHANNEL,)), ask=None, announce=never_announced) + + message = str(pending.value) + assert "ide ide: Your IDE for this checkout" in message + assert "trust devcapsule-base" not in message + assert "Nothing was written" in message + + +def test_trusting_a_channel_the_project_does_not_use_is_refused_naming_its_channels() -> None: + """``--trust codex`` on a project whose only channel is DevCapsule's base is refused, and the refusal lists + the project's channels.""" + with pytest.raises(ProjectConfigurationError, match="No channel 'codex' on this project; its channels: devcapsule-base"): + review_launch(leaving_the_base_to_the_home(), RunFlags(trust=("codex",)), ask=None, announce=never_announced) + + +SAVED_ORIGIN = "https://selected.example.test" +"""Where the checkout's saved version set takes Claude Code from, which is not where the project's lock does.""" + + +def with_a_saved_set_from_another_origin() -> CheckoutState: + """A checkout of a project that requires the Claude Code agent, with a saved version set whose Claude Code + comes from ``SAVED_ORIGIN``.""" + state = checkout_of(("python", "python-ide", "claude-code-agent")) + saved = state.composed_lock() + for artifact in saved["components"]["claude-code"]["artifacts"].values(): + artifact["url"] = f"{SAVED_ORIGIN}/claude" + state.checkout["version-set"] = {"format": 1, "lock": render_toml(saved), + "recommendation-digest": canonical_digest(state.shared_lock)} + return state + + +def test_the_trust_flag_accepts_the_channel_as_the_checkouts_saved_version_set_names_it() -> None: + """``--trust claude-code`` accepts the channel of the checkout's saved version set: the origin staged for + the home is the saved set's, not the project lock's, and the download is authorized in the plan.""" + state = with_a_saved_set_from_another_origin() + assert SAVED_ORIGIN not in channels_for(state.shared_lock)["claude-code"].origins + + review = review_launch(state, RunFlags(trust=("claude-code",)), ask=None, announce=never_announced) + + assert review.state.home["trust"]["channels"]["claude-code"]["origins"] == [SAVED_ORIGIN] + assert review.selected.resolution["authorization"]["claude-code-download"] is True + + +def test_the_question_put_to_the_developer_names_the_channel_of_the_saved_version_set() -> None: + """Without the flag, the one decision put to the developer describes Claude Code's channel with the saved + set's origin and not the project lock's; accepted, that origin is what is staged for the home.""" + state = with_a_saved_set_from_another_origin() + (shared_origin,) = channels_for(state.shared_lock)["claude-code"].origins + asked: list[Decision] = [] + + review = review_launch(state, RunFlags(), ask=accepting(asked), announce=never_announced) + + assert [(decision.kind, decision.name) for decision in asked] == [("trust", "claude-code")] + assert SAVED_ORIGIN in asked[0].description and shared_origin not in asked[0].description + assert review.state.home["trust"]["channels"]["claude-code"]["origins"] == [SAVED_ORIGIN] + + +def test_the_second_review_is_given_this_launchs_flags_without_trust_and_without_save() -> None: + """After an upgrade, flags that were for this launch only are given again, but for ``--trust``; a host + access allowed once at the terminal is given as its ``--authorize`` flag.""" + flags = RunFlags(ide="codium", memory="6g", environment=("A=1",), trust=("claude-code",), allow_unverified=True) + + again = flags_after_upgrade(flags, {"network": "host"}) + + assert again == RunFlags(ide="codium", memory="6g", environment=("A=1",), authorize=(("network", "host"),), allow_unverified=True) + + +def test_the_second_review_is_given_none_of_the_flags_that_were_saved() -> None: + """With ``--save`` the flags are the checkout's answers by the second review: none is given again, except + the permission for unverified combinations, which is never saved.""" + flags = RunFlags(ide="codium", memory="6g", authorize=(("network", "host"),), trust=("claude-code",), save=True, allow_unverified=True) + + assert flags_after_upgrade(flags, {}) == RunFlags(allow_unverified=True) + + +def test_a_channel_that_an_upgrade_moved_is_pending_in_the_second_review_and_the_acceptance_is_not_widened() -> None: + """The first review accepted Claude Code's channel by flag. An upgrade then moves Claude Code to another + origin. The second review, given the flags that remain, ends pending on the channel, and the home still + holds the origin that was accepted and no other.""" + flags = RunFlags(trust=("claude-code",)) + state = checkout_of(("python", "python-ide", "claude-code-agent")) + first = review_launch(state, flags, ask=None, announce=never_announced) + accepted_origins = list(first.state.home["trust"]["channels"]["claude-code"]["origins"]) + upgraded = first.state.composed_lock() + for artifact in upgraded["components"]["claude-code"]["artifacts"].values(): + artifact["url"] = "https://unaccepted.example.test/claude" + state.checkout["version-set"] = {"format": 1, "lock": render_toml(upgraded), + "recommendation-digest": canonical_digest(state.shared_lock)} + + with pytest.raises(DecisionPending, match="trust claude-code"): + review_launch(state, flags_after_upgrade(flags, first.host_overrides), ask=None, announce=never_announced) + + assert state.home["trust"]["channels"]["claude-code"]["origins"] == accepted_origins diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py index faf4c1ca..d5178e97 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py @@ -146,3 +146,29 @@ def test_a_checkouts_own_grant_answers_a_vendor_download_under_a_home_that_trust review = _download_review(lock, _checkout_answering(lock, download=True), HomeTrust()) assert (review.status, review.value, review.problem) == ("authorized", True, None) + + +def test_a_trusted_channel_does_not_cover_an_artifact_that_moved_to_another_origin() -> None: + """A home accepted Claude Code's channel as one lock named it. Under a lock whose artifact comes from + another origin the acceptance does not answer the download: it is unanswered again, with a problem.""" + accepted = _lock_with_claude_code() + moved = _lock_with_claude_code() + moved["components"]["claude-code"]["artifacts"]["linux-amd64"]["url"] = "https://mirror.example.test/claude" + + review = _download_review(moved, _checkout_answering(moved, download=None), _trusting_every_channel_of(accepted)) + + assert (review.status, review.trusted_channel) == ("missing-required", None) + assert review.problem is not None + + +def test_a_trusted_channel_covers_another_version_from_the_same_origin() -> None: + """The same acceptance answers the download of a later version that comes from the origin accepted: trust + is given to the channel, not to a version.""" + accepted = _lock_with_claude_code() + later = _lock_with_claude_code() + later["components"]["claude-code"]["version"] = "2.2.0" + later["components"]["claude-code"]["artifacts"]["linux-amd64"] = {"url": "https://downloads.claude.ai/later/claude", "sha256": "d" * 64} + + review = _download_review(later, _checkout_answering(later, download=None), _trusting_every_channel_of(accepted)) + + assert (review.status, review.trusted_channel, review.problem) == ("trusted", "claude-code", None) diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_trust_listing.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_trust_listing.py new file mode 100644 index 00000000..f759df7a --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_trust_listing.py @@ -0,0 +1,90 @@ +"""Unit tests of ``devcapsule/configuration/trust_listing.py``: what ``project config trust list`` shows. + +Each test builds the channels and the home's trust record as values. +""" + +from __future__ import annotations + +from dataclasses import replace +from datetime import datetime, timezone + +from devcapsule.configuration.trust import Channel, HomeTrust +from devcapsule.configuration.trust_listing import render_trust_rows, trust_rows + +ACCEPTED_AT = datetime(2026, 1, 2, 3, 4, 5, tzinfo=timezone.utc) + +EDITOR = Channel("editor", "Example Vendor", "Example Editor", ("https://downloads.example.test",), + "the SHA-256 the launcher pins", "https://example.test/terms", "editor-download") +"""A vendor's channel as a lock names it: one origin, pinned checksums, terms.""" + + +def accepting(*channels: Channel) -> HomeTrust: + """The trust record of a home whose user accepted each of ``channels``, at ``ACCEPTED_AT``.""" + trust = HomeTrust() + for channel in channels: + trust = trust.with_channel(channel, accepted_at=ACCEPTED_AT) + return trust + + +def test_a_channel_the_home_never_accepted_is_listed_as_not_yet() -> None: + """A channel of the lock with no entry in the home's record is not trusted and has nothing accepted; its + line says ``not yet`` with the vendor, the product, the origin, the integrity method and the terms.""" + rows = trust_rows({EDITOR.id: EDITOR}, HomeTrust()) + + assert [(row["channel"], row["trusted"], row["accepted"]) for row in rows] == [("editor", False, None)] + assert render_trust_rows(rows) == [ + "editor not yet Example Vendor — Example Editor; from https://downloads.example.test; " + "integrity the SHA-256 the launcher pins; terms https://example.test/terms", + ] + + +def test_a_channel_the_home_accepted_as_the_lock_names_it_is_listed_as_trusted() -> None: + """A channel accepted with the origin the lock names is trusted, and the row carries the home's entry with + the time of the acceptance.""" + (row,) = trust_rows({EDITOR.id: EDITOR}, accepting(EDITOR)) + + assert row["trusted"] is True + assert row["accepted"]["accepted"] == "2026-01-02T03:04:05+00:00" + (line,) = render_trust_rows([row]) + assert line.startswith("editor trusted Example Vendor") + + +def test_a_channel_that_left_what_was_accepted_is_not_covered_and_the_accepted_origins_are_shown() -> None: + """When the lock names an origin the home did not accept, the channel is not trusted although it has an + entry: its line says ``not covered`` with the new origin, and a second line gives the origins, integrity + method and terms that were accepted.""" + moved = replace(EDITOR, origins=("https://mirror.example.test",)) + + rows = trust_rows({moved.id: moved}, accepting(EDITOR)) + + assert [(row["trusted"], row["accepted"]["origins"]) for row in rows] == [(False, ["https://downloads.example.test"])] + first, second = render_trust_rows(rows) + assert first.startswith("editor not covered Example Vendor") and "from https://mirror.example.test;" in first + assert second.strip() == ("Accepted origins: https://downloads.example.test; integrity the SHA-256 the launcher pins; " + "terms https://example.test/terms") + + +def test_an_accepted_channel_that_the_checkout_does_not_use_is_listed_after_the_locks_channels() -> None: + """A channel in the home's record that the checkout's lock does not use is listed last, from the record + alone, and noted as not used by this checkout.""" + other = Channel("other", "Other Vendor", "Other Tool", ("https://other.example.test",), "the SHA-256 the launcher pins") + + rows = trust_rows({EDITOR.id: EDITOR}, accepting(EDITOR, other)) + + assert [(row["channel"], row["trusted"], row["note"]) for row in rows] == [ + ("editor", True, ""), ("other", True, "not used by this checkout"), + ] + assert render_trust_rows(rows)[-2:] == [ + "other trusted Other Vendor — (not used by this checkout); from https://other.example.test; " + "integrity the SHA-256 the launcher pins", + " not used by this checkout", + ] + + +def test_a_channels_note_is_shown_under_its_line() -> None: + """A channel that carries a note, as DevCapsule's base channel does, has the note on a line of its own.""" + noted = replace(EDITOR, note="Read this before you accept.") + + lines = render_trust_rows(trust_rows({noted.id: noted}, HomeTrust())) + + assert len(lines) == 2 and lines[1].strip() == "Read this before you accept." diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/__init__.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_home.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_home.py deleted file mode 100644 index db3f57d5..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_home.py +++ /dev/null @@ -1,38 +0,0 @@ -"""Legacy tests of ``tests/test_home.py`` marked expected to fail on 2026-11-04, moved verbatim but for one path. - -The path to ``devcapsule-src`` is taken from this file's place in the mirror, four levels deeper -than the legacy file's. -Mirror of ``devcapsule/legacy_refactoring/home.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -from pathlib import Path -import pytest -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.parametrize("folder", ["devcapsule", "tests", "docs"]) -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_replaced_scope_word_is_absent(folder: str) -> None: - """Legacy test, moved verbatim and expected to fail: it walks the checkout's resources, ignored directories included, instead of constructing its input.""" - package = Path(__file__).resolve().parents[4] # devcapsule-src; parents[1] in the legacy file's place - root = package.parent / "docs" if folder == "docs" else package / folder - forbidden = "work" + "station" - failures = [] - for path in root.rglob("*"): - if not path.is_file() or "__pycache__" in path.parts or ".pytest_cache" in path.parts: - continue - if path.is_relative_to(package / "tests" / "resources" / "compat"): - continue - try: - text = path.read_text() - except UnicodeError: - continue - if forbidden in text.lower(): - failures.append(str(path.relative_to(root))) - assert failures == [] diff --git a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_trust.py b/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_trust.py deleted file mode 100644 index 800e4806..00000000 --- a/devcapsule-src/tests/unit/devcapsule/legacy_refactoring/test_trust.py +++ /dev/null @@ -1,157 +0,0 @@ -"""Legacy tests of ``tests/test_trust.py`` marked expected to fail on 2026-11-04, moved verbatim. - -Mirror of ``devcapsule/legacy_refactoring/trust.py``, a temporary target that holds no code. -Each test here reads a precondition from outside itself, against *Unit Tests* rule 2; the -maintenance workstream rewrites each against its real unit and this file shrinks to nothing. -""" -from __future__ import annotations - -import io -import json -from pathlib import Path -import pytest -from devcapsule import cli -from devcapsule.commands._run_flow import RunFlags, prepare_launch -from devcapsule.compat import DecisionPending -from devcapsule.configuration.file_formats import render_toml -from devcapsule.configuration.storage import checkout_record_paths, load_toml, load_trust, manifest_for, settings_path -from devcapsule.configuration.trust import BASE_CHANNEL, HomeTrust -from tests.test_trust import accept, config, lock_path, pin_claude_code, project, reviews, withdraw -from devcapsule.runtime_configuration import CONTEXT_PATH - -IN_CAPSULE = CONTEXT_PATH.is_file() -"""The marker holds only inside a capsule, where these tests inherit its state; elsewhere they are the tests they were.""" - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_trust_list_accept_and_withdraw(project: Path, capsys) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - assert config(project, "ide", "python-ide") == 0 - assert config(project, "check") == 3 - assert config(project, "trust", "list") == 0 - out = capsys.readouterr().out - assert "devcapsule-base" in out and "not yet" in out and str(settings_path()) in out - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - out = capsys.readouterr().out - assert "Trust DevCapsule to supply the base images" in out and "Recorded for this DevCapsule home" in out - assert load_toml(settings_path())["trust"]["channels"]["devcapsule-base"]["vendor"] == "DevCapsule" - assert config(project, "show") == 0 - assert "home trust (devcapsule-base)" in capsys.readouterr().out - assert config(project, "check") == 0 - capsys.readouterr() - assert config(project, "trust", "list", "--json") == 0 - listed = json.loads(capsys.readouterr().out) - assert [(row["channel"], row["trusted"]) for row in listed["channels"]] == [("devcapsule-base", True)] - assert withdraw("devcapsule-base") == 0 - assert config(project, "check") == 3 - assert withdraw("devcapsule-base") == 0 - assert accept(project, "codex") == 2 - assert "its channels: devcapsule-base" in capsys.readouterr().err - - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_run_trust_flag_records_the_channel_before_the_questions(project: Path) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - with pytest.raises(DecisionPending, match="--trust devcapsule-base"): - prepare_launch(project, RunFlags(ide="python-ide"), interactive=False) - assert not settings_path().exists() - prepared = prepare_launch(project, RunFlags(ide="python-ide", trust=("devcapsule-base",)), interactive=False) - assert prepared.selected.resolution["authorization"]["base-image"]["reference"].startswith("docker.io/mycodespaceai/devcapsule-base@") - assert "devcapsule-base" in load_toml(settings_path())["trust"]["channels"] - assert "Accepted the channel devcapsule-base for this home." in prepared.notes - # Printing the command stages the acceptance for the plan and writes nothing. - assert withdraw("devcapsule-base") == 0 - prepare_launch(project, RunFlags(ide="python-ide", trust=("devcapsule-base",)), print_only=True) - assert not HomeTrust.read(load_trust()).channels - # With another decision pending and no terminal, the flag's acceptance is staged with the other answers: nothing is written. - with pytest.raises(DecisionPending, match="Nothing was written"): - prepare_launch(project, RunFlags(trust=("devcapsule-base",)), interactive=False) # the IDE is still unchosen - assert not HomeTrust.read(load_trust()).channels - # Declined at the prompt: nothing recorded, the launch is still pending. - assert config(project, "ide", "python-ide") == 0 - prompts = io.StringIO() - with pytest.raises(DecisionPending): - prepare_launch(project, RunFlags(), interactive=True, input_stream=io.StringIO("n\n"), output_stream=prompts) - assert "Not accepted. Accept later:" in prompts.getvalue() - assert not HomeTrust.read(load_trust()).channels - - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_changed_artifact_origin_asks_and_lists_the_previous_acceptance(project: Path, capsys) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - pin_claude_code(project, "1.0.0") - assert accept(project, "claude-code") == 0 - lock = load_toml(lock_path(project)) - lock["components"]["claude-code"]["artifacts"]["linux-amd64"]["url"] = "https://mirror.example.test/claude" - lock_path(project).write_text(render_toml(lock)) - assert reviews(project)["claude-code-download"].status == "missing-required" - capsys.readouterr() - assert config(project, "trust", "list") == 0 - text = capsys.readouterr().out - assert "not covered" in text and "https://mirror.example.test" in text - assert "Accepted origins: https://downloads.example.test" in text - assert "SHA-256" in text and "Anyone who uses this home uses this acceptance" in text - assert accept(project, "claude-code") == 0 - assert reviews(project)["claude-code-download"].status == "trusted" - pin_claude_code(project, "1.1.0") - assert reviews(project)["claude-code-download"].status == "trusted" - - - -@pytest.mark.parametrize("via", ["flag", "terminal"]) -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_acceptance_uses_the_checkout_version_set_not_the_shared_lock(project: Path, via: str, capsys) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - from devcapsule.configuration.derivation import load_state - from devcapsule.configuration.file_formats import canonical_digest - assert config(project, "ide", "python-ide") == 0 - assert accept(project, BASE_CHANNEL) == 0 - pin_claude_code(project, "1.0.0") - _, manifest = manifest_for(project) - manifest["capabilities"]["required"].append("claude-code-agent") - (project / ".devcapsule/devcapsule.toml").write_text(render_toml(manifest)) - state = load_state(project, manifest) - selected = state.composed_lock() - selected["components"]["claude-code"]["artifacts"]["linux-amd64"]["url"] = "https://selected.example.test/claude" - record_path = checkout_record_paths(manifest, project)[0] - record = load_toml(record_path) - record["version-set"] = {"format": 1, "lock": render_toml(selected), "recommendation-digest": canonical_digest(state.shared_lock)} - record_path.write_text(render_toml(record)) - capsys.readouterr() - assert config(project, "trust", "list", "--json") == 0 - listed = json.loads(capsys.readouterr().out) - channel = next(row for row in listed["channels"] if row["channel"] == "claude-code") - assert channel["origins"] == ["https://selected.example.test"] - flags, interactive = RunFlags(trust=("claude-code",) if via == "flag" else ()), via == "terminal" - output = io.StringIO() - prepared = prepare_launch(project, flags, interactive=interactive, input_stream=io.StringIO("y\n"), output_stream=output) - assert prepared.selected.resolution["authorization"]["claude-code-download"] is True - if via == "terminal": - assert "https://selected.example.test" in output.getvalue() - assert "https://downloads.example.test" not in output.getvalue() - assert load_trust()["channels"]["claude-code"]["origins"] == ["https://selected.example.test"] - - - -@pytest.mark.xfail(IN_CAPSULE, reason="TODO: fix the wrong approach to testing") -def test_run_does_not_replay_trust_flags_after_an_upgrade_changes_the_channel(project: Path, monkeypatch) -> None: - """Legacy test, moved verbatim and expected to fail: it inherits the capsule's mounted launcher settings instead of constructing its own home.""" - from tests.test_upgrade_recovery import install_external_fakes, invoke - assert config(project, "ide", "python-ide") == 0 - pin_claude_code(project, "1.0.0") - _, manifest = manifest_for(project) - manifest["capabilities"]["required"].append("claude-code-agent") - (project / ".devcapsule/devcapsule.toml").write_text(render_toml(manifest)) - launch = install_external_fakes(monkeypatch, []) - monkeypatch.setattr("sys.stdin.isatty", lambda: False) - def upgrade(root: Path, *, refresh: bool) -> bool: - lock = load_toml(lock_path(root)) - lock["components"]["claude-code"]["artifacts"]["linux-amd64"]["url"] = "https://unaccepted.example.test/claude" - lock_path(root).write_text(render_toml(lock)) - return True - monkeypatch.setattr("devcapsule.commands.project.offer_upgrades", upgrade) - assert invoke(project, "run", "--trust", BASE_CHANNEL, "--trust", "claude-code", "--no-update-check") == 3 - launch.assert_not_called() - assert load_trust()["channels"]["claude-code"]["origins"] == ["https://downloads.example.test"] From 902a6a2e07e53e2c3d0543920155b4203d6760de Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Fri, 13 Nov 2026 00:01:38 +0000 Subject: [PATCH 52/75] Records: the mounted-settings bug is fixed on the branch; the holding pen is empty Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 40 ++++++++++++++++- engineering-docs/releases/v0.3.1/bugs.md | 2 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 43 +++++++++++++++++++ 3 files changed, 83 insertions(+), 2 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 3641bb9a..6e2c672c 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -1,5 +1,5 @@ --- -status: fixing +status: fixed severity: blocking target: 0.3.1 owner: maintenance @@ -272,6 +272,44 @@ which inside a capsule names no home. 4 does not hold: named home nor a handed-in one still reads the mount. The next channel the developer accepts can turn other tests red. +## Fixed on the branch, 2026-11-13 + +On `ws-maintenance/launch-phases`, pull request #29, at `8af31910`. The +fix is committed; the record closes when the owner has validated it and +the pull request is merged. + +The two holding-pen files that remained are gone, and with them the last +marks. The five tests of `test_trust.py` are rewritten: in memory on the +launch review, the review of authorizations and the trust listing, and as +processes in `tests/integration/test_home_trust_cli.py`, one of them on a +pseudo-terminal. The one test of `test_home.py`, a walk of the repository +for a retired word, is deleted on the owner's word. The holding pen and its +package of empty target modules no longer exist. + +Against the close criteria, all four now hold: + +1. `nox -s tests` passes inside the owner's capsule, whose mounted settings + carry three accepted channels: 3129 passed, 1 expected to fail, 1 + unexpectedly passed, in 155 seconds. +2. The hosted run at `8af31910` gives the same counts: 3129 passed, 1 + expected to fail, 1 unexpectedly passed. The two marked tests are + workflow tests with causes of their own, one of them dependent on the + clock, so that pair can read 2 and 0 on another run. A run with empty + mounted settings was not made: the mount is the owner's and read-only. + It cannot differ, because the fixture hides the capsule from every test + and a test of the conftest holds the fixture. +3. No expected-to-fail mark names the mounted settings, and none depends on + whether the suite runs in a capsule. The network guard records no + attempt. +4. `engineering-docs/development/unit-tests.md` describes the fixture as a + private home on a machine that is no capsule. + +What this record does not cover and is still true: one integration test, +`tests/integration/test_pex_runtime.py::test_built_pex_authors_shared_policy_and_keeps_personal_selection_local`, +fails inside a capsule. It is a legacy file and builds the launcher's +environment in the test's body from the test process's own, which names no +home; the fixture cannot reach a program a test starts. + ## Verification target and close criteria 1. `nox -s tests` passes inside a capsule whose mounted settings carry diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 1b31be36..425e4a2e 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -17,7 +17,7 @@ before each candidate and record the reconciliation revision here. | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixing | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture is fixed there too, so no unit test sees the capsule it runs in; 6 stale marks on 9 passing cases, in two holding-pen files, are still to do | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture is fixed there too, so no unit test sees the capsule it runs in; since `8af31910` no mark depends on the capsule and the capsule's counts equal the hosted run's, 3129 passed; closes on the owner's validation and the merge of #29 | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 73eb2387..78f0ad8c 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -205,6 +205,49 @@ capsule: 3095 passed, 9 expected to fail, 10 unexpectedly passed. The integration tests that need no Docker: 128 passed, 3 skipped, and the one standing failure. +**The holding pen emptied; the mounted-settings bug is `fixed`, +2026-11-13.** Owner direction: delete the `test_home.py` test, fix +`test_trust.py`. + +- The five marked tests of the holding-pen `test_trust.py` drove the + command line and patched the upgrade offer. They are now 10 tests of the + launch review, 2 of the review of authorizations and 5 of the trust + listing, all in memory; 3 process tests in the new + `tests/integration/test_home_trust_cli.py`; and 1 more in + `test_print_command_cli.py`. +- One of the process tests runs `project run` on a pseudo-terminal and + answers no to the trust question. The terminal's dialogue is in + `_run_flow.py`, whose mirror is blocked by the legacy file of the same + name, and the launch asks only when its input is a terminal; a process on + a pty tests both. Run five times, about 1.2 s each, no failure. +- Two extractions in the product, behaviour unchanged. The rows and lines + of `config trust list` moved from the command class to + `configuration/trust_listing.py`. The flags of the second review after an + upgrade became `flags_after_upgrade` in `_launch_review.py`, called from + `ProjectCommand._run`. +- The one test of the holding-pen `test_home.py` is deleted. Its reader + gone, the Python route's input `docs/**` in + `.github/ci-python-inputs.yml` narrowed to `docs/versions.yaml`: a pull + request that changes only other files under `docs/` no longer runs the + hosted Python job. The suite passes under the guard with the narrower + list, so no unit test reads another path there. +- `devcapsule/legacy_refactoring/` and its test package are removed. The + command-line debt list has 3 files. +- Twelve planted faults are each caught. One wiring line is held by + nothing: that `_run` hands the second review what `flags_after_upgrade` + returns with respect to `--trust`. With that line made to give `--trust` + again, the whole unit suite passes. A legacy test of + `tests/test_run_flow.py` holds the same line for saved flags. The deleted + test held it, by patching the upgrade offer; nothing can without that + patch until `_run` takes the offer as a value. +- `nox -s typecheck tests` in the capsule: 3129 passed, 1 expected to fail, + 1 unexpectedly passed, 155 seconds. The hosted run at `8af31910`: the + same counts. Integration tests that need no Docker: 132 passed, 3 + skipped, and the one standing failure. + +The bug record is `fixed`: all four close criteria hold. It closes on the +owner's validation and the merge of pull request #29. + **The shared fixture fixed and the last two failing marked cases rewritten, 2026-11-12.** Owner direction: go at the first item of the debt list. From 33331a1da729bc4e828dd89d5f6d3486b49eff13 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Fri, 13 Nov 2026 00:54:48 +0000 Subject: [PATCH 53/75] Tests: the console channel's legacy file retired into unit tests and process tests; the pex file retired in place tests/test_console_channel.py passed under nox -s tests and failed under a checkout's .venv inside a capsule. Its 'project config' commands were processes with no named home; inside a capsule each read the launcher's mounted settings and compared their minimum-devcapsule with the version of the distribution installed in its interpreter. nox installs the current version; a .venv installed long ago said 0.2.15, so every command was refused. The file's 26 tests are now: - in memory: the channel's contract (classification, request, listing and store documents, reading and publishing), the store of kept requests, and the launcher's side with the command runner passed as a value (applied, kept, refused, bad files, the stopping launcher, the watcher, apply and discard, the view of a channel, the listing inside a capsule); the child's environment and process as two functions with tests of their own; a waiting request and the launch's listing in the launch review; - as processes, tests/integration/test_console_channel_cli.py: a widening kept and shown on the host, config check, console apply and discard, the secure authorizations, and 'project run' on a pseudo-terminal, with a stand-in for docker, where a kept request is applied or left at the launch's question. Every process is given a named home. The module's docstring says what the tests need and why the legacy file failed. Seams in the product, behaviour unchanged: handle_request, sweep, ChannelWatcher and apply_deferred take the runner as 'run'; run_config is child_environment and run_command composed; request_rows builds the listing rows of kept requests; launch_listing moved to the launch review module and is given the checkout's name; the listing shown inside a capsule is running_listing_document and render_running_listing. tests/integration/test_pex_runtime.py is retired in place instead of marking its capsule failure expected: every executable it starts gets an environment the test builds, with a named home, and the test passes. The conventions gate refuses a mark on a legacy test. Evidence: 22 planted faults each caught; nox -s typecheck tests in the capsule, 3212 passed, 1 expected to fail, 1 unexpectedly passed; the same suite under the stale .venv interpreter, 3212 passed; integration tests that need no Docker, 146 passed, 3 skipped, none failed. Co-Authored-By: Claude --- .../devcapsule/commands/_console_channel.py | 146 ++++- .../devcapsule/commands/_launch_review.py | 31 +- .../devcapsule/commands/_run_flow.py | 22 +- devcapsule-src/devcapsule/commands/project.py | 32 +- .../configuration/console_requests.py | 11 +- .../integration/test_console_channel_cli.py | 279 ++++++++- .../tests/integration/test_pex_runtime.py | 83 ++- devcapsule-src/tests/test_console_channel.py | 543 ------------------ .../commands/test_console_channel.py | 489 ++++++++++++++++ .../devcapsule/commands/test_launch_review.py | 80 ++- .../configuration/test_console_channel.py | 237 ++++++++ .../configuration/test_console_requests.py | 146 +++++ .../development/integration-tests.md | 28 +- 13 files changed, 1472 insertions(+), 655 deletions(-) delete mode 100644 devcapsule-src/tests/test_console_channel.py create mode 100644 devcapsule-src/tests/unit/devcapsule/commands/test_console_channel.py create mode 100644 devcapsule-src/tests/unit/devcapsule/configuration/test_console_channel.py create mode 100644 devcapsule-src/tests/unit/devcapsule/configuration/test_console_requests.py diff --git a/devcapsule-src/devcapsule/commands/_console_channel.py b/devcapsule-src/devcapsule/commands/_console_channel.py index e3065365..53715d8b 100644 --- a/devcapsule-src/devcapsule/commands/_console_channel.py +++ b/devcapsule-src/devcapsule/commands/_console_channel.py @@ -22,7 +22,7 @@ import sys import threading import uuid -from typing import Any, Sequence +from typing import Any, Callable, Mapping, Sequence from devcapsule.configuration.console_channel import ( CHANNEL_FORMAT, @@ -42,9 +42,19 @@ ) from devcapsule.configuration.console_requests import deferred_requests, write_deferred from devcapsule.configuration.file_formats import ProjectConfigurationError +from devcapsule.configuration.listing import Listing -__all__ = ["ChannelView", "ChannelWatcher", "apply_deferred", "discard_deferred", "handle_request", "read_channel", - "run_config", "sweep"] +__all__ = ["ChannelView", "ChannelWatcher", "ConfigRunner", "apply_deferred", "child_environment", "discard_deferred", + "handle_request", "read_channel", "render_running_listing", "run_command", "run_config", + "running_listing_document", "sweep"] + +ConfigRunner = Callable[..., tuple[int, str]] +"""Runs ``config ARGUMENTS`` for a project: ``run(root, arguments, host_confirmed=False)`` gives the command's +status and its output. :func:`run_config` is the one the launcher uses; a test passes its own.""" + +INHERITED_VARIABLES = frozenset({"HOME", "PATH", "LANG", "TMPDIR", "DEVCAPSULE_CONFIG_HOME", "XDG_CONFIG_HOME", + "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME", "XDG_RUNTIME_DIR"}) +"""What a command run for the console inherits of the launcher's environment, with every ``LC_`` variable.""" _log = logging.getLogger("devcapsule.console-channel") COMMAND_TIMEOUT_SECONDS = 120.0 @@ -58,34 +68,60 @@ def _config_command(root: Path, arguments: Sequence[str]) -> list[str]: return [sys.executable, "-m", "devcapsule", "project", "--path", str(root), "config", *arguments] -def run_config(root: Path, arguments: Sequence[str], *, host_confirmed: bool = False) -> tuple[int, str]: - """Run ``config ARGUMENTS`` for the project at ``root`` as its own process; the status and the combined output.""" - # The child needs the host record locations, not credentials, Python - # injection settings, or the launcher's controlling terminal. - environment = {key: value for key, value in os.environ.items() - if key in {"HOME", "PATH", "LANG", "TMPDIR", "DEVCAPSULE_CONFIG_HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", - "XDG_STATE_HOME", "XDG_CACHE_HOME", "XDG_RUNTIME_DIR"} or key.startswith("LC_")} +def child_environment(environment: Mapping[str, str], *, host_confirmed: bool = False) -> dict[str, str]: + """The environment of a command run for the console, from the launcher's own ``environment``. + + The child needs the host record locations, not credentials, Python + injection settings, or anything else of the launcher's shell: only + :data:`INHERITED_VARIABLES` and the ``LC_`` variables pass. With + ``host_confirmed`` the human ran the command on the host themselves, and + it keeps their Docker context and other host configuration, as an + ordinary CLI invocation does: everything passes. + """ if host_confirmed: - # The human's explicit host command keeps their Docker context and - # other host configuration, as an ordinary CLI invocation does. - environment = dict(os.environ) + return dict(environment) + return {key: value for key, value in environment.items() if key in INHERITED_VARIABLES or key.startswith("LC_")} + + +def run_command(command: Sequence[str], environment: Mapping[str, str], timeout: float) -> tuple[int, str]: + """Run ``command`` as its own process; its exit status and its output, standard error included, stripped. + + The child has no input, no controlling terminal of the launcher's and a + session of its own. One that has not finished after ``timeout`` seconds + is killed with every process of its session, and the result is status 1 + with a line saying so. A command that cannot be started is status 1 with + the reason. + """ try: - with subprocess.Popen(_config_command(root, arguments), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, + with subprocess.Popen(list(command), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, errors="replace", stdin=subprocess.DEVNULL, start_new_session=True, - cwd="/", env=environment) as child: + cwd="/", env=dict(environment)) as child: try: - output, _ = child.communicate(timeout=COMMAND_TIMEOUT_SECONDS) + output, _ = child.communicate(timeout=timeout) except subprocess.TimeoutExpired: + # A descendant inherits the output pipe. Killing only its parent would + # let it finish its write and keep communicate() waiting for that pipe. os.killpg(child.pid, signal.SIGKILL) child.communicate() - return 1, f"the command did not finish within {COMMAND_TIMEOUT_SECONDS:g} seconds" + return 1, f"the command did not finish within {timeout:g} seconds" return child.returncode, output.strip() except OSError as exc: return 1, f"cannot run the configuration command: {exc}" -def handle_request(root: Path, checkout_record: Path, request_path: Path, *, stopping: bool = False) -> dict[str, Any]: - """Answer one request file with its result file; the result document.""" +def run_config(root: Path, arguments: Sequence[str], *, host_confirmed: bool = False) -> tuple[int, str]: + """Run ``config ARGUMENTS`` for the project at ``root`` as its own process; the status and the combined output.""" + return run_command(_config_command(root, arguments), child_environment(os.environ, host_confirmed=host_confirmed), + COMMAND_TIMEOUT_SECONDS) + + +def handle_request(root: Path, checkout_record: Path, request_path: Path, *, stopping: bool = False, + run: ConfigRunner | None = None) -> dict[str, Any]: + """Answer one request file with its result file; the result document. + + ``run`` runs the command of a request that is applied at once; left + out, it is :func:`run_config`. + """ identifier = request_id(request_path) try: document = read_document(request_path) @@ -98,7 +134,7 @@ def handle_request(root: Path, checkout_record: Path, request_path: Path, *, sto if stopping and disposition is Disposition.APPLY: disposition = Disposition.DEFER if disposition is Disposition.APPLY: - status, output = run_config(root, arguments) + status, output = (run or run_config)(root, arguments) if status == 0: result = result_document("recorded", f"Recorded for the next launch. This running capsule is unchanged.\n{output or statement(arguments)}") else: @@ -128,8 +164,13 @@ def handle_request(root: Path, checkout_record: Path, request_path: Path, *, sto return result -def sweep(directory: Path, root: Path, checkout_record: Path, *, stop: threading.Event | None = None) -> int: - """Answer every complete request in ``directory`` that has no result yet; how many were answered.""" +def sweep(directory: Path, root: Path, checkout_record: Path, *, stop: threading.Event | None = None, + run: ConfigRunner | None = None) -> int: + """Answer every complete request in ``directory`` that has no result yet; how many were answered. + + Once ``stop`` is set, a request that would be applied is kept for the + host's confirmation instead. ``run`` is as for :func:`handle_request`. + """ answered = 0 try: names = sorted(path for path in directory.iterdir() if path.name.endswith(REQUEST_SUFFIX)) @@ -143,7 +184,7 @@ def sweep(directory: Path, root: Path, checkout_record: Path, *, stop: threading if request_path.with_name(identifier + RESULT_SUFFIX).exists(): continue try: - handle_request(root, checkout_record, request_path, stopping=stop is not None and stop.is_set()) + handle_request(root, checkout_record, request_path, stopping=stop is not None and stop.is_set(), run=run) except Exception as exc: # noqa: BLE001 - one bad request never stops the watcher _log.warning("console request %s: %s", request_path.name, exc) try: @@ -159,11 +200,12 @@ class ChannelWatcher: """A thread sweeping the channel directory while the capsule runs; ``stop`` sweeps once more.""" def __init__(self, directory: Path, root: Path, checkout_record: Path, - interval: float = SWEEP_INTERVAL_SECONDS) -> None: + interval: float = SWEEP_INTERVAL_SECONDS, run: ConfigRunner | None = None) -> None: self.directory = directory self.root = root self.checkout_record = checkout_record self.interval = interval + self.run = run self._stop = threading.Event() self._thread = threading.Thread(target=self._run, name="devcapsule-console-channel", daemon=True) @@ -178,17 +220,22 @@ def stop(self) -> None: def _run(self) -> None: while not self._stop.wait(self.interval): - sweep(self.directory, self.root, self.checkout_record, stop=self._stop) - sweep(self.directory, self.root, self.checkout_record, stop=self._stop) + sweep(self.directory, self.root, self.checkout_record, stop=self._stop, run=self.run) + sweep(self.directory, self.root, self.checkout_record, stop=self._stop, run=self.run) + +def apply_deferred(root: Path, checkout_record: Path, identifier: str, *, run: ConfigRunner | None = None) -> tuple[int, str]: + """Run the deferred request ``identifier`` as its command, and forget it; the command's status and output. -def apply_deferred(root: Path, checkout_record: Path, identifier: str) -> tuple[int, str]: - """Run the deferred request ``identifier`` as its command, and forget it; the command's status and output.""" + The command is run as confirmed on the host, with the request's tokens + exactly as kept. A command that fails leaves the request awaiting. ``run`` + is as for :func:`handle_request`. + """ requests = deferred_requests(checkout_record) match = next((item for item in requests if item.id == identifier), None) if match is None: raise ProjectConfigurationError(f"No console request {identifier!r} awaits confirmation for this checkout.") - status, output = run_config(root, match.arguments, host_confirmed=True) + status, output = (run or run_config)(root, match.arguments, host_confirmed=True) if status == 0: write_deferred(checkout_record, [item for item in requests if item.id != identifier]) return status, output @@ -242,3 +289,44 @@ def read_channel(directory: Path) -> ChannelView: requests.append({"id": identifier, "arguments": arguments, "statement": statement(arguments), "requested": str(document.get("requested", "")), "result": result}) return ChannelView(at, listing, tuple(requests)) + + +def _require_this_checkout(view: ChannelView, launcher_root: str, checkout_name: str, project: Mapping[str, Any]) -> None: + """Refuse a listing that the launcher wrote for another checkout than the one this capsule runs.""" + checkout = view.listing.get("checkout") + if (not isinstance(checkout, dict) or checkout.get("launcher-path") != launcher_root + or checkout.get("name") != checkout_name + or view.listing.get("project") != {key: project[key] for key in ("creator", "slug")}): + raise ProjectConfigurationError("The channel listing belongs to another checkout; inspect configuration on the host.") + + +def running_listing_document(view: ChannelView, *, launcher_root: str, checkout_name: str, project: Mapping[str, Any], + launcher_command: str) -> dict[str, Any]: + """What ``config show --json`` prints inside a running capsule: the launch-time listing and the requests since. + + ``launcher_root``, ``checkout_name`` and ``project`` say which checkout + this capsule runs; a listing written for another is refused. + ``launcher_command`` is the host command that shows the configuration. + """ + _require_this_checkout(view, launcher_root, checkout_name, project) + return {**view.listing, "context": "running capsule: the launcher's listing at launch", "at": view.at, + "console-requests": list(view.requests), "launcher-command": launcher_command} + + +def render_running_listing(view: ChannelView, *, launcher_root: str, checkout_name: str, project: Mapping[str, Any], + launcher_command: str) -> str: + """What ``config show`` prints inside a running capsule; the arguments are those of :func:`running_listing_document`.""" + _require_this_checkout(view, launcher_root, checkout_name, project) + checkout = view.listing.get("checkout", {}) + lines = [f"Checkout: {checkout.get('launcher-path', launcher_root)} ({checkout.get('name', checkout_name)})", + f"At launch, {view.at}:", Listing.from_document(view.listing).render(), ""] + if view.requests: + lines.append("Pending, next launch (asked on the console since launch):") + for item in view.requests: + result = item.get("result") + outcome = f"{result['status']}: {result['text']}" if isinstance(result, dict) else "waiting for the launcher" + lines.append(f" {item['id']}: {item['statement'] or '(unreadable request)'}\n {outcome}") + else: + lines.append("Nothing asked on the console since launch.") + lines.append(f"To change the next launch: the console's configuration page, or on the host: {launcher_command}") + return "\n".join(lines) diff --git a/devcapsule-src/devcapsule/commands/_launch_review.py b/devcapsule-src/devcapsule/commands/_launch_review.py index f25a96ba..89aaa862 100644 --- a/devcapsule-src/devcapsule/commands/_launch_review.py +++ b/devcapsule-src/devcapsule/commands/_launch_review.py @@ -33,7 +33,7 @@ from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import ( - authorization_declarations, normalize_authorization_value, render_authorization_value, + HOME_CAPABILITY_DEFAULTS, authorization_declarations, normalize_authorization_value, render_authorization_value, ) from devcapsule.configuration.capabilities import ( IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture, capability_notes, @@ -50,8 +50,8 @@ __all__ = [ "BLOCKING_KINDS", "Ask", "LaunchReview", "Prepared", "RunFlags", "capability", "channel_for", - "flags_after_upgrade", "refuse_contradictory_flags", "render_pending", "requested_ide", "review_launch", - "stage_trust", + "flags_after_upgrade", "launch_listing", "refuse_contradictory_flags", "render_pending", "requested_ide", + "review_launch", "stage_trust", ] BLOCKING_KINDS = {"ide", "env", "renew", "trust", "consent", "value", "secret"} @@ -151,6 +151,31 @@ def flags_after_upgrade(flags: RunFlags, host_overrides: Mapping[str, Any]) -> R )) +def launch_listing(state: CheckoutState, selected: ResolvedProject, checkout_name: str) -> dict[str, Any]: + """The ``config show --json`` document of a launch, which the launcher gives the capsule for its own inspection. + + It lists the checkout as this launch runs it, ``selected``, run-once + choices included, and the console's requests that await confirmation, + from ``state``. Each host access row also says what the access exposes + and, when the project recommends it, why. ``checkout_name`` is the name + the checkout is registered under. + """ + document = state.listing(selected.checkout).document() + declarations = authorization_declarations(selected.manifest, selected.lock) + for row in document["rows"]: + if row["kind"] == "access" and row["name"] in HOME_CAPABILITY_DEFAULTS: + row["exposure"] = HOME_CAPABILITY_DEFAULTS[row["name"]][1] + declaration = declarations[row["name"]] + row["reason"] = declaration.description if declaration.project_recommended else "" + identity = selected.manifest["project"] + return { + **document, + "context": "at launch", + "project": {"creator": identity["creator"], "slug": identity["slug"]}, + "checkout": {"name": checkout_name, "launcher-path": str(selected.root), "input": str(selected.checkout_path)}, + } + + def refuse_contradictory_flags(flags: RunFlags) -> None: """Refuse a command line that contradicts itself. It needs nothing but the flags.""" if flags.force and flags.ide is None: diff --git a/devcapsule-src/devcapsule/commands/_run_flow.py b/devcapsule-src/devcapsule/commands/_run_flow.py index eb1bcbb8..c7abdadd 100644 --- a/devcapsule-src/devcapsule/commands/_run_flow.py +++ b/devcapsule-src/devcapsule/commands/_run_flow.py @@ -30,8 +30,8 @@ from typing import Any, Callable, Mapping, TextIO from devcapsule.commands._launch_review import ( - LaunchReview, Prepared, RunFlags, capability, channel_for, refuse_contradictory_flags, render_pending, - requested_ide, review_launch, stage_trust, + LaunchReview, Prepared, RunFlags, capability, channel_for, launch_listing, refuse_contradictory_flags, + render_pending, requested_ide, review_launch, stage_trust, ) from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import HOME_CAPABILITY_DEFAULTS, authorization_declarations, normalize_authorization_value @@ -152,26 +152,10 @@ def load_launch_state(start: Path, flags: RunFlags) -> CheckoutState: def launch_listing_document(selected: ResolvedProject) -> dict[str, Any]: """The ``config show --json`` document of the launch's checkout, for the capsule's own inspection.""" - from devcapsule.configuration.storage import checkout_name_for state = load_state(selected.root, selected.manifest) for departure in selected.departures: state.depart(departure) - listing = state.listing(selected.checkout) - document = listing.document() - declarations = authorization_declarations(selected.manifest, selected.lock) - for row in document["rows"]: - if row["kind"] == "access" and row["name"] in HOME_CAPABILITY_DEFAULTS: - row["exposure"] = HOME_CAPABILITY_DEFAULTS[row["name"]][1] - declaration = declarations[row["name"]] - row["reason"] = declaration.description if declaration.project_recommended else "" - identity = selected.manifest["project"] - return { - **document, - "context": "at launch", - "project": {"creator": identity["creator"], "slug": identity["slug"]}, - "checkout": {"name": checkout_name_for(selected.manifest, selected.checkout_path), - "launcher-path": str(selected.root), "input": str(selected.checkout_path)}, - } + return launch_listing(state, selected, checkout_name_for(selected.manifest, selected.checkout_path)) def project_channel(root: Path, manifest: dict[str, Any], channel_id: str) -> Channel: diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 1bff5ffa..8ffa2d12 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -832,38 +832,20 @@ def run(cls, arguments: argparse.Namespace, context: object | None) -> int: def _show_inside_capsule(loaded: runtime_configuration.RuntimeConfiguration, as_json: bool) -> int: """Inside a capsule: the launcher's listing at launch and the console's requests since (answer 16).""" - from devcapsule.commands._console_channel import read_channel + from devcapsule.commands._console_channel import read_channel, render_running_listing, running_listing_document view = read_channel(runtime_configuration.CHANNEL_PATH) if runtime_configuration.CHANNEL_PATH.is_dir() else None if view is None: print(json.dumps(loaded.configuration_document(), indent=2, sort_keys=True) if as_json else loaded.configuration_report()) return 0 - checkout = view.listing.get("checkout") - identity = loaded.document["project"] - if (not isinstance(checkout, dict) or checkout.get("launcher-path") != loaded.document["launcher-root"] - or checkout.get("name") != loaded.checkout_name - or view.listing.get("project") != {key: identity[key] for key in ("creator", "slug")}): - raise ProjectConfigurationError("The channel listing belongs to another checkout; inspect configuration on the host.") - command = loaded.launcher_command(["config", "show"]) + capsule: dict[str, Any] = { + "launcher_root": loaded.document["launcher-root"], "checkout_name": loaded.checkout_name, + "project": loaded.document["project"], "launcher_command": loaded.launcher_command(["config", "show"]), + } if as_json: - print(json.dumps({**view.listing, "context": "running capsule: the launcher's listing at launch", "at": view.at, - "console-requests": list(view.requests), "launcher-command": command}, - indent=2, sort_keys=True)) - return 0 - checkout = view.listing.get("checkout", {}) - print(f"Checkout: {checkout.get('launcher-path', loaded.document['launcher-root'])} ({checkout.get('name', loaded.checkout_name)})") - print(f"At launch, {view.at}:") - print(Listing.from_document(view.listing).render()) - print("") - if view.requests: - print("Pending, next launch (asked on the console since launch):") - for item in view.requests: - result = item.get("result") - outcome = f"{result['status']}: {result['text']}" if isinstance(result, dict) else "waiting for the launcher" - print(f" {item['id']}: {item['statement'] or '(unreadable request)'}\n {outcome}") + print(json.dumps(running_listing_document(view, **capsule), indent=2, sort_keys=True)) else: - print("Nothing asked on the console since launch.") - print(f"To change the next launch: the console's configuration page, or on the host: {command}") + print(render_running_listing(view, **capsule)) return 0 diff --git a/devcapsule-src/devcapsule/configuration/console_requests.py b/devcapsule-src/devcapsule/configuration/console_requests.py index 721cc651..53784be0 100644 --- a/devcapsule-src/devcapsule/configuration/console_requests.py +++ b/devcapsule-src/devcapsule/configuration/console_requests.py @@ -21,7 +21,7 @@ from .listing import Decision, ListingRow from .storage import atomic_write, config_root, load_toml -__all__ = ["console_requests_path", "deferred_requests", "deferred_rows", "write_deferred"] +__all__ = ["console_requests_path", "deferred_requests", "deferred_rows", "request_rows", "write_deferred"] def console_requests_path(checkout_record: Path) -> Path: @@ -64,6 +64,15 @@ def deferred_rows(checkout_record: Path | None, project: Path | None) -> list[Li requests = deferred_requests(checkout_record) except (ProjectConfigurationError, ValueError) as exc: return [ListingRow("console", "*", "invalid", str(exc), "repair or remove the console-requests file", "")] + return request_rows(requests, project) + + +def request_rows(requests: Sequence[DeferredRequest], project: Path | None) -> list[ListingRow]: + """``requests`` as listing rows, each a soft decision whose command applies it on the host. + + ``project`` is the project's directory, for the command; None leaves the + command to the working directory. + """ rows: list[ListingRow] = [] context = ["--path", str(project)] if project is not None else [] for item in requests: diff --git a/devcapsule-src/tests/integration/test_console_channel_cli.py b/devcapsule-src/tests/integration/test_console_channel_cli.py index 47cb9422..5863c8fe 100644 --- a/devcapsule-src/tests/integration/test_console_channel_cli.py +++ b/devcapsule-src/tests/integration/test_console_channel_cli.py @@ -2,19 +2,48 @@ The launcher answers a request file by running ``devcapsule project config`` as a process of its own. So these tests run processes: the launcher's sweep -of a request directory, and the commands it starts, in an environment the -test builds. The home is named and lies under the test's directory, with -nothing accepted in it; the project is created there by ``project init``. +of a request directory, the commands it starts, and ``project run`` on a +pseudo-terminal where the launch asks about a kept request. -No command here needs Docker or the network. +What it takes for them to pass, and why the legacy file they replace, +``tests/test_console_channel.py``, passed under ``nox -s tests`` and failed +under ``.venv/bin/python -m pytest``: + +- The interpreter that runs pytest must be able to import ``devcapsule``: + every process here is ``sys.executable -m devcapsule`` or a ``-c`` program + that imports it. Nothing else is needed of the interpreter. +- Every process gets an environment the test builds, with a named home, + ``DEVCAPSULE_CONFIG_HOME``, under the test's directory. The launcher hands + that variable on to the commands it starts. +- The legacy file named no home. Its ``config`` commands were processes too, + and a process started inside a capsule with no named home and no settings + of its own reads the launcher's settings, mounted at + ``/etc/devcapsule/home``. Those settings carry ``minimum-devcapsule``, and + the command compares it with the version of the ``devcapsule`` + distribution installed in its interpreter. ``nox -s tests`` installs the + current version in its own environment, so the command went on. A + checkout's ``.venv`` that was installed long ago and never reinstalled + still says an old version, 0.2.15 in the case found, so every command was + refused with "requires DevCapsule 0.3.0; this launcher is 0.2.15" and the + tests saw ``refused`` where they expected ``recorded``. Outside a capsule + there is no mounted home and the legacy file passed with either + interpreter. +- No command needs the network. The launch tests put a stand-in where + ``docker`` is, which answers that no image is local and refuses to pull, + so a launch ends there, after its questions and its writes. """ from __future__ import annotations import json import os from pathlib import Path +import pty +import select +import stat import subprocess import sys +import time +import tomllib from typing import Any import pytest @@ -33,6 +62,29 @@ """ """The launcher's side of the channel, as a program: answer the requests in a directory and print how many.""" +ANSWER_WHILE_STOPPING = """ +import sys +from pathlib import Path +from devcapsule.commands._console_channel import handle_request +print(handle_request(Path(sys.argv[2]), Path(sys.argv[3]), Path(sys.argv[1]), stopping=True)["status"]) +""" +"""The launcher answering one request file while it stops, as a program: print the result's status.""" + +STAND_IN_DOCKER = """#!/bin/sh +# Stands where docker is. No image is local, and nothing else is done: a launch ends at its first pull. +if [ "$1 $2" = "image inspect" ]; then + echo "[]" + echo "Error response from daemon: No such image: $3" >&2 + exit 1 +fi +echo "the stand-in for docker was asked to: $*" >&2 +exit 97 +""" + +ASKED_AT = "2026-10-24T10:00:00+00:00" +KEPT_PROMPT = "Enter = keep it for later:" +"""The end of the question a launch puts for a request kept from the console.""" + class Capsule: """One project with its home and its channel directory, and the processes that act on them.""" @@ -43,9 +95,14 @@ def __init__(self, directory: Path) -> None: self.channel = directory / "channel" self.project.mkdir() self.channel.mkdir() + tools = directory / "tools" + tools.mkdir() + docker = tools / "docker" + docker.write_text(STAND_IN_DOCKER, encoding="utf-8") + docker.chmod(docker.stat().st_mode | stat.S_IXUSR) self.environment = { - "PATH": os.defpath, "HOME": str(directory / "home"), "DEVCAPSULE_CONFIG_HOME": str(self.home), - "PYTHONDONTWRITEBYTECODE": "1", + "PATH": f"{tools}{os.pathsep}{os.defpath}", "HOME": str(directory / "home"), + "DEVCAPSULE_CONFIG_HOME": str(self.home), "PYTHONDONTWRITEBYTECODE": "1", } def run(self, *command: str) -> subprocess.CompletedProcess[str]: @@ -69,14 +126,81 @@ def selection(self) -> LocalCapabilities: """The capabilities the checkout's record selects, omits and chooses providers for.""" return LocalCapabilities.read(load_toml(self.record)) + def ask(self, identifier: str, *arguments: str) -> Path: + """Put one request in the channel as the console writes it, asked at ``ASKED_AT``.""" + return write_complete(self.channel / f"{identifier}.request.json", + {"format": 1, "requested": ASKED_AT, "arguments": list(arguments)}) + def send(self, identifier: str, *arguments: str) -> dict[str, Any]: - """Put one request in the channel as the console writes it, let the launcher sweep, and return its result.""" - write_complete(self.channel / f"{identifier}.request.json", - {"format": 1, "requested": "2026-10-24T10:00:00+00:00", "arguments": list(arguments)}) + """Put one request in the channel, let the launcher sweep, and return its result.""" + self.ask(identifier, *arguments) swept = self.run("-c", SWEEP, str(self.channel), str(self.project), str(self.record)) assert swept.returncode == 0 and swept.stdout.strip() == "1", swept.stdout return read_document(self.channel / f"{identifier}.result.json") + def saved(self) -> dict[str, Any]: + """The checkout's record as it is on disk.""" + return load_toml(self.record) + + def planned(self) -> dict[str, Any]: + """The plan the last launch derived and wrote beside the record.""" + return tomllib.loads(self.record.with_name("devcapsule.resolved.toml").read_text(encoding="utf-8")) + + def kept(self) -> str: + """What ``config console list`` prints: the requests that await the host's confirmation.""" + listed = self.config("console", "list") + assert listed.returncode == 0, listed.stdout + return listed.stdout + + def ready_to_launch(self) -> None: + """Choose PyCharm and accept DevCapsule's channel for the home, so that a launch has nothing else to ask.""" + assert self.config("ide", "python-ide").returncode == 0 + accepted = self.run("-m", "devcapsule", "home", "trust", "accept", "devcapsule-base", "--yes") + assert accepted.returncode == 0, accepted.stdout + + def launch_at_a_terminal(self, answers: list[tuple[str, str]], *flags: str) -> str: + """``project run FLAGS`` on a pseudo-terminal; return all it showed. + + ``answers`` are the developer's, in order: each is typed when the + terminal's output ends with the prompt paired with it. The launch + ends where it would pull the base image, at the stand-in for Docker, + with every question asked and every answer written. + """ + terminal, launcher_side = pty.openpty() + process = subprocess.Popen( + [sys.executable, "-m", "devcapsule", "project", "--path", str(self.project), "run", "--no-update-check", *flags], + cwd=self.project, env=self.environment, stdin=launcher_side, stdout=launcher_side, stderr=launcher_side, + close_fds=True, + ) + os.close(launcher_side) + shown = b"" + waiting = list(answers) + deadline = time.monotonic() + 300 + try: + while time.monotonic() < deadline: + readable, _, _ = select.select([terminal], [], [], 0.2) + if readable: + try: + chunk = os.read(terminal, 4096) + except OSError: # Linux reports the launcher's closed side as an error, not as an empty read. + break + if not chunk: + break + shown += chunk + if waiting and shown.rstrip().endswith(waiting[0][0].encode()): + os.write(terminal, waiting.pop(0)[1].encode()) + elif process.poll() is not None: + break + process.wait(timeout=30) + finally: + if process.poll() is None: + process.kill() + os.close(terminal) + text = shown.decode(errors="replace") + assert not waiting, f"the launch never asked {waiting[0][0]!r}:\n{text}" + assert "the stand-in for docker was asked to: image pull" in text, text + return text + @pytest.fixture def capsule(tmp_path: Path) -> Capsule: @@ -133,3 +257,140 @@ def test_choices_recorded_through_the_channel_leave_their_vendors_consents_pendi assert shown.returncode == 0, shown.stdout pending = {row["name"] for row in json.loads(shown.stdout)["rows"] if row["pending"]} assert {"claude-code-download", "vscode-download"} <= pending + + +def test_a_widening_sent_through_the_channel_is_kept_and_shown_on_the_host_until_confirmed(capsule: Capsule) -> None: + """A request to put the capsule on the host's network is not applied: its result is ``deferred`` and names + the command that applies it, and the checkout's record has no answer for the network. On the host, + ``config show`` lists the request with what it stands for, and ``config console list`` with when it was asked.""" + deferred = capsule.send("000001-authorize", "authorize", "network", "host") + + assert deferred["status"] == "deferred" and "config console apply 000001-authorize" in deferred["text"] + assert "network" not in capsule.saved().get("authorization", {}) + shown = capsule.config("show") + assert shown.returncode == 0, shown.stdout + assert "000001-authorize" in shown.stdout and "confirm or discard: config authorize network host" in shown.stdout + assert f"000001-authorize asked {ASKED_AT}: config authorize network host" in capsule.kept() + + +def test_config_check_counts_a_kept_request_among_the_pending_decisions(capsule: Capsule) -> None: + """A checkout with nothing pending passes ``config check`` with exit status 0. With one request kept from + the console the same command exits 3.""" + capsule.ready_to_launch() + settled = capsule.config("check") + assert settled.returncode == 0, settled.stdout + + capsule.send("000001-authorize", "authorize", "network", "host") + + assert capsule.config("check").returncode == 3 + + +def test_console_apply_runs_the_kept_request_as_its_command_and_forgets_it(capsule: Capsule) -> None: + """``config console apply ID`` on the host runs the kept request: it prints the command's own output and + that the request was applied and forgotten, the record then holds the answer, and nothing is kept.""" + capsule.send("000001-authorize", "authorize", "network", "host") + + applied = capsule.config("console", "apply", "000001-authorize") + + assert applied.returncode == 0, applied.stdout + assert "Authorized network for this checkout: host" in applied.stdout and "Applied and forgot" in applied.stdout + assert capsule.saved()["authorization"]["network"]["value"] == "host" + assert "000001-authorize" not in capsule.kept() + + +def test_a_kept_request_that_its_command_refuses_stays_kept(capsule: Capsule) -> None: + """A kept request for an authorization that does not exist is refused by the command when applied, with + exit status 2, and still awaits on the host.""" + assert capsule.send("000001-authorize", "authorize", "quantum", "x")["status"] == "deferred" + + refused = capsule.config("console", "apply", "000001-authorize") + + assert refused.returncode == 2, refused.stdout + assert "000001-authorize" in capsule.kept() + + +def test_console_discard_forgets_a_kept_request_without_applying_it(capsule: Capsule) -> None: + """``config console discard ID`` forgets the request and changes nothing of the record. Discarding it + again, or applying a request that was never kept, exits 2.""" + capsule.send("000001-bind", "bind", "home", "~/capsule-home") + before = capsule.record.read_bytes() + + discarded = capsule.config("console", "discard", "000001-bind") + + assert discarded.returncode == 0, discarded.stdout + assert "000001-bind" not in capsule.kept() and capsule.record.read_bytes() == before + assert capsule.config("console", "discard", "000001-bind").returncode == 2 + assert capsule.config("console", "apply", "000009-never-asked").returncode == 2 + + +@pytest.mark.parametrize(("node", "value", "recorded"), [ + ("network", "bridge", "bridge"), ("docker-daemon", "none", "none"), ("host-browser", "false", False), +]) +def test_an_authorization_of_the_secure_value_is_recorded_without_the_hosts_confirmation( + capsule: Capsule, node: str, value: str, recorded: object, +) -> None: + """``authorize`` with the value that grants nothing is applied at once by the real command: the result is + ``recorded``, the record holds the value, and nothing is kept for the host.""" + assert capsule.send("000001-authorize", "authorize", node, value)["status"] == "recorded" + + assert capsule.saved()["authorization"][node]["value"] == recorded + assert "000001-authorize" not in capsule.kept() + + +@pytest.mark.parametrize("save", [False, True]) +def test_a_kept_request_applied_at_the_launchs_question_is_used_by_that_launch_and_recorded(capsule: Capsule, save: bool) -> None: + """A launch on a terminal asks about the kept request, saying when the console asked and what. Answered + ``a``, the request's command runs: the Docker daemon is authorized in the record and in the plan of this + very launch, and nothing is kept. ``--memory`` given beside it is recorded with ``--save`` and not without, + so applying the request neither loses nor writes the launch's own flags.""" + capsule.ready_to_launch() + capsule.send("000001-authorize", "authorize", "docker-daemon", "host-socket") + + shown = capsule.launch_at_a_terminal([(KEPT_PROMPT, "a\n")], "--memory", "6g", *(["--save"] if save else [])) + + assert f"The console asked at {ASKED_AT}: config authorize docker-daemon host-socket" in shown + assert capsule.saved()["authorization"]["docker-daemon"]["value"] == "host-socket" + assert capsule.planned()["authorization"]["docker-daemon"] == "host-socket" + assert capsule.saved().get("configuration", {}).get("values", {}) == ({"memory": "6GiB"} if save else {}) + assert "000001-authorize" not in capsule.kept() + + +def test_a_kept_request_left_at_the_launchs_question_stays_kept_and_the_launch_goes_on(capsule: Capsule) -> None: + """Answered with Enter, the request is neither applied nor discarded: the launch says it was kept and how + to apply or discard it later, goes on, and the request still awaits with the record unchanged.""" + capsule.ready_to_launch() + capsule.send("000001-authorize", "authorize", "network", "host") + + shown = capsule.launch_at_a_terminal([(KEPT_PROMPT, "\n")]) + + assert "Kept. Apply or discard later:" in shown and "config console apply 000001-authorize" in shown + assert "network" not in capsule.saved().get("authorization", {}) + assert "000001-authorize" in capsule.kept() + + +def test_a_kept_forget_applied_at_the_launch_removes_the_grant_and_keeps_the_flags_saved_beside_it(capsule: Capsule) -> None: + """The checkout had authorized the host's network, and the console asked to forget that answer. Applied at + the launch's question, the grant is gone from the record and from this launch's plan, and the memory given + with ``--save`` in the same launch is recorded.""" + capsule.ready_to_launch() + assert capsule.config("authorize", "network", "host").returncode == 0 + assert capsule.send("000001-forget", "forget", "network")["status"] == "deferred" + + capsule.launch_at_a_terminal([(KEPT_PROMPT, "a\n")], "--memory", "6g", "--save") + + assert "network" not in capsule.saved().get("authorization", {}) + assert "network" not in capsule.planned()["authorization"] + assert capsule.saved()["configuration"]["values"] == {"memory": "6GiB"} + + +def test_a_request_kept_because_the_launcher_was_stopping_is_applied_at_the_next_launch_beside_its_flags(capsule: Capsule) -> None: + """A request the launcher would apply at once is kept when it arrives while the launcher stops. At the + next launch it is asked; applied there, its value and the one given with ``--save`` are both recorded.""" + capsule.ready_to_launch() + request = capsule.ask("000001-set", "set", "cpus", "2") + stopping = capsule.run("-c", ANSWER_WHILE_STOPPING, str(request), str(capsule.project), str(capsule.record)) + assert stopping.returncode == 0 and stopping.stdout.strip() == "deferred", stopping.stdout + + capsule.launch_at_a_terminal([(KEPT_PROMPT, "a\n")], "--memory", "6g", "--save") + + assert capsule.saved()["configuration"]["values"] == {"memory": "6GiB", "cpus": 2} diff --git a/devcapsule-src/tests/integration/test_pex_runtime.py b/devcapsule-src/tests/integration/test_pex_runtime.py index 6f972b52..78f4b45e 100644 --- a/devcapsule-src/tests/integration/test_pex_runtime.py +++ b/devcapsule-src/tests/integration/test_pex_runtime.py @@ -1,3 +1,15 @@ +"""Integration tests of the built launcher: the one-file executable, run as a developer runs it. + +Each test starts the executable that ``built_pex`` names, in an environment +the test builds: the search path, a home directory and a named DevCapsule +home under the test's directory, and the two caches the executable unpacks +itself into, which the suite keeps for the whole run. Nothing else of the +developer's shell reaches it, so the outcome is the same on a plain host and +inside a capsule, where an unnamed home would read the launcher's mounted +settings. + +No test here needs Docker or the network. +""" from __future__ import annotations import json @@ -15,7 +27,7 @@ import tomllib from devcapsule.host_open import HOST_OPEN_SOCKET_ENV, HostOpenBroker -pytestmark = pytest.mark.legacy +pytestmark = pytest.mark.integration # The artifact under test is built from this tree, so compare against the # authored version, not installed metadata an editable install may have frozen. @@ -26,26 +38,41 @@ )["project"]["version"] -@pytest.mark.integration -def test_built_pex_dispatches_runtime_help(built_pex: Path) -> None: +@pytest.fixture +def environment(tmp_path: Path) -> dict[str, str]: + """The environment every executable here is started in: a search path, a home and a named DevCapsule home + under the test's directory, and the executable's own caches.""" + return { + "PATH": os.environ["PATH"], + "HOME": str(tmp_path / "home"), + "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "devcapsule-home"), + **{name: os.environ[name] for name in ("PEX_ROOT", "SCIE_BASE") if name in os.environ}, + } + + +def test_built_pex_dispatches_runtime_help(built_pex: Path, environment: dict[str, str]) -> None: + """The executable carries the in-capsule runtime: ``runtime --help`` exits 0 with that command's usage.""" completed = subprocess.run( [str(built_pex), "runtime", "--help"], check=False, text=True, capture_output=True, + env=environment, ) assert completed.returncode == 0, completed.stderr assert "usage: devcapsule runtime RUNTIME_PLAN.json" in completed.stdout -@pytest.mark.integration -def test_built_pex_exposes_recursive_preflight_help(built_pex: Path) -> None: +def test_built_pex_exposes_recursive_preflight_help(built_pex: Path, environment: dict[str, str]) -> None: + """The recursive end-to-end commands are in the executable: ``preflight --help`` offers ``--show-host-paths`` + and ``run --help`` offers ``--keep-on-failure``.""" completed = subprocess.run( [str(built_pex), "project", "recursive-e2e", "preflight", "--help"], check=False, text=True, capture_output=True, + env=environment, ) assert completed.returncode == 0, completed.stderr @@ -57,15 +84,17 @@ def test_built_pex_exposes_recursive_preflight_help(built_pex: Path) -> None: check=False, text=True, capture_output=True, + env=environment, ) assert run_help.returncode == 0, run_help.stderr assert "--keep-on-failure" in run_help.stdout -@pytest.mark.integration def test_built_pex_bootstraps_packaged_workflow( - built_pex: Path, tmp_path: Path + built_pex: Path, tmp_path: Path, environment: dict[str, str], ) -> None: + """``bootstrap`` in an empty directory writes the workflow definition that the package carries, byte for + byte, and a status file of a single-stream project.""" project = tmp_path / "adopter" project.mkdir() @@ -75,6 +104,7 @@ def test_built_pex_bootstraps_packaged_workflow( text=True, capture_output=True, cwd=project, + env=environment, ) assert completed.returncode == 0, completed.stderr @@ -91,8 +121,8 @@ def test_built_pex_bootstraps_packaged_workflow( ).read_text(encoding="utf-8") -@pytest.mark.integration -def test_built_pex_exposes_recursive_host_public_interface(built_pex: Path) -> None: +def test_built_pex_exposes_recursive_host_public_interface(built_pex: Path, environment: dict[str, str]) -> None: + """Run as an interpreter, the executable imports ``devcapsule.recursive_host`` and its launch context class.""" completed = subprocess.run( [ str(built_pex), @@ -103,18 +133,20 @@ def test_built_pex_exposes_recursive_host_public_interface(built_pex: Path) -> N check=False, text=True, capture_output=True, - env={**os.environ, "PEX_INTERPRETER": "1"}, + env={**environment, "PEX_INTERPRETER": "1"}, ) assert completed.returncode == 0, completed.stderr assert completed.stdout.strip() == "HostDaemonLaunchContext" -@pytest.mark.integration def test_xdg_open_dispatches_through_built_pex_to_exact_host_argument( built_pex: Path, tmp_path: Path, + environment: dict[str, str], ) -> None: + """``xdg-open URL``, with the executable's ``host-open`` as the browser, hands the broker's opener the URL + exactly as given, shell characters and all.""" xdg_open = shutil.which("xdg-open") if xdg_open is None: pytest.skip("xdg-open is unavailable on this packaging-test host") @@ -135,7 +167,7 @@ def test_xdg_open_dispatches_through_built_pex_to_exact_host_argument( text=True, capture_output=True, env={ - **os.environ, + **environment, "BROWSER": f"{built_pex} host-open", HOST_OPEN_SOCKET_ENV: str(socket_path), "DISPLAY": "", @@ -148,13 +180,15 @@ def test_xdg_open_dispatches_through_built_pex_to_exact_host_argument( assert captured.read_text(encoding="utf-8") == url -@pytest.mark.integration -def test_built_pex_exposes_self_contained_source_identity(built_pex: Path) -> None: +def test_built_pex_exposes_self_contained_source_identity(built_pex: Path, environment: dict[str, str]) -> None: + """``version --json`` gives the six fields of the executable's identity. The version is the one this tree + declares; a local build has no source revision, a release build names its commit.""" completed = subprocess.run( [str(built_pex), "version", "--json"], check=False, text=True, capture_output=True, + env=environment, ) assert completed.returncode == 0, completed.stderr @@ -182,13 +216,15 @@ def test_built_pex_exposes_self_contained_source_identity(built_pex: Path) -> No } -@pytest.mark.integration def test_built_pex_authors_shared_policy_and_keeps_personal_selection_local( - built_pex: Path, tmp_path: Path, + built_pex: Path, tmp_path: Path, environment: dict[str, str], ) -> None: + """A developer's own choices, an IDE, an omitted offer, an added agent, change no file of the project's + shared directory. The base then waits for the home's trust: ``config check`` exits 3 until the channel is + accepted for the home, and 0 after. A requirement in the retired ``TOOL=MAJOR`` form is refused and changes + nothing shared.""" project = tmp_path / "capability-project" project.mkdir() - environment = {**os.environ, "XDG_CONFIG_HOME": str(tmp_path / "config")} def invoke(*arguments: str) -> subprocess.CompletedProcess[str]: return subprocess.run([str(built_pex), "project", "--path", str(project), *arguments], cwd=project, env=environment, text=True, capture_output=True, check=False) @@ -204,8 +240,8 @@ def invoke(*arguments: str) -> subprocess.CompletedProcess[str]: assert {path.name: path.read_bytes() for path in directory.iterdir()} == shared # The base channel is a home decision since 0.3.0 rc4: until it is # trusted, or the base consented to per checkout, 'check' reports it as - # pending with status 3. The trust record lives under the isolated - # XDG_CONFIG_HOME above, so accepting it here touches nothing shared. + # pending with status 3. The trust record lives in the named home of + # this test, so accepting it here touches nothing shared. pending = invoke("config", "check") assert pending.returncode == 3 and "trust accept devcapsule-base" in pending.stderr, pending.stdout trusted = subprocess.run([str(built_pex), "home", "trust", "accept", "devcapsule-base", "--yes"], @@ -220,8 +256,9 @@ def invoke(*arguments: str) -> subprocess.CompletedProcess[str]: assert {path.name: path.read_bytes() for path in directory.iterdir()} == shared -@pytest.mark.integration -def test_built_pex_carries_force_for_a_required_ide_to_the_launch_review(built_pex: Path, tmp_path: Path) -> None: +def test_built_pex_carries_force_for_a_required_ide_to_the_launch_review( + built_pex: Path, tmp_path: Path, environment: dict[str, str], +) -> None: """``run --ide IDE --force`` reaches preparation through the built executable; the refusals name it. The forced launch itself materializes the requested IDE, which needs the @@ -229,15 +266,13 @@ def test_built_pex_carries_force_for_a_required_ide_to_the_launch_review(built_p """ project = tmp_path / "required-ide" project.mkdir() - environment = {**os.environ, "HOME": str(tmp_path / "home"), "XDG_CONFIG_HOME": str(tmp_path / "config"), - "XDG_STATE_HOME": str(tmp_path / "state"), "XDG_DATA_HOME": str(tmp_path / "data")} def invoke(*arguments: str) -> subprocess.CompletedProcess[str]: return subprocess.run([str(built_pex), "project", "--path", str(project), *arguments], cwd=project, env=environment, text=True, capture_output=True, check=False) created = invoke("init", "--require", "python", "--require", "python-ide", "--ide", "python-ide", "--creator", "mailto:fixture@example.test", "--authorize", "base-image", "default") assert created.returncode == 0, created.stderr - records = sorted((tmp_path / "config").rglob("*.toml")) + records = sorted((tmp_path / "devcapsule-home").rglob("*.toml")) assert records, "init registers the checkout and derives its resolution" before = {path: path.read_bytes() for path in (*records, *sorted((project / ".devcapsule").iterdir()))} helped = invoke("run", "--help") diff --git a/devcapsule-src/tests/test_console_channel.py b/devcapsule-src/tests/test_console_channel.py deleted file mode 100644 index 1a891d03..00000000 --- a/devcapsule-src/tests/test_console_channel.py +++ /dev/null @@ -1,543 +0,0 @@ -"""The console's configuration channel on the launcher's side: results, deferral, the in-capsule listing, the commands.""" - -from __future__ import annotations - -import io -import json -from pathlib import Path -from unittest.mock import patch - -import pytest - -from devcapsule import cli -from devcapsule.commands._console_channel import ChannelWatcher, handle_request, read_channel, run_config, sweep -from devcapsule.commands._run_flow import RunFlags, launch_listing_document, prepare_launch -from devcapsule.configuration.capability_commands import paths -from devcapsule.configuration.console_channel import ( - Disposition, classify, listing_document, parse_request, read_document, request_id, write_complete, -) -from devcapsule.configuration.console_requests import console_requests_path, deferred_requests -from devcapsule.configuration.file_formats import ProjectConfigurationError -from devcapsule.configuration.storage import checkout_record_paths, load_toml -from devcapsule import runtime_configuration - -pytestmark = pytest.mark.legacy - - -@pytest.fixture -def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: - for key in ("HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"): - monkeypatch.setenv(key, str(tmp_path / key.lower())) - root = tmp_path / "project" - root.mkdir() - assert cli.main(["project", "--path", str(root), "init", "--require", "node", "--creator", "mailto:owner@example.test"]) == 0 - return root - - -def config(root: Path, *arguments: str) -> int: - return cli.main(["project", "--path", str(root), "config", *arguments]) - - -def record_path(root: Path) -> Path: - return checkout_record_paths(load_toml(paths(root)[0]), root)[0] - - -def request(directory: Path, identifier: str, *arguments: str) -> Path: - path = directory / f"{identifier}.request.json" - write_complete(path, {"format": 1, "requested": "2026-10-24T10:00:00+00:00", "arguments": list(arguments)}) - return path - - -def result(directory: Path, identifier: str) -> dict: - return read_document(directory / f"{identifier}.result.json") - - -@pytest.mark.parametrize("arguments, expected", [ - (["ide", "python-ide"], Disposition.APPLY), (["env", "set", "X", "1"], Disposition.APPLY), - (["deny", "network"], Disposition.APPLY), (["trust", "withdraw", "x"], Disposition.APPLY), - (["docker-args", "clear"], Disposition.APPLY), - (["authorize", "network", "host"], Disposition.DEFER), (["trust", "accept", "x"], Disposition.DEFER), - (["bind", "x", "y"], Disposition.DEFER), (["docker-args", "set", "--privileged"], Disposition.DEFER), - (["show"], Disposition.REFUSE), (["env", "list"], Disposition.REFUSE), (["default", "memory", "8G"], Disposition.REFUSE), - (["require", "x"], Disposition.REFUSE), (["run"], Disposition.REFUSE), ([], Disposition.REFUSE), -]) -def test_classification(arguments: list[str], expected: Disposition) -> None: - disposition, reason = classify(arguments) - assert disposition is expected and bool(reason) == (expected is Disposition.REFUSE) - - -def test_request_documents_are_validated(tmp_path: Path) -> None: - assert request_id(Path("000001-ide.request.json")) == "000001-ide" - for name in ("x.json", "1-ide.request.json", "000001-Ide.request.json"): - with pytest.raises(ProjectConfigurationError): - request_id(Path(name)) - assert parse_request({"format": 1, "arguments": ["ide", "x"]}) == ["ide", "x"] - documents: list[object] = [{"format": 2, "arguments": ["ide"]}, {"format": 1, "arguments": []}, {"format": 1, "arguments": ["a\nb"]}, - {"format": 1, "arguments": ["ide", "--path", "/x"]}, {"format": 1, "arguments": ["x" * 5000]}, {"format": 1, "arguments": ["ide", "\ud800"]}, []] - for document in documents: - with pytest.raises(ProjectConfigurationError): - parse_request(document) - (tmp_path / "link.json").symlink_to(tmp_path / "missing") - with pytest.raises(ProjectConfigurationError, match="cannot open"): - read_document(tmp_path / "link.json") - big = tmp_path / "big.json" - big.write_text("[" + "1," * 200000 + "1]") - with pytest.raises(ProjectConfigurationError, match="larger than"): - read_document(big) - path = write_complete(tmp_path / "doc.json", {"a": 1}) - assert read_document(path) == {"a": 1} and not list(tmp_path.glob(".doc.json.*")) - - -def test_an_applied_request_runs_the_config_command_and_reports_its_output(project: Path, tmp_path: Path) -> None: - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-ide", "ide", "python-ide") - request(channel, "000002-ide", "ide", "no-such-ide") - assert sweep(channel, project, record_path(project)) == 2 - recorded = result(channel, "000001-ide") - assert recorded["status"] == "recorded" and "python-ide" in recorded["text"] - assert load_toml(record_path(project))["capabilities"]["selected"] == ["python-ide"] - refused = result(channel, "000002-ide") - assert refused["status"] == "refused" and "no-such-ide" in refused["text"] - assert sweep(channel, project, record_path(project)) == 0 # answered requests are never run twice - - -def test_a_widening_is_deferred_until_confirmed_on_the_host(project: Path, tmp_path: Path, capsys) -> None: - assert config(project, "ide", "python-ide") == 0 - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-authorize", "authorize", "network", "host") - request(channel, "000002-ide", "ide") # malformed: refused by the command, not by the launcher - request(channel, "000003-show", "show") - assert sweep(channel, project, record_path(project)) == 3 - deferred = result(channel, "000001-authorize") - assert deferred["status"] == "deferred" and "console apply 000001-authorize" in deferred["text"] - assert result(channel, "000003-show")["status"] == "refused" - assert "network" not in load_toml(record_path(project)).get("authorization", {}) - kept = deferred_requests(record_path(project)) - assert [item.id for item in kept] == ["000001-authorize"] and kept[0].statement == "config authorize network host" - assert not str(console_requests_path(record_path(project))).startswith(str(record_path(project).parent)) - capsys.readouterr() - # The host's listing shows it, pending and soft; check does not block on it, run asks. - assert config(project, "show") == 0 - shown = capsys.readouterr().out - assert "000001-authorize" in shown and "confirm or discard: config authorize network host" in shown - assert config(project, "check") == 3 - assert config(project, "console", "list") == 0 - assert "000001-authorize asked 2026-10-24T10:00:00+00:00: config authorize network host" in capsys.readouterr().out - prompts = io.StringIO() - prepared = prepare_launch(project, RunFlags(), interactive=True, input_stream=io.StringIO("\n"), output_stream=prompts) - assert "The console asked at 2026-10-24T10:00:00+00:00: config authorize network host" in prompts.getvalue() - assert deferred_requests(record_path(project)) # kept - prepared = prepare_launch(project, RunFlags(), interactive=False) - assert any("000001-authorize" in note and "console apply" in note for note in prepared.notes) - prompts = io.StringIO() - prepare_launch(project, RunFlags(), interactive=True, input_stream=io.StringIO("a\n"), output_stream=prompts) - assert load_toml(record_path(project))["authorization"]["network"]["value"] == "host" - assert deferred_requests(record_path(project)) == [] - request(channel, "000004-bind", "bind", "x", "y") - sweep(channel, project, record_path(project)) - assert config(project, "console", "discard", "000004-bind") == 0 - assert deferred_requests(record_path(project)) == [] - assert config(project, "console", "discard", "000004-bind") == 2 - assert config(project, "console", "apply", "000009-x") == 2 - - -def test_console_apply_runs_the_command_and_forgets_the_request(project: Path, tmp_path: Path, capsys) -> None: - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-authorize", "authorize", "network", "host") - sweep(channel, project, record_path(project)) - assert config(project, "console", "apply", "000001-authorize") == 0 - out = capsys.readouterr().out - assert "Authorized network for this checkout: host" in out and "Applied and forgot" in out - assert deferred_requests(record_path(project)) == [] - request(channel, "000002-authorize", "authorize", "quantum", "x") - sweep(channel, project, record_path(project)) - assert config(project, "console", "apply", "000002-authorize") == 2 - assert [item.id for item in deferred_requests(record_path(project))] == ["000002-authorize"] # kept after a refusal - - -def test_the_watcher_answers_while_running_and_once_more_on_stop(project: Path, tmp_path: Path) -> None: - channel = tmp_path / "channel" - channel.mkdir() - watcher = ChannelWatcher(channel, project, record_path(project), interval=0.05) - watcher.start() - request(channel, "000001-deny", "deny", "network") - for _ in range(200): - if (channel / "000001-deny.result.json").exists(): - break - import time - time.sleep(0.05) - assert result(channel, "000001-deny")["status"] == "recorded" - watcher.stop() - request(channel, "000002-forget", "forget", "network") - assert sweep(channel, project, record_path(project)) == 1 - - -def test_inside_a_capsule_show_prints_the_launch_listing_and_the_requests(project: Path, tmp_path: Path, monkeypatch, capsys) -> None: - assert config(project, "ide", "python-ide") == 0 - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - prepared = prepare_launch(project, RunFlags(), interactive=False) - listing = launch_listing_document(prepared.selected) - assert listing["context"] == "at launch" and listing["checkout"]["name"] == "default" - assert any(row["kind"] == "ide" and row["name"] == "python-ide" for row in listing["rows"]) - channel = tmp_path / "channel" - channel.mkdir() - write_complete(channel / "listing.json", listing_document(listing, "2026-10-24T12:00:00+00:00")) - request(channel, "000001-ide", "ide", "frontend-ide") - write_complete(channel / "000001-ide.result.json", {"format": 1, "status": "recorded", "text": "done", "at": "t"}) - request(channel, "000002-authorize", "authorize", "network", "host") - view = read_channel(channel) - assert view is not None and view.at == "2026-10-24T12:00:00+00:00" and len(view.requests) == 2 - assert view.requests[1]["result"] is None - # The in-capsule command reads the channel through the runtime context. - monkeypatch.setattr(runtime_configuration, "CHANNEL_PATH", channel) - context = runtime_configuration.RuntimeConfiguration({"format": 1, "project": listing["project"], "launcher-root": str(project), - "runtime-root": "/workspace/project", "checkout-file": "devcapsule.checkout.toml", - "checkout-name": "default"}) - from devcapsule.commands.project import _show_inside_capsule - assert _show_inside_capsule(context, False) == 0 - out = capsys.readouterr().out - assert "At launch, 2026-10-24T12:00:00+00:00:" in out and "python-ide" in out - assert "000001-ide: config ide frontend-ide" in out and "recorded: done" in out - assert "000002-authorize: config authorize network host" in out and "waiting for the launcher" in out - assert "config show" in out - assert _show_inside_capsule(context, True) == 0 - document = json.loads(capsys.readouterr().out) - assert document["at"] == "2026-10-24T12:00:00+00:00" and len(document["console-requests"]) == 2 - assert document["rows"] == listing["rows"] - # A valid listing from another checkout cannot stand in for this run. - foreign = {**listing, "checkout": {**listing["checkout"], "launcher-path": "/other"}} - write_complete(channel / "listing.json", listing_document(foreign)) - with pytest.raises(ProjectConfigurationError, match="another checkout"): - _show_inside_capsule(context, True) - (channel / "listing.json").unlink() - with pytest.raises(ProjectConfigurationError, match="no launch listing"): - _show_inside_capsule(context, False) - # Without the launcher's listing, the older read-only report stays. - monkeypatch.setattr(runtime_configuration, "CHANNEL_PATH", tmp_path / "absent") - with patch.object(runtime_configuration.RuntimeConfiguration, "configuration_report", return_value="legacy report"): - assert _show_inside_capsule(context, False) == 0 - assert "legacy report" in capsys.readouterr().out - - -@pytest.mark.parametrize("tokens", [ - ["forget", "docker-daemon"], ["env", "set", "HOST_SECRET", "--from-host"], - ["env", "set", "HOST_SECRET", "--from-h"], -]) -def test_indirect_widenings_never_run_in_the_watcher(project, tmp_path, tokens): - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-change", *tokens) - with patch("devcapsule.commands._console_channel.run_config") as run: - assert sweep(channel, project, record_path(project)) == 1 - run.assert_not_called() - assert deferred_requests(record_path(project))[0].arguments == tuple(tokens) - assert result(channel, "000001-change")["status"] == "deferred" - - -def test_same_request_name_in_later_run_preserves_both_requests(project, tmp_path): - for name, node in (("first", "network"), ("second", "docker-daemon")): - channel = tmp_path / name - channel.mkdir() - request(channel, "000001-authorize", "authorize", node, "host" if node == "network" else "host-socket") - sweep(channel, project, record_path(project)) - kept = deferred_requests(record_path(project)) - assert len(kept) == 2 and kept[0].id != kept[1].id - assert [item.arguments[1] for item in kept] == ["network", "docker-daemon"] - assert kept[1].id in result(channel, "000001-authorize")["text"] - - -def test_store_follows_checkout_path_not_registration_name(project, tmp_path): - import shutil - from devcapsule.configuration.storage import named_checkout_record_paths - channel = tmp_path / "channel" - channel.mkdir() - assert config(project, "deny", "network") == 0 - request(channel, "000001-authorize", "authorize", "network", "host") - sweep(channel, project, record_path(project)) - original = record_path(project) - stored = console_requests_path(original) - assert config(project, "forget", "network") == 0 - assert len(deferred_requests(original)) == 1 - renamed, _ = named_checkout_record_paths(load_toml(paths(project)[0]), "renamed") - renamed.parent.mkdir(parents=True, exist_ok=True) - original.rename(renamed) - assert console_requests_path(renamed) == stored and len(deferred_requests(renamed)) == 1 - second = tmp_path / "second" - shutil.copytree(project, second) - assert cli.main(["project", "--path", str(second), "checkout", "register", "second"]) == 0 - other = record_path(second) - other.rename(original) # Reuse the first checkout's old registration slot. - other = original - assert console_requests_path(other) != stored and deferred_requests(other) == [] - request(channel, "000002-authorize", "authorize", "docker-daemon", "host-socket") - sweep(channel, second, other) - assert [item.arguments[1] for item in deferred_requests(other)] == ["docker-daemon"] - assert [item.arguments[1] for item in deferred_requests(renamed)] == ["network"] - - -@pytest.mark.parametrize("kind", ["link", "fifo", "huge", "partial"]) -def test_bad_request_cannot_block_other_requests(project, tmp_path, kind): - import os - channel = tmp_path / "channel" - channel.mkdir() - bad = channel / "000001-ide.request.json" - if kind == "link": - bad.symlink_to(record_path(project)) - elif kind == "fifo": - os.mkfifo(bad) - elif kind == "huge": - bad.write_bytes(b" " * (256 * 1024 + 1)) - else: - bad.write_text('{"format":') - (channel / "outside.request.json").write_text("{}") - request(channel, "000002-deny", "deny", "network") - assert sweep(channel, project, record_path(project)) == 2 - assert result(channel, "000001-ide")["status"] == "refused" - assert result(channel, "000002-deny")["status"] == "recorded" - assert not (channel / "outside.result.json").exists() - - -def test_stop_keeps_pending_requests_without_running_more_children(project, tmp_path): - channel = tmp_path / "channel" - channel.mkdir() - watcher = ChannelWatcher(channel, project, record_path(project), interval=3600) - watcher.start() - request(channel, "000001-ide", "ide", "frontend-ide") - request(channel, "000002-authorize", "authorize", "docker-daemon", "host-socket") - with patch("devcapsule.commands._console_channel.run_config") as run: - watcher.stop() - run.assert_not_called() - assert not watcher._thread.is_alive() - assert [item.arguments[0] for item in deferred_requests(record_path(project))] == ["ide", "authorize"] - assert result(channel, "000001-ide")["status"] == "deferred" - assert "stopping" in result(channel, "000001-ide")["text"] - - -def test_child_has_no_host_secret_python_injection_or_terminal(project, tmp_path, monkeypatch): - import os - import sys - from devcapsule.commands import _console_channel as adapter - monkeypatch.setenv("HOST_SECRET", "never expose") - monkeypatch.setenv("PYTHONPATH", str(tmp_path)) - script = "import os,sys,json; print(json.dumps([dict(os.environ),os.getsid(0),os.getpid(),sys.stdin.read()]))" - monkeypatch.setattr(adapter, "_config_command", lambda root, args: [sys.executable, "-c", script]) - status, output = adapter.run_config(project, []) - environment, session, pid, stdin = json.loads(output) - assert status == 0 and session == pid and session != os.getsid(0) and stdin == "" - assert "HOST_SECRET" not in environment and "PYTHONPATH" not in environment - assert environment["XDG_CONFIG_HOME"] == os.environ["XDG_CONFIG_HOME"] - monkeypatch.setenv("DOCKER_HOST", "ssh://host-context.example") - status, output = adapter.run_config(project, [], host_confirmed=True) - confirmed_environment = json.loads(output)[0] - assert status == 0 and confirmed_environment["DOCKER_HOST"] == "ssh://host-context.example" - assert confirmed_environment["HOST_SECRET"] == "never expose" - # A descendant inherits the output pipe. Killing only its parent would - # let it finish its write and keep communicate() waiting for that pipe. - import time - started, escaped = tmp_path / "started", tmp_path / "escaped" - descendant = (f"from pathlib import Path; import time; Path({str(started)!r}).touch(); " - f"time.sleep(0.8); Path({str(escaped)!r}).touch()") - parent = f"import subprocess,sys,time; subprocess.Popen([sys.executable, '-c', {descendant!r}]); time.sleep(30)" - monkeypatch.setattr(adapter, "COMMAND_TIMEOUT_SECONDS", 0.3) - monkeypatch.setattr(adapter, "_config_command", lambda root, args: [sys.executable, "-c", parent]) - assert adapter.run_config(project, []) == (1, "the command did not finish within 0.3 seconds") - assert started.exists() - time.sleep(0.9) - assert not escaped.exists() - - -def test_apply_preserves_exact_tokens(project): - from devcapsule.commands._console_channel import apply_deferred - from devcapsule.configuration.console_channel import DeferredRequest - from devcapsule.configuration.console_requests import write_deferred - tokens = ("docker-args", "set", "--env", "TEXT=a b;$(false)") - write_deferred(record_path(project), [DeferredRequest("000001-docker-args", "now", tokens)]) - with patch("devcapsule.commands._console_channel.run_config", return_value=(0, "done")) as run: - assert apply_deferred(project, record_path(project), "000001-docker-args") == (0, "done") - run.assert_called_once_with(project, tokens, host_confirmed=True) - assert deferred_requests(record_path(project)) == [] - - -def test_launch_listing_includes_run_once_selection_and_earlier_requests(project, tmp_path): - assert config(project, "ide", "python-ide") == 0 - assert config(project, "recommend", "docker-daemon", "host-socket", "--because", "Project build containers") == 0 - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-authorize", "authorize", "network", "host") - sweep(channel, project, record_path(project)) - prepared = prepare_launch(project, RunFlags(ide="frontend-ide", capabilities=("codex",)), interactive=False) - listing = launch_listing_document(prepared.selected) - assert any(row["kind"] == "ide" and row["name"] == "frontend-ide" for row in listing["rows"]) - assert any(row["kind"] == "console" and row["name"] == "000001-authorize" for row in listing["rows"]) - exposure = next(row for row in listing["rows"] if row["name"] == "docker-daemon") - assert "broad control of the host" in exposure["exposure"] - assert exposure["reason"] == "Project build containers" - assert "codex" in prepared.selected.lock["components"] - assert any(row["kind"] == "capability" and "codex" in row["name"] for row in listing["rows"]) - assert load_toml(record_path(project))["capabilities"]["selected"] == ["python-ide"] - - -def test_channel_requires_its_listing_and_contains_unreadable_results(tmp_path): - import os - with pytest.raises(ProjectConfigurationError, match="no launch listing"): - read_channel(tmp_path) - write_complete(tmp_path / "listing.json", listing_document({"rows": []})) - request(tmp_path, "000001-ide", "ide", "python-ide") - result_path = tmp_path / "000001-ide.result.json" - for document in ({}, {"format": 1, "status": "recorded"}): - write_complete(result_path, document) - view = read_channel(tmp_path) - assert view is not None and "Cannot read" in view.requests[0]["result"]["text"] - assert view.requests[0]["result"]["status"] == "unknown" - result_path.unlink() - os.mkfifo(result_path) - view = read_channel(tmp_path) - assert view is not None and "not a regular file" in view.requests[0]["result"]["text"] - - -@pytest.mark.parametrize("save", [False, True]) -def test_confirmed_console_request_is_used_this_launch_and_not_overwritten(project, tmp_path, save): - assert config(project, "ide", "python-ide") == 0 - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-authorize", "authorize", "docker-daemon", "host-socket") - sweep(channel, project, record_path(project)) - prepared = prepare_launch(project, RunFlags(memory="6g", save=save), interactive=True, - input_stream=io.StringIO("a\n"), output_stream=io.StringIO()) - assert prepared.selected.checkout["authorization"]["docker-daemon"]["value"] == "host-socket" - saved = load_toml(record_path(project)) - assert saved["authorization"]["docker-daemon"]["value"] == "host-socket" - if save: - assert saved["configuration"]["values"]["memory"] == "6GiB" - assert deferred_requests(record_path(project)) == [] - - -def test_forgetting_vendor_denial_requires_confirmation_despite_home_trust(project, tmp_path): - from devcapsule.configuration.authorization import review_authorizations - from devcapsule.configuration.file_formats import render_toml - from devcapsule.configuration.storage import load_trust - from devcapsule.configuration.trust import HomeTrust - manifest = load_toml(paths(project)[0]) - lock_path = project / ".devcapsule" / "devcapsule.linux-amd64.lock" - lock = load_toml(lock_path) - lock["components"]["claude-code"] = { - "version": "1.0.0", "acquisition-authorization": "claude-code-download", - "terms-url": "https://www.anthropic.com/legal/commercial-terms", "delivery-policy": "local-materialization", - "artifacts": {"linux-amd64": {"url": "https://downloads.example.test/claude", "sha256": "e" * 64}}, - } - lock_path.write_text(render_toml(lock)) - def reviews(root): - return {item.name: item for item in review_authorizations( - manifest, lock, load_toml(record_path(root)), HomeTrust.read(load_trust()))} - from tests.test_trust import accept - assert accept(project, "claude-code") == 0 - assert config(project, "authorize", "claude-code-download", "false") == 0 - assert reviews(project)["claude-code-download"].trusted_channel is None - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-forget", "forget", "claude-code-download") - sweep(channel, project, record_path(project)) - assert reviews(project)["claude-code-download"].trusted_channel is None - assert result(channel, "000001-forget")["status"] == "deferred" - assert config(project, "console", "apply", "000001-forget") == 0 - assert reviews(project)["claude-code-download"].trusted_channel == "claude-code" - - -@pytest.mark.parametrize("node,value", [("network", "bridge"), ("docker-daemon", "none"), ("host-browser", "false")]) -def test_explicit_secure_authorizations_are_applied_without_confirmation(project, tmp_path, node, value): - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-authorize", "authorize", node, value) - assert sweep(channel, project, record_path(project)) == 1 - assert result(channel, "000001-authorize")["status"] == "recorded" - assert deferred_requests(record_path(project)) == [] - assert load_toml(record_path(project))["authorization"][node]["value"] == (False if value == "false" else value) - - -def test_full_deferred_queue_preserves_previous_requests(project): - from devcapsule.configuration.console_channel import DeferredRequest, result_document - from devcapsule.configuration.console_requests import write_deferred - first = DeferredRequest("000001-authorize", "now", ("authorize", "network", "host")) - write_deferred(record_path(project), [first]) - huge = DeferredRequest("000002-bind", "now", ("bind", *(["x" * 4096] * 63))) - with pytest.raises(ProjectConfigurationError, match="queue is full"): - write_deferred(record_path(project), [first, huge, DeferredRequest("000003-bind", "now", huge.arguments)]) - assert deferred_requests(record_path(project)) == [first] - document = result_document("refused", "x" * (256 * 1024)) - assert "Output truncated" in document["text"] - assert len(json.dumps(document).encode()) < 256 * 1024 - - -def test_launcher_publication_replaces_links_only_after_document_is_complete(tmp_path, monkeypatch): - import os - destination = tmp_path / "000001-ide.result.json" - outside = tmp_path / "outside" - outside.write_text("unchanged") - destination.symlink_to(outside) - planted = tmp_path / f".{destination.name}.{os.getpid()}.tmp" - planted.symlink_to(outside) - original = Path.replace - observed = [] - def publish(source, target): - observed.append(json.loads(source.read_text())) - assert destination.is_symlink() and outside.read_text() == "unchanged" - return original(source, target) - monkeypatch.setattr(Path, "replace", publish) - write_complete(destination, {"format": 1, "text": "done"}) - assert observed == [{"format": 1, "text": "done"}] - assert read_document(destination) == observed[0] and outside.read_text() == "unchanged" - assert planted.is_symlink() - - -def test_request_timestamp_cannot_inject_terminal_controls_or_overflow_results(): - for value in ("\x1b[2J", "x" * 100000, 4, "2026-10-24"): - with pytest.raises(ProjectConfigurationError, match="ISO time"): - parse_request({"format": 1, "arguments": ["authorize", "network", "host"], "requested": value}) - - -def test_console_forget_during_run_removes_stale_grant_but_keeps_saved_flags(project, tmp_path): - assert config(project, "ide", "python-ide") == 0 - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - assert config(project, "authorize", "network", "host") == 0 - channel = tmp_path / "channel" - channel.mkdir() - request(channel, "000001-forget", "forget", "network") - sweep(channel, project, record_path(project)) - prepared = prepare_launch(project, RunFlags(memory="6g", save=True), interactive=True, - input_stream=io.StringIO("a\n"), output_stream=io.StringIO()) - assert "network" not in prepared.selected.checkout.get("authorization", {}) - assert "network" not in load_toml(record_path(project)).get("authorization", {}) - assert load_toml(record_path(project))["configuration"]["values"]["memory"] == "6GiB" - - -def test_console_set_during_run_preserves_other_staged_values(project, tmp_path): - assert config(project, "ide", "python-ide") == 0 - assert cli.main(["home", "trust", "accept", "devcapsule-base", "--yes"]) == 0 - channel = tmp_path / "channel" - channel.mkdir() - # A command retained at shutdown is confirmed during the next launch. - path = request(channel, "000001-set", "set", "cpus", "2") - handle_request(project, record_path(project), path, stopping=True) - prepared = prepare_launch(project, RunFlags(memory="6g", save=True), interactive=True, - input_stream=io.StringIO("a\n"), output_stream=io.StringIO()) - assert prepared.selected.checkout["configuration"]["values"] == {"memory": "6GiB", "cpus": 2} - assert load_toml(record_path(project))["configuration"]["values"] == {"memory": "6GiB", "cpus": 2} - - -@pytest.mark.parametrize("arguments", [ - ["add", "claude-code-agent"], ["omit", "browser-automation"], - ["restore", "browser-automation"], ["use", "frontend-ide", "codium"], -]) -def test_capability_requests_apply_without_host_confirmation(arguments): - assert classify(arguments) == (Disposition.APPLY, "") - - -@pytest.mark.parametrize("arguments", [["agent", "add", "codex"], ["tool", "omit", "browser-automation"]]) -def test_deleted_channel_verbs_are_refused(arguments): - assert classify(arguments)[0] is Disposition.REFUSE diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_console_channel.py b/devcapsule-src/tests/unit/devcapsule/commands/test_console_channel.py new file mode 100644 index 00000000..22112459 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_console_channel.py @@ -0,0 +1,489 @@ +"""Unit tests of ``devcapsule/commands/_console_channel.py``: the launcher's side of the console's channel. + +The launcher answers a request file by running ``project config`` as a +process. Here that runner is a value of the test, ``Runner``, which notes +what it was asked to run and answers as the test says, so the tests of what +is applied, kept or refused start no program. The channel directory, the +checkout's record and the home are the test's own, under its directory. + +Two operations are about a process itself, ``run_command`` and +``child_environment``; their tests start one small Python program whose +whole text is in the test. +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +import sys +import threading +import time +from typing import Any, Sequence + +import pytest + +from devcapsule.commands._console_channel import ( + ChannelView, ChannelWatcher, apply_deferred, child_environment, discard_deferred, handle_request, read_channel, + render_running_listing, run_command, running_listing_document, sweep, +) +from devcapsule.configuration.console_channel import DeferredRequest, listing_document, read_document, write_complete +from devcapsule.configuration.console_requests import deferred_requests, write_deferred +from devcapsule.configuration.file_formats import ProjectConfigurationError, render_toml +from devcapsule.configuration.listing import Listing, ListingRow +from devcapsule.configuration.storage import config_root + +ASKED_AT = "2026-10-24T10:00:00+00:00" +ROOT = Path("/projects/order") +"""The project's directory, as the runner is told it; no test opens it.""" + + +class Runner: + """Stands where ``run_config`` is: notes each command it is asked to run, and answers ``status`` and ``output``.""" + + def __init__(self, status: int = 0, output: str = "the command's own output") -> None: + self.status, self.output = status, output + self.calls: list[tuple[Path, tuple[str, ...], bool]] = [] + self.called = threading.Event() + + def __call__(self, root: Path, arguments: Sequence[str], *, host_confirmed: bool = False) -> tuple[int, str]: + self.calls.append((root, tuple(arguments), host_confirmed)) + self.called.set() + return self.status, self.output + + +@pytest.fixture +def channel(tmp_path: Path) -> Path: + """The directory the launcher mounts into the capsule for one run, empty.""" + directory = tmp_path / "channel" + directory.mkdir() + return directory + + +@pytest.fixture +def record(tmp_path: Path) -> Path: + """The record, in the test's home, of a checkout of ``owner/order`` that lies under the test's directory.""" + path = config_root() / "projects" / "owner" / "order" / "devcapsule.checkout.toml" + path.parent.mkdir(parents=True) + path.write_text(render_toml({"checkout": {"path": str(tmp_path / "order")}}), encoding="utf-8") + return path + + +def ask(channel: Path, identifier: str, *arguments: str) -> Path: + """Put one request in the channel as the console writes it, asked at ``ASKED_AT``.""" + return write_complete(channel / f"{identifier}.request.json", + {"format": 1, "requested": ASKED_AT, "arguments": list(arguments)}) + + +def result(channel: Path, identifier: str) -> dict[str, Any]: + """The launcher's answer to the request ``identifier``.""" + return read_document(channel / f"{identifier}.result.json") + + +def test_a_request_applied_at_once_runs_its_command_and_reports_the_commands_output(channel: Path, record: Path) -> None: + """A request for the checkout's own choice is run as its tokens, not as confirmed on the host. When the + command succeeds the result is ``recorded``, with the command's output and the note that the running + capsule is unchanged.""" + run = Runner(0, "Your IDE for this checkout: python-ide (pycharm).") + + answer = handle_request(ROOT, record, ask(channel, "000001-ide", "ide", "python-ide"), run=run) + + assert run.calls == [(ROOT, ("ide", "python-ide"), False)] + assert answer == result(channel, "000001-ide") + assert answer["status"] == "recorded" + assert answer["text"] == ("Recorded for the next launch. This running capsule is unchanged.\n" + "Your IDE for this checkout: python-ide (pycharm).") + + +def test_a_command_that_fails_makes_its_request_refused_in_the_commands_words(channel: Path, record: Path) -> None: + """When the command exits with another status than 0, the result is ``refused`` and its text is what the + command printed; a command that printed nothing is named with its status.""" + spoken = handle_request(ROOT, record, ask(channel, "000001-ide", "ide", "no-such-ide"), run=Runner(2, "Unknown IDE 'no-such-ide'")) + silent = handle_request(ROOT, record, ask(channel, "000002-ide", "ide", "no-such-ide"), run=Runner(2, "")) + + assert (spoken["status"], spoken["text"]) == ("refused", "Unknown IDE 'no-such-ide'") + assert (silent["status"], silent["text"]) == ("refused", "config ide no-such-ide exited with status 2") + + +def test_a_sweep_answers_each_request_once_in_the_order_of_their_names(channel: Path, record: Path) -> None: + """A sweep answers every request that has no result, lowest name first, and says how many. A second sweep + finds them answered: it answers none and runs nothing.""" + ask(channel, "000002-deny", "deny", "network") + ask(channel, "000001-ide", "ide", "python-ide") + run = Runner() + + assert sweep(channel, ROOT, record, run=run) == 2 + assert sweep(channel, ROOT, record, run=run) == 0 + + assert [arguments for _, arguments, _ in run.calls] == [("ide", "python-ide"), ("deny", "network")] + + +@pytest.mark.parametrize("tokens", [ + ("authorize", "network", "host"), ("forget", "docker-daemon"), + ("env", "set", "HOST_SECRET", "--from-host"), ("env", "set", "HOST_SECRET", "--from-h"), +]) +def test_a_request_that_can_widen_is_kept_for_the_host_and_no_command_is_run(channel: Path, record: Path, tokens: tuple[str, ...]) -> None: + """A widening is not run. It is kept for the checkout with its tokens and the time the console asked, and + the result is ``deferred``, carrying that time and naming the command that applies it on the host.""" + run = Runner() + ask(channel, "000001-change", *tokens) + + assert sweep(channel, ROOT, record, run=run) == 1 + + assert run.calls == [] + assert deferred_requests(record) == [DeferredRequest("000001-change", ASKED_AT, tokens)] + answer = result(channel, "000001-change") + assert (answer["status"], answer["at"]) == ("deferred", ASKED_AT) + assert "This command can widen access. Nothing has been applied." in answer["text"] + assert "devcapsule project config console apply 000001-change" in answer["text"] + + +def test_a_request_the_launcher_does_not_take_is_refused_with_the_reason_and_nothing_is_kept(channel: Path, record: Path) -> None: + """A read-only command asked through the channel is refused with the classification's reason; no command is + run and nothing is kept for the host.""" + run = Runner() + + answer = handle_request(ROOT, record, ask(channel, "000001-show", "show"), run=run) + + assert (answer["status"], answer["text"]) == ("refused", "config show is read-only; the console shows what it reports") + assert run.calls == [] and deferred_requests(record) == [] + + +def test_a_request_whose_document_is_not_the_contracts_is_refused(channel: Path, record: Path) -> None: + """A request file with a well-formed name and a document of another format is answered ``refused``, naming + the file.""" + path = write_complete(channel / "000001-ide.request.json", {"format": 2, "arguments": ["ide", "python-ide"]}) + + answer = handle_request(ROOT, record, path, run=Runner()) + + assert answer["status"] == "refused" and "000001-ide.request.json: not a format-1 request document" in answer["text"] + + +@pytest.mark.parametrize("kind", ["link", "pipe", "huge", "partial"]) +def test_a_request_file_that_cannot_be_read_is_refused_and_does_not_keep_the_next_one_waiting( + channel: Path, record: Path, kind: str, +) -> None: + """Anything in the capsule can write to the channel. A request that is a link, a named pipe, larger than a + document may be, or cut short is answered ``refused``, and the request after it is still run. A file + whose name is not a request's is left unanswered.""" + bad = channel / "000001-ide.request.json" + if kind == "link": + bad.symlink_to(record) + elif kind == "pipe": + os.mkfifo(bad) + elif kind == "huge": + bad.write_bytes(b" " * (256 * 1024 + 1)) + else: + bad.write_text('{"format":') + (channel / "outside.request.json").write_text("{}") + ask(channel, "000002-deny", "deny", "network") + run = Runner() + + assert sweep(channel, ROOT, record, run=run) == 2 + + assert result(channel, "000001-ide")["status"] == "refused" + assert result(channel, "000002-deny")["status"] == "recorded" + assert [arguments for _, arguments, _ in run.calls] == [("deny", "network")] + assert not (channel / "outside.result.json").exists() + + +def test_a_request_named_like_one_already_kept_is_kept_beside_it_under_a_new_id(tmp_path: Path, record: Path) -> None: + """A console numbers its requests from 1 in every run. A widening whose name was already kept in an earlier + run does not replace that one: both are kept, the later under an id of the launcher's, which its result names.""" + for name, node, value in (("first-run", "network", "host"), ("second-run", "docker-daemon", "host-socket")): + directory = tmp_path / name + directory.mkdir() + ask(directory, "000001-authorize", "authorize", node, value) + sweep(directory, ROOT, record, run=Runner()) + + first, second = deferred_requests(record) + + assert (first.id, first.arguments) == ("000001-authorize", ("authorize", "network", "host")) + assert second.id != first.id and second.arguments == ("authorize", "docker-daemon", "host-socket") + assert f"Saved request {second.id}:" in result(tmp_path / "second-run", "000001-authorize")["text"] + + +def test_while_the_launcher_stops_a_request_that_would_be_applied_is_kept_instead(channel: Path, record: Path) -> None: + """Once the launcher is stopping it runs no more commands: a request it would have applied is kept for the + host, and its result says that the launcher is stopping.""" + run = Runner() + + answer = handle_request(ROOT, record, ask(channel, "000001-set", "set", "cpus", "2"), stopping=True, run=run) + + assert run.calls == [] + assert answer["status"] == "deferred" and "The launcher is stopping." in answer["text"] + assert deferred_requests(record) == [DeferredRequest("000001-set", ASKED_AT, ("set", "cpus", "2"))] + + +def test_the_watcher_answers_a_request_while_the_capsule_runs(channel: Path, record: Path) -> None: + """A started watcher answers a request written after it started, without being asked to.""" + run = Runner() + watcher = ChannelWatcher(channel, ROOT, record, interval=0.01, run=run) + watcher.start() + try: + ask(channel, "000001-deny", "deny", "network") + assert run.called.wait(timeout=30), "the watcher did not run the request's command" + finally: + watcher.stop() + + assert result(channel, "000001-deny")["status"] == "recorded" + + +def test_stopping_the_watcher_answers_what_is_waiting_without_running_a_command(channel: Path, record: Path) -> None: + """``stop`` sweeps once more and returns when the watcher's thread has ended. The requests still waiting + are answered then, kept for the host and not run, the one that would have been applied included.""" + run = Runner() + watcher = ChannelWatcher(channel, ROOT, record, interval=3600, run=run) + watcher.start() + ask(channel, "000001-ide", "ide", "frontend-ide") + ask(channel, "000002-authorize", "authorize", "docker-daemon", "host-socket") + + watcher.stop() + + assert not watcher._thread.is_alive() + assert run.calls == [] + assert [item.arguments[0] for item in deferred_requests(record)] == ["ide", "authorize"] + assert "The launcher is stopping." in result(channel, "000001-ide")["text"] + + +def test_applying_a_kept_request_runs_its_exact_tokens_as_confirmed_on_the_host_and_forgets_it(record: Path) -> None: + """``apply_deferred`` runs the kept request's tokens unchanged, spaces and shell characters included, as a + command the human confirmed on the host, returns the command's status and output, and forgets the request.""" + tokens = ("docker-args", "set", "--env", "TEXT=a b;$(false)") + write_deferred(record, [DeferredRequest("000001-docker-args", ASKED_AT, tokens)]) + run = Runner(0, "done") + + assert apply_deferred(ROOT, record, "000001-docker-args", run=run) == (0, "done") + + assert run.calls == [(ROOT, tokens, True)] + assert deferred_requests(record) == [] + + +def test_a_kept_request_whose_command_fails_stays_kept(record: Path) -> None: + """When the command of a kept request fails, its status and output are returned and the request still + awaits the host.""" + kept = DeferredRequest("000001-authorize", ASKED_AT, ("authorize", "quantum", "x")) + write_deferred(record, [kept]) + + assert apply_deferred(ROOT, record, "000001-authorize", run=Runner(2, "Unknown authorization 'quantum'")) == (2, "Unknown authorization 'quantum'") + + assert deferred_requests(record) == [kept] + + +def test_discarding_a_kept_request_forgets_it_and_runs_nothing(record: Path) -> None: + """``discard_deferred`` removes the one request named and leaves the others.""" + kept = [DeferredRequest("000001-authorize", ASKED_AT, ("authorize", "network", "host")), + DeferredRequest("000002-bind", ASKED_AT, ("bind", "home", "~/capsule-home"))] + write_deferred(record, kept) + + discard_deferred(record, "000002-bind") + + assert deferred_requests(record) == kept[:1] + + +def test_applying_or_discarding_a_request_that_is_not_kept_is_refused(record: Path) -> None: + """An id that no kept request of the checkout has is refused by both operations, and no command is run.""" + run = Runner() + + with pytest.raises(ProjectConfigurationError, match="No console request '000009-x' awaits confirmation"): + apply_deferred(ROOT, record, "000009-x", run=run) + with pytest.raises(ProjectConfigurationError, match="No console request '000009-x' awaits confirmation"): + discard_deferred(record, "000009-x") + + assert run.calls == [] + + +LAUNCHERS_SHELL = { + "HOME": "/home/developer", "PATH": "/usr/bin", "LANG": "C.UTF-8", "LC_TIME": "ro_RO.UTF-8", "TMPDIR": "/tmp/own", + "DEVCAPSULE_CONFIG_HOME": "/homes/developer", "XDG_CONFIG_HOME": "/home/developer/.config", + "HOST_SECRET": "never expose", "PYTHONPATH": "/somewhere/injected", "DOCKER_HOST": "ssh://host-context.example", +} +"""An environment a launcher could run in: where its records are, the locale, and three things a child must not get.""" + + +def test_a_command_run_for_the_console_inherits_the_record_locations_and_the_locale_only() -> None: + """The child gets where the home and the records are, the search path, the temporary directory and the + locale. It gets no other variable: not a secret, not a Python path, not the Docker context.""" + assert child_environment(LAUNCHERS_SHELL) == { + "HOME": "/home/developer", "PATH": "/usr/bin", "LANG": "C.UTF-8", "LC_TIME": "ro_RO.UTF-8", "TMPDIR": "/tmp/own", + "DEVCAPSULE_CONFIG_HOME": "/homes/developer", "XDG_CONFIG_HOME": "/home/developer/.config", + } + + +def test_a_command_the_human_confirmed_on_the_host_inherits_the_whole_environment() -> None: + """With ``host_confirmed`` the child is an ordinary command of the human's shell: every variable passes, the + Docker context among them, in a copy of its own.""" + inherited = child_environment(LAUNCHERS_SHELL, host_confirmed=True) + + assert inherited == LAUNCHERS_SHELL and inherited is not LAUNCHERS_SHELL + + +PROBE = "import json, os, sys; print(json.dumps([dict(os.environ), os.getsid(0), os.getpid(), sys.stdin.read()]))" +"""A program that reports what it was given: its environment, its session, its process id and its input.""" + + +def test_the_child_runs_in_a_session_of_its_own_with_the_environment_given_and_no_input() -> None: + """``run_command`` starts the command in a new session, of which the child is the leader, with exactly + the environment given and an input that is already at its end.""" + status, output = run_command([sys.executable, "-c", PROBE], {"ONLY": "this"}, 30) + + environment, session, process, read = json.loads(output) + assert status == 0 + assert environment.get("ONLY") == "this" and "PATH" not in environment and "HOME" not in environment + assert session == process and session != os.getsid(0) + assert read == "" + + +def test_the_childs_status_and_both_its_outputs_come_back() -> None: + """The result is the child's exit status and what it wrote to standard output and standard error, in the + order written, without the surrounding blank space.""" + program = "import sys; print('to output', flush=True); print('to error', file=sys.stderr, flush=True); sys.exit(3)" + + assert run_command([sys.executable, "-c", program], {}, 30) == (3, "to output\nto error") + + +def test_a_command_that_cannot_be_started_is_status_one_with_the_reason(tmp_path: Path) -> None: + """A command whose program does not exist is reported, not raised: status 1 and a line that names the cause.""" + status, output = run_command([str(tmp_path / "no-such-program")], {}, 30) + + assert status == 1 and output.startswith("cannot run the configuration command: ") + + +def test_a_command_that_outlives_its_time_is_killed_with_the_processes_it_started(tmp_path: Path) -> None: + """A child still running at the timeout is killed and reported as status 1 with the timeout. A process it + started is killed with it: that process had begun, and never reaches the line after its own wait.""" + started, escaped = tmp_path / "started", tmp_path / "escaped" + grandchild = (f"from pathlib import Path; import time; Path({str(started)!r}).touch(); " + f"time.sleep(0.8); Path({str(escaped)!r}).touch()") + child = f"import subprocess, sys, time; subprocess.Popen([sys.executable, '-c', {grandchild!r}]); time.sleep(30)" + + assert run_command([sys.executable, "-c", child], {}, 0.3) == (1, "the command did not finish within 0.3 seconds") + + assert started.exists() + time.sleep(0.9) # Longer than the grandchild's own wait: alive, it would have written by now. + assert not escaped.exists() + + +LISTING = { + **Listing((ListingRow("ide", "python-ide", "pycharm 2026.2", "checkout"),)).document(), + "project": {"creator": "owner", "slug": "order"}, + "checkout": {"name": "default", "launcher-path": "/host/order", "input": "/homes/developer/order.toml"}, +} +"""A launch-time listing as the launcher writes it: one row, and whose checkout it is.""" + +THIS_CAPSULE: dict[str, Any] = { + "launcher_root": "/host/order", "checkout_name": "default", "project": {"creator": "owner", "slug": "order", "name": "Order"}, + "launcher_command": "devcapsule project --path /host/order config show", +} +"""What a capsule knows of itself: the checkout the launcher started it for, and the host command that shows it.""" + + +def test_a_channel_without_the_launchers_listing_is_an_error_that_sends_to_the_host(channel: Path) -> None: + """Reading a channel directory in which the launcher wrote no listing is refused, with the advice to inspect + the configuration on the host.""" + with pytest.raises(ProjectConfigurationError, match="no launch listing; inspect configuration on the host"): + read_channel(channel) + + +def test_the_view_of_a_channel_is_the_listing_with_its_time_and_each_request_with_its_answer(channel: Path) -> None: + """The view carries the launch-time listing and when it was written, then every request in name order with + its statement and the launcher's result, or None for a request not yet answered.""" + write_complete(channel / "listing.json", listing_document(LISTING, "2026-10-24T12:00:00+00:00")) + ask(channel, "000001-ide", "ide", "frontend-ide") + write_complete(channel / "000001-ide.result.json", {"format": 1, "status": "recorded", "text": "done", "at": "t"}) + ask(channel, "000002-authorize", "authorize", "network", "host") + + view = read_channel(channel) + + assert (view.at, view.listing) == ("2026-10-24T12:00:00+00:00", LISTING) + answered, waiting = view.requests + assert (answered["id"], answered["statement"], answered["requested"]) == ("000001-ide", "config ide frontend-ide", ASKED_AT) + assert answered["result"] == {"format": 1, "status": "recorded", "text": "done", "at": "t"} + assert (waiting["id"], waiting["arguments"], waiting["result"]) == ("000002-authorize", ["authorize", "network", "host"], None) + + +@pytest.mark.parametrize("planted", ["empty", "without-text", "pipe"]) +def test_a_result_that_cannot_be_read_is_shown_as_unknown_and_does_not_fail_the_view(channel: Path, planted: str) -> None: + """A result file that is not the contract's document, or not a regular file, is shown with the status + ``unknown`` and a text that says the result cannot be read and to inspect on the host before retrying.""" + write_complete(channel / "listing.json", listing_document(LISTING)) + ask(channel, "000001-ide", "ide", "python-ide") + path = channel / "000001-ide.result.json" + if planted == "pipe": + os.mkfifo(path) + else: + write_complete(path, {} if planted == "empty" else {"format": 1, "status": "recorded"}) + + (request,) = read_channel(channel).requests + + assert request["result"]["status"] == "unknown" + assert request["result"]["text"].startswith("Cannot read the launcher result: ") + assert "Inspect configuration on the host before retrying." in request["result"]["text"] + + +def test_a_request_file_that_cannot_be_read_is_shown_as_refused_under_its_file_name(channel: Path) -> None: + """A request whose document is not the contract's is listed by its file name, with no statement and a + refusal that says why.""" + write_complete(channel / "listing.json", listing_document(LISTING)) + write_complete(channel / "000001-ide.request.json", {"format": 2}) + + (request,) = read_channel(channel).requests + + assert (request["id"], request["statement"], request["result"]["status"]) == ("000001-ide.request.json", "", "refused") + + +def a_view(*requests: dict[str, Any]) -> ChannelView: + """The view of a channel whose listing is ``LISTING``, written at noon, with the requests given.""" + return ChannelView("2026-10-24T12:00:00+00:00", LISTING, tuple(requests)) + + +ANSWERED = {"id": "000001-ide", "arguments": ["ide", "frontend-ide"], "statement": "config ide frontend-ide", + "requested": ASKED_AT, "result": {"format": 1, "status": "recorded", "text": "done", "at": "t"}} +WAITING = {"id": "000002-authorize", "arguments": ["authorize", "network", "host"], + "statement": "config authorize network host", "requested": ASKED_AT, "result": None} + + +def test_inside_a_capsule_the_json_document_is_the_listing_at_launch_with_the_requests_since() -> None: + """The document keeps the launch-time listing's rows and adds that it is a running capsule's, the time of + the listing, the console's requests, and the host command that shows the configuration.""" + document = running_listing_document(a_view(ANSWERED, WAITING), **THIS_CAPSULE) + + assert document["rows"] == LISTING["rows"] + assert document["context"] == "running capsule: the launcher's listing at launch" + assert document["at"] == "2026-10-24T12:00:00+00:00" + assert document["console-requests"] == [ANSWERED, WAITING] + assert document["launcher-command"] == "devcapsule project --path /host/order config show" + + +def test_inside_a_capsule_the_text_shows_the_listing_then_each_request_with_its_outcome() -> None: + """The text names the checkout and the time of the listing, renders the listing, then lists each request + asked since launch with the launcher's answer, or that it waits for the launcher, and ends with how to + change the next launch.""" + text = render_running_listing(a_view(ANSWERED, WAITING), **THIS_CAPSULE) + + lines = text.splitlines() + assert lines[:2] == ["Checkout: /host/order (default)", "At launch, 2026-10-24T12:00:00+00:00:"] + assert any("python-ide" in line and "pycharm 2026.2" in line for line in lines) + assert "Pending, next launch (asked on the console since launch):" in lines + assert text.count(" 000001-ide: config ide frontend-ide\n recorded: done") == 1 + assert text.count(" 000002-authorize: config authorize network host\n waiting for the launcher") == 1 + assert lines[-1] == ("To change the next launch: the console's configuration page, or on the host: " + "devcapsule project --path /host/order config show") + + +def test_inside_a_capsule_with_nothing_asked_the_text_says_so() -> None: + """With no request in the channel the text says that nothing was asked on the console since launch.""" + assert "Nothing asked on the console since launch." in render_running_listing(a_view(), **THIS_CAPSULE).splitlines() + + +@pytest.mark.parametrize("difference", [{"launcher_root": "/host/another-copy"}, {"checkout_name": "second"}, + {"project": {"creator": "owner", "slug": "another"}}]) +def test_a_listing_written_for_another_checkout_is_refused_in_both_forms(difference: dict[str, Any]) -> None: + """A listing whose checkout directory, checkout name or project is not this capsule's cannot stand in for + this run: the document and the text are both refused, sending the reader to the host.""" + capsule = {**THIS_CAPSULE, **difference} + + with pytest.raises(ProjectConfigurationError, match="belongs to another checkout; inspect configuration on the host"): + running_listing_document(a_view(), **capsule) + with pytest.raises(ProjectConfigurationError, match="belongs to another checkout; inspect configuration on the host"): + render_running_listing(a_view(), **capsule) diff --git a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py index 61a8b9d1..a509a7e9 100644 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -16,7 +16,7 @@ import pytest -from devcapsule.commands._launch_review import RunFlags, flags_after_upgrade, review_launch, stage_trust +from devcapsule.commands._launch_review import RunFlags, flags_after_upgrade, launch_listing, review_launch, stage_trust from devcapsule.compat import DecisionPending from devcapsule.configuration.authorization import authorization_declarations, normalize_authorization_value from devcapsule.configuration.bindings import HostDirectory @@ -24,6 +24,8 @@ IDE_REQUIREMENT, CapabilityPolicy, LocalCapabilities, RequirementDeparture, resolution_recommendations, ) from devcapsule.configuration.capability_selection import generate_lock +from devcapsule.configuration.console_channel import DeferredRequest +from devcapsule.configuration.console_requests import request_rows from devcapsule.configuration.derivation import CheckoutState, Host, Selection from devcapsule.configuration.file_formats import ProjectConfigurationError, canonical_digest, render_checkout, render_toml from devcapsule.configuration.listing import Decision @@ -726,3 +728,79 @@ def test_a_channel_that_an_upgrade_moved_is_pending_in_the_second_review_and_the review_launch(state, flags_after_upgrade(flags, first.host_overrides), ask=None, announce=never_announced) assert state.home["trust"]["channels"]["claude-code"]["origins"] == accepted_origins + + +ASKED_ON_THE_CONSOLE = DeferredRequest("000001-authorize", "2026-10-24T10:00:00+00:00", ("authorize", "network", "host")) +"""A widening the console asked for in an earlier run, kept for the host's confirmation.""" + + +def with_a_console_request(state: CheckoutState) -> CheckoutState: + """``state`` with ``ASKED_ON_THE_CONSOLE`` awaiting confirmation, as the reading phase finds it in the store.""" + state.deferred = tuple(request_rows([ASKED_ON_THE_CONSOLE], state.root)) + return state + + +def test_a_console_request_that_awaits_confirmation_does_not_stop_a_launch_without_a_terminal() -> None: + """A request kept from the console is a soft decision: with no terminal the launch is planned without it, + the network stays as it was, and a note says what awaits, since when, and the command that applies it.""" + review = review_launch(with_a_console_request(checkout_of(REQUIRING_PYCHARM)), RunFlags(), ask=None, announce=never_announced) + + assert "network" not in review.selected.checkout.get("authorization", {}) + assert review.notes == [ + "The console's request 000001-authorize of 2026-10-24T10:00:00+00:00 awaits your confirmation: " + "config authorize network host. Apply or discard: " + f"devcapsule project --path {ROOT} config console apply 000001-authorize" + ] + + +def test_a_console_request_is_put_to_the_developer_once_and_kept_when_they_leave_it() -> None: + """With a terminal the request is asked, once. A developer who neither applies nor discards it gets the + launch planned, with the same note that it still awaits.""" + asked: list[Decision] = [] + + def leaving_it(state: CheckoutState, record: CheckoutRecord, checkout: dict[str, Any], decision: Decision, + host_overrides: dict[str, Any], environment: dict[str, str | None], accepted: list[str], flags: RunFlags) -> None: + asked.append(decision) + + review = review_launch(with_a_console_request(checkout_of(REQUIRING_PYCHARM)), RunFlags(), ask=leaving_it, announce=never_announced) + + assert [(decision.kind, decision.name, decision.description) for decision in asked] == [ + ("console", "000001-authorize", "config authorize network host")] + assert len(review.notes) == 1 and "000001-authorize" in review.notes[0] and "awaits your confirmation" in review.notes[0] + + +RECOMMENDING_THE_DOCKER_DAEMON: dict[str, Any] = { + "host": {"docker": {"mode": {"recommended": {"value": "host-socket", "justification": "Project build containers"}}}}} +"""Manifest tables by which a project recommends the host's Docker daemon, with its reason.""" + + +def test_the_launchs_listing_shows_the_run_once_choices_and_the_requests_that_await() -> None: + """The listing a launch gives its capsule is of the launch as it runs: the IDE and the agent chosen for + this run only are rows of it, beside the console's request that still awaits. It says whose checkout it is. + The record staged for writing keeps the saved IDE.""" + state = with_a_console_request(checkout_of(("node",), manifest_tables=RECOMMENDING_THE_DOCKER_DAEMON)) + review = review_launch(state, RunFlags(ide="frontend-ide", capabilities=("codex",)), ask=None, announce=never_announced) + + listing = launch_listing(review.state, review.selected, "default") + + rows = listing["rows"] + assert any(row["kind"] == "ide" and row["name"] == "frontend-ide" for row in rows) + assert any(row["kind"] == "capability" and "codex" in row["name"] for row in rows) + assert any(row["kind"] == "console" and row["name"] == "000001-authorize" for row in rows) + assert listing["context"] == "at launch" + assert listing["project"] == {"creator": "mailto:owner@example.test", "slug": "order"} + assert listing["checkout"] == {"name": "default", "launcher-path": str(ROOT), "input": str(review.selected.checkout_path)} + assert LocalCapabilities.read(review.record.document).selected == ("python-ide",) + + +def test_the_launchs_listing_says_what_a_host_access_exposes_and_why_the_project_recommends_it() -> None: + """The row of a host access the project recommends carries what granting it exposes and the project's + reason; the row of one the project does not recommend carries the exposure and no reason.""" + state = checkout_of(("node",), manifest_tables=RECOMMENDING_THE_DOCKER_DAEMON) + review = review_launch(state, RunFlags(), ask=None, announce=never_announced) + + rows = {row["name"]: row for row in launch_listing(review.state, review.selected, "default")["rows"] if row["kind"] == "access"} + + assert "broad control of the host" in rows["docker-daemon"]["exposure"] + assert rows["docker-daemon"]["reason"] == "Project build containers" + assert rows["network"]["exposure"] and rows["network"]["reason"] == "" diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_console_channel.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_console_channel.py new file mode 100644 index 00000000..d0fb1bee --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_console_channel.py @@ -0,0 +1,237 @@ +"""Unit tests of ``devcapsule/configuration/console_channel.py``: the contract of the console's channel. + +The module is the contract between a capsule's console and the launcher: +which request is applied at once, kept for the host's confirmation or +refused, and the documents the two sides exchange. Each test builds its +tokens and documents as values. The tests of reading and publishing write +their own files under the test's directory. +""" + +from __future__ import annotations + +import json +import os +from pathlib import Path +from typing import Any + +import pytest + +from devcapsule.configuration.console_channel import ( + DeferredRequest, Disposition, classify, listing_document, parse_deferred, parse_listing, parse_request, + read_document, render_deferred, request_id, result_document, statement, write_complete, +) +from devcapsule.configuration.file_formats import ProjectConfigurationError + + +@pytest.mark.parametrize("arguments", [ + ["ide", "python-ide"], ["add", "claude-code-agent"], ["omit", "browser-automation"], + ["restore", "browser-automation"], ["use", "frontend-ide", "codium"], ["set", "cpus", "2"], + ["deny", "network"], ["unbind", "home"], ["env", "set", "X", "1"], ["env", "unset", "X"], + ["trust", "withdraw", "claude-code"], ["docker-args", "clear"], +]) +def test_a_request_that_keeps_or_narrows_the_checkouts_choices_is_applied_at_once(arguments: list[str]) -> None: + """A verb that records the checkout's own choice, or narrows what the next launch reaches, is applied + without the host's confirmation, and no reason is given.""" + assert classify(arguments) == (Disposition.APPLY, "") + + +@pytest.mark.parametrize("arguments", [ + ["authorize", "network", "bridge"], ["authorize", "network", "none"], ["authorize", "docker-daemon", "none"], + ["authorize", "development-sudo", "false"], ["authorize", "host-browser", "false"], ["authorize", "host-x11", "none"], +]) +def test_an_authorization_of_the_secure_value_is_applied_at_once(arguments: list[str]) -> None: + """``authorize`` with the value that grants nothing, a bridged or absent network, no Docker daemon, no + sudo, no host browser or display, narrows the launch and is applied like a denial.""" + assert classify(arguments) == (Disposition.APPLY, "") + + +@pytest.mark.parametrize("arguments", [ + ["authorize", "network", "host"], ["authorize", "docker-daemon", "host-socket"], ["trust", "accept", "claude-code"], + ["bind", "home", "~/capsule-home"], ["docker-args", "set", "--privileged"], ["forget", "docker-daemon"], + ["forget", "claude-code-download"], + ["env", "set", "HOST_SECRET", "--from-host"], ["env", "set", "HOST_SECRET", "--from-h"], ["env", "set", "X"], +]) +def test_a_request_that_can_widen_what_the_launch_reaches_is_deferred(arguments: list[str]) -> None: + """A verb that can widen the next launch is kept for the host's confirmation: an authorization, a trusted + channel, a binding, Docker arguments, forgetting an answer, which can bring back a grant of the home, and an + environment variable taken from the host, however its option is abbreviated.""" + assert classify(arguments) == (Disposition.DEFER, "") + + +@pytest.mark.parametrize(("arguments", "reason"), [ + ([], "an empty request names no command"), + (["show"], "config show is read-only"), + (["check"], "config check is read-only"), + (["env", "list"], "config env is read-only"), + (["trust", "list"], "config trust is read-only"), + (["default", "memory", "8G"], "run it on the host"), + (["require", "java"], "edits the project's shared files"), + (["recommend", "ide", "python-ide"], "edits the project's shared files"), + (["run"], "not a request the launcher takes from the console"), + (["agent", "add", "codex"], "not a request the launcher takes from the console"), + (["tool", "omit", "browser-automation"], "not a request the launcher takes from the console"), +]) +def test_every_other_request_is_refused_with_its_reason(arguments: list[str], reason: str) -> None: + """A read-only command, a home default, an edit of the project's shared files, an unknown or retired verb + and an empty request are refused, each with a reason that says why.""" + disposition, given = classify(arguments) + + assert disposition is Disposition.REFUSE + assert reason in given + + +def test_a_request_is_stated_as_the_command_it_stands_for_with_its_tokens_quoted() -> None: + """A request's statement is ``config`` followed by its tokens, quoted as a shell would need them.""" + assert statement(["docker-args", "set", "--env", "TEXT=a b"]) == "config docker-args set --env 'TEXT=a b'" + + +@pytest.mark.parametrize("name", ["000001-ide.request.json", "000042-docker-args-0123456789abcdef0123456789abcdef.request.json"]) +def test_a_request_files_id_is_its_name_without_the_suffix(name: str) -> None: + """A request file named by the contract, a six-digit number, a verb and optionally a UUID, has that name + without the suffix as its id.""" + assert request_id(Path("/channel") / name) == name.removesuffix(".request.json") + + +@pytest.mark.parametrize("name", ["x.json", "1-ide.request.json", "000001-Ide.request.json", "000001-ide.result.json"]) +def test_a_file_not_named_by_the_contract_has_no_request_id(name: str) -> None: + """A file with another suffix, a short number or an upper-case verb is refused as a request.""" + with pytest.raises(ProjectConfigurationError): + request_id(Path("/channel") / name) + + +def test_a_request_documents_tokens_are_returned_as_given() -> None: + """A format-1 document with a list of tokens, and optionally the time it was asked, gives those tokens.""" + document = {"format": 1, "requested": "2026-10-24T10:00:00+00:00", "arguments": ["ide", "python-ide"]} + + assert parse_request(document) == ["ide", "python-ide"] + assert parse_request({"format": 1, "arguments": ["ide", "python-ide"]}) == ["ide", "python-ide"] + + +@pytest.mark.parametrize("document", [ + [], {"format": 2, "arguments": ["ide"]}, {"format": 1, "arguments": []}, {"format": 1, "arguments": "ide"}, + {"format": 1, "arguments": ["a\nb"]}, {"format": 1, "arguments": ["ide", ""]}, {"format": 1, "arguments": ["ide", 3]}, + {"format": 1, "arguments": ["ide", "--path", "/x"]}, {"format": 1, "arguments": ["x" * 5000]}, + {"format": 1, "arguments": ["ide", "\ud800"]}, {"format": 1, "arguments": ["ide"] * 65}, +], ids=["not-a-table", "another-format", "no-token", "not-a-list", "control-character", "empty-token", "not-text", + "names-the-project", "token-too-long", "not-unicode", "too-many-tokens"]) +def test_a_malformed_request_document_is_refused(document: Any) -> None: + """A document of another format, without tokens, or with a token that is empty, not text, too long, not + valid Unicode, holding a control character, or ``--path``, which is the launcher's to give, is refused.""" + with pytest.raises(ProjectConfigurationError): + parse_request(document) + + +@pytest.mark.parametrize("requested", ["\x1b[2J", "x" * 100000, 4, "2026-10-24", "2026-10-24T10:00:00"]) +def test_a_requests_time_must_be_an_iso_time_with_its_zone(requested: Any) -> None: + """The time a request says it was asked is shown on a terminal and kept in results, so it must be a short + ISO time with a time zone: terminal controls, an overlong string, a number, a date and a time without a zone + are refused.""" + with pytest.raises(ProjectConfigurationError, match="ISO time"): + parse_request({"format": 1, "arguments": ["authorize", "network", "host"], "requested": requested}) + + +def test_a_result_document_carries_the_status_the_text_and_the_time() -> None: + """A result is a format-1 document with its status, its text and the time given.""" + assert result_document("recorded", "done", "2026-10-24T12:00:00+00:00") == { + "format": 1, "status": "recorded", "text": "done", "at": "2026-10-24T12:00:00+00:00"} + + +def test_a_results_text_is_cut_so_that_the_document_stays_readable() -> None: + """A text longer than a result may hold is cut and says so, and the document stays under the size a reader + of the channel accepts.""" + document = result_document("refused", "x" * (256 * 1024), "2026-10-24T12:00:00+00:00") + + assert document["text"].endswith("[Output truncated; inspect configuration on the host.]") + assert len(json.dumps(document).encode()) < 256 * 1024 + + +def test_a_listing_document_gives_back_its_time_and_its_listing() -> None: + """The launcher's listing document, read back, gives the time it was written with and the listing.""" + listing = {"rows": [{"kind": "ide", "name": "python-ide"}]} + + assert parse_listing(listing_document(listing, "2026-10-24T12:00:00+00:00")) == ("2026-10-24T12:00:00+00:00", listing) + + +@pytest.mark.parametrize("document", [[], {"format": 2}, {"format": 1, "at": "t", "listing": {}}, {"format": 1, "listing": {"rows": []}}]) +def test_a_listing_document_without_its_time_or_its_rows_is_refused(document: Any) -> None: + """A listing document of another format, without the time, or whose listing has no rows, is refused.""" + with pytest.raises(ProjectConfigurationError): + parse_listing(document) + + +def test_deferred_requests_survive_being_written_and_read() -> None: + """Requests kept for the host, rendered as the store's text and parsed again, are the same requests.""" + kept = [DeferredRequest("000001-authorize", "2026-10-24T10:00:00+00:00", ("authorize", "network", "host")), + DeferredRequest("000002-bind", "", ("bind", "home", "~/capsule home"))] + + assert parse_deferred(json.loads(render_deferred(kept))) == kept + assert kept[0].statement == "config authorize network host" + + +@pytest.mark.parametrize("document", [ + [], {"format": 1, "requests": {}}, {"format": 1, "requests": [{"id": "x", "arguments": ["ide"]}]}, + {"format": 1, "requests": [{"id": "000001-ide", "requested": 4, "arguments": ["ide"]}]}, + {"format": 1, "requests": [{"id": "000001-ide", "arguments": []}]}, +]) +def test_a_malformed_store_of_deferred_requests_is_refused(document: Any) -> None: + """A store that is not a format-1 document with a list of requests, or holds a request with an id outside + the contract, a time that is not text or no tokens, is refused.""" + with pytest.raises(ProjectConfigurationError): + parse_deferred(document) + + +def test_a_document_written_complete_is_read_back_and_leaves_no_temporary_file(tmp_path: Path) -> None: + """``write_complete`` publishes the document under the name given, and the directory then holds that file + alone.""" + path = write_complete(tmp_path / "000001-ide.result.json", {"format": 1, "text": "done"}) + + assert read_document(path) == {"format": 1, "text": "done"} + assert [item.name for item in tmp_path.iterdir()] == ["000001-ide.result.json"] + + +def test_publishing_over_a_symbolic_link_replaces_the_link_and_leaves_its_target_alone(tmp_path: Path) -> None: + """Anything in the capsule can plant a link where the launcher will publish. The published name becomes a + regular file with the document; the file the link pointed to is unchanged.""" + outside = tmp_path / "outside" + outside.write_text("unchanged") + destination = tmp_path / "000001-ide.result.json" + destination.symlink_to(outside) + + write_complete(destination, {"format": 1, "text": "done"}) + + assert not destination.is_symlink() and read_document(destination) == {"format": 1, "text": "done"} + assert outside.read_text() == "unchanged" + + +def test_a_document_is_never_read_through_a_symbolic_link(tmp_path: Path) -> None: + """A link is refused as a document, whether it points to nothing or to a readable file.""" + target = tmp_path / "target.json" + target.write_text("{}") + (tmp_path / "dangling.json").symlink_to(tmp_path / "missing") + (tmp_path / "pointing.json").symlink_to(target) + + for name in ("dangling.json", "pointing.json"): + with pytest.raises(ProjectConfigurationError, match="cannot open"): + read_document(tmp_path / name) + + +def test_a_document_that_is_not_a_regular_file_is_refused_without_waiting_for_it(tmp_path: Path) -> None: + """A named pipe where a document should be is refused as not a regular file; the read does not block on it.""" + pipe = tmp_path / "000001-ide.result.json" + os.mkfifo(pipe) + + with pytest.raises(ProjectConfigurationError, match="not a regular file"): + read_document(pipe) + + +def test_a_document_larger_than_the_limit_or_not_json_is_refused(tmp_path: Path) -> None: + """A file over the size limit is refused by its size, and a file that is not JSON by its content.""" + big = tmp_path / "big.json" + big.write_text("[" + "1," * 200000 + "1]") + partial = tmp_path / "partial.json" + partial.write_text('{"format":') + + with pytest.raises(ProjectConfigurationError, match="larger than"): + read_document(big) + with pytest.raises(ProjectConfigurationError, match="not a JSON document"): + read_document(partial) diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_console_requests.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_console_requests.py new file mode 100644 index 00000000..c41671df --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_console_requests.py @@ -0,0 +1,146 @@ +"""Unit tests of ``devcapsule/configuration/console_requests.py``: the requests kept for the host's confirmation. + +A checkout's kept requests live under the DevCapsule home, in a file found +from the checkout's record. Each test writes its own record, in the private +home the suite gives every test, and asks the product where that home is. +""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule.configuration.console_channel import DeferredRequest +from devcapsule.configuration.console_requests import ( + console_requests_path, deferred_requests, deferred_rows, request_rows, write_deferred, +) +from devcapsule.configuration.file_formats import ProjectConfigurationError, render_toml +from devcapsule.configuration.storage import config_root + +NETWORK = DeferredRequest("000001-authorize", "2026-10-24T10:00:00+00:00", ("authorize", "network", "host")) +DOCKER = DeferredRequest("000002-authorize", "2026-10-24T11:00:00+00:00", ("authorize", "docker-daemon", "host-socket")) + + +def a_record(directory: Path, *, name: str = "devcapsule.checkout.toml") -> Path: + """The record, in the test's home, of a checkout of the project ``owner/order`` that lies at ``directory``.""" + record = config_root() / "projects" / "owner" / "order" / name + record.parent.mkdir(parents=True, exist_ok=True) + record.write_text(render_toml({"checkout": {"path": str(directory)}}), encoding="utf-8") + return record + + +def test_a_checkout_that_was_asked_nothing_has_no_kept_request(tmp_path: Path) -> None: + """A registered checkout with no store has no kept request, and so has a checkout with no record at all.""" + assert deferred_requests(a_record(tmp_path / "order")) == [] + assert deferred_requests(tmp_path / "no-such-record.toml") == [] + + +def test_kept_requests_are_read_back_in_the_order_written(tmp_path: Path) -> None: + """Requests written for a checkout are the checkout's kept requests, in order.""" + record = a_record(tmp_path / "order") + + write_deferred(record, [NETWORK, DOCKER]) + + assert deferred_requests(record) == [NETWORK, DOCKER] + + +def test_the_store_lies_in_the_home_outside_the_directory_of_the_records(tmp_path: Path) -> None: + """The launcher mounts the records' directory into the capsule. The store of kept requests is under the + home's ``console-requests`` tree and not under that directory, so the capsule cannot reach it.""" + record = a_record(tmp_path / "order") + + path = write_deferred(record, [NETWORK]) + + assert path.is_file() and path.is_relative_to(config_root() / "console-requests") + assert not path.is_relative_to(record.parent) + + +def test_writing_no_request_removes_the_store(tmp_path: Path) -> None: + """When the last kept request is gone the store's file is removed, and the checkout has none again.""" + record = a_record(tmp_path / "order") + path = write_deferred(record, [NETWORK]) + + write_deferred(record, []) + + assert not path.exists() and deferred_requests(record) == [] + + +def test_a_store_that_would_grow_past_its_limit_is_refused_and_keeps_what_it_held(tmp_path: Path) -> None: + """Writing more than the store may hold is refused as a full queue, and the requests kept before are intact.""" + record = a_record(tmp_path / "order") + write_deferred(record, [NETWORK]) + huge = ("bind", *(["x" * 4096] * 63)) + + with pytest.raises(ProjectConfigurationError, match="queue is full"): + write_deferred(record, [NETWORK, DeferredRequest("000002-bind", "", huge), DeferredRequest("000003-bind", "", huge)]) + + assert deferred_requests(record) == [NETWORK] + + +def test_the_store_follows_the_checkouts_directory_when_its_record_is_renamed(tmp_path: Path) -> None: + """A checkout registered under another name keeps its requests: the store is found from the directory the + record names, not from the record's file name.""" + record = a_record(tmp_path / "order") + stored = write_deferred(record, [NETWORK]) + + renamed = record.rename(record.with_name("renamed.checkout.toml")) + + assert console_requests_path(renamed) == stored + assert deferred_requests(renamed) == [NETWORK] + + +def test_another_checkout_that_takes_over_a_records_name_does_not_inherit_its_requests(tmp_path: Path) -> None: + """A record under the same file name, of a checkout at another directory, has a store of its own: it starts + with no request, and what is kept for it leaves the first checkout's requests alone.""" + first = a_record(tmp_path / "order") + write_deferred(first, [NETWORK]) + first = first.rename(first.with_name("first.checkout.toml")) + + second = a_record(tmp_path / "another-copy") + + assert deferred_requests(second) == [] + write_deferred(second, [DOCKER]) + assert deferred_requests(second) == [DOCKER] and deferred_requests(first) == [NETWORK] + + +def test_a_kept_request_is_a_soft_decision_of_the_listing_with_the_command_that_applies_it() -> None: + """A kept request becomes a ``console`` row that names the request, when it was asked and what it stands + for, with the host command that applies it for the project given, and the same as a decision.""" + (row,) = request_rows([NETWORK], Path("/projects/order")) + + command = "devcapsule project --path /projects/order config console apply 000001-authorize" + assert (row.kind, row.name, row.source, row.pending, row.command) == ( + "console", "000001-authorize", "console request at 2026-10-24T10:00:00+00:00", + "confirm or discard: config authorize network host", command) + assert row.decision is not None + assert (row.decision.kind, row.decision.name, row.decision.description, row.decision.command, row.decision.reason) == ( + "console", "000001-authorize", "config authorize network host", command, "2026-10-24T10:00:00+00:00") + + +def test_without_a_project_directory_the_command_leaves_the_project_to_the_working_directory() -> None: + """With no project directory given, the applying command has no ``--path``.""" + (row,) = request_rows([NETWORK], None) + + assert row.command == "devcapsule project config console apply 000001-authorize" + + +def test_the_rows_of_a_checkout_are_its_kept_requests_and_none_without_a_record(tmp_path: Path) -> None: + """A checkout's rows are the rows of what its store holds; a checkout with no record has none.""" + record = a_record(tmp_path / "order") + write_deferred(record, [NETWORK, DOCKER]) + + assert deferred_rows(record, tmp_path / "order") == request_rows([NETWORK, DOCKER], tmp_path / "order") + assert deferred_rows(None, tmp_path / "order") == [] + + +def test_a_store_that_cannot_be_read_is_one_invalid_row_and_not_an_error(tmp_path: Path) -> None: + """A store whose file is not the contract's document does not stop the listing: it is one row, marked + invalid, that says to repair or remove the file.""" + record = a_record(tmp_path / "order") + write_deferred(record, [NETWORK]).write_text("{}", encoding="utf-8") + + (row,) = deferred_rows(record, tmp_path / "order") + + assert (row.kind, row.effective, row.pending) == ("console", "invalid", "repair or remove the console-requests file") + assert row.decision is None diff --git a/engineering-docs/development/integration-tests.md b/engineering-docs/development/integration-tests.md index 8190fc42..bd50abc6 100644 --- a/engineering-docs/development/integration-tests.md +++ b/engineering-docs/development/integration-tests.md @@ -31,7 +31,7 @@ cd devcapsule-src ``` The session builds `dist/devcapsule-local.pex` and runs -`pytest -m integration tests/integration`. The one module there, +`pytest -m integration tests/integration`. One module there, `test_pex_runtime.py`, proves what only the packaged form can prove: - the built executable dispatches the in-container `runtime` entrypoint and @@ -74,6 +74,32 @@ website submodule is not initialized or npm is absent, which is the case on the hosted runner. The contract it checks is [the content–website contract](../specifications/product/content-website-contract.md). +## Commands as processes, and a terminal + +A command whose work is to start another command, or to ask a developer at +a terminal, is tested by starting it. `test_console_channel_cli.py`, +`test_home_trust_cli.py` and `test_print_command_cli.py` do that, and they +share three rules. + +- **The test builds the environment of every process it starts.** A search + path, a home directory, and a named DevCapsule home, + `DEVCAPSULE_CONFIG_HOME`, under the test's directory. Nothing of the + developer's shell is handed on. The suite's fixture that hides the + capsule from a unit test cannot reach a program the test starts; a + process with no named home, started inside a capsule, reads the + launcher's mounted settings. With a named home the outcome is the same on + a plain host and inside a capsule, and under any interpreter that can + import `devcapsule`, whatever version its installed distribution says. +- **Docker is a stand-in on the search path.** A shell script named + `docker` answers that no image is local and refuses everything else. A + launch then ends at its first pull, after its questions and its writes, + and a launcher that asked Docker for more would be seen. +- **A question is answered on a pseudo-terminal.** `project run` asks only + when its input is a terminal. The test opens a pty, starts the launch on + it, types each answer when the output ends with the prompt it waits for, + and reads what was shown. This is the only test of the terminal's + dialogue while `commands/_run_flow.py` has no unit test file of its own. + ## Where the next integration test goes A test of a subsystem against the real things it uses belongs in From ed232fea2b42a2bae7a0d0a24a9457d8d8ed8f02 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Fri, 13 Nov 2026 00:55:12 +0000 Subject: [PATCH 54/75] Records: the console channel and pex files retired; why one interpreter passed and the other failed Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 25 ++++++-- .../2026-09-18-maintenance/CURRENT-STATUS.md | 63 +++++++++++++++++++ 2 files changed, 83 insertions(+), 5 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 6e2c672c..869d3dec 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -304,11 +304,26 @@ Against the close criteria, all four now hold: 4. `engineering-docs/development/unit-tests.md` describes the fixture as a private home on a machine that is no capsule. -What this record does not cover and is still true: one integration test, -`tests/integration/test_pex_runtime.py::test_built_pex_authors_shared_policy_and_keeps_personal_selection_local`, -fails inside a capsule. It is a legacy file and builds the launcher's -environment in the test's body from the test process's own, which names no -home; the fixture cannot reach a program a test starts. +Outside the unit suite the same cause had two more faces, both gone at +`33331a1d`: + +- `tests/integration/test_pex_runtime.py` built the launcher's environment + from the test process's own, which names no home, and one of its tests + failed inside a capsule. The file is retired in place: every executable + it starts gets an environment the test builds, with a named home. +- `tests/test_console_channel.py` started `project config` as processes + with no named home. Inside a capsule each read the launcher's mounted + settings and compared their `minimum-devcapsule` with the version of the + distribution installed in its interpreter. So the file passed under + `nox -s tests`, whose environment is installed fresh, and failed under a + checkout's `.venv` whose installed version was an old one, 0.2.15: every + command was refused with "requires DevCapsule 0.3.0; this launcher is + 0.2.15". The file is retired: unit tests in memory, and integration + tests that name the home of every process. + +The integration tests that need no Docker now pass inside the owner's +capsule: 146 passed, 3 skipped. `.venv/bin/python -m pytest tests/`, with +the stale interpreter, passes too: 3212 passed. ## Verification target and close criteria diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 78f0ad8c..cee555c6 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -205,6 +205,69 @@ capsule: 3095 passed, 9 expected to fail, 10 unexpectedly passed. The integration tests that need no Docker: 128 passed, 3 skipped, and the one standing failure. +**`tests/test_console_channel.py` retired; the pex integration file +retired in place, 2026-11-13.** Owner direction: say what `nox` sets up +that makes the console channel file pass, document it in the file, move it +to the integration tests, and fix the approach of what belongs in the +gate; mark the failing pex test expected to fail for now. + +Why it passed under `nox -s tests` and failed under +`.venv/bin/python -m pytest`: the launcher answers a console request by +running `project config` as a process. The legacy file named no home, so +inside a capsule each such process read the launcher's mounted settings, +which carry `minimum-devcapsule`, and compared it with the version of the +`devcapsule` distribution installed in its interpreter. `nox` installs the +current version in its session environment. The checkout's `.venv` holds an +editable install whose metadata still says 0.2.15, so every command was +refused with "requires DevCapsule 0.3.0; this launcher is 0.2.15". Outside a +capsule there is no mount and both interpreters pass. `nox` sets up nothing +else for it. + +- The file's 26 tests are 61 test functions in three new mirror files, + `configuration/test_console_channel.py`, + `configuration/test_console_requests.py` and + `commands/test_console_channel.py`, 4 more in `test_launch_review.py`, + and 9 more in `tests/integration/test_console_channel_cli.py`, whose + docstring carries the explanation above. The mirror names were free once + the legacy file was gone. +- The unit tests start no `config` command: the runner is a value of the + test. Seams for that, behaviour unchanged: `handle_request`, `sweep`, + `ChannelWatcher` and `apply_deferred` take `run`; `run_config` is + `child_environment` and `run_command` composed; `request_rows` in the + store; `launch_listing` in the launch review module, given the + checkout's name; `running_listing_document` and `render_running_listing` + for the listing inside a capsule. +- The process tests give every process a named home, so they pass in a + capsule and under the stale interpreter. Four of them run `project run` + on a pseudo-terminal with a stand-in for `docker`, and apply or leave a + kept request at the launch's question. +- The pex test was not marked: the conventions gate refuses a mark on a + legacy test, and the fix cost the same. + `tests/integration/test_pex_runtime.py` is retired in place, its eight + tests given docstrings and an environment the test builds, and the + failing one passes. +- 22 planted faults are each caught. +- `nox -s typecheck tests` in the capsule: 3212 passed, 1 expected to fail, + 1 unexpectedly passed. The same suite with `.venv/bin/python`: 3212 + passed. The integration tests that need no Docker: 146 passed, 3 skipped, + none failed, for the first time in this capsule. +- The gate: 99 legacy files holding 1,315 tests; 58 files follow the + conventions. + +What moved out of the pull-request gate with the process tests: the +terminal's question about a kept request in `commands/_run_flow.py`, whose +coverage in the unit suite fell from 87% to 71%, and the three +`config console` commands in `commands/project.py`, 93% to 91%. The +integration suite covers them. Not covered by any test now: the eight +lines of `_show_inside_capsule` in `project.py` that choose between the +channel and the older report, the two lines of `run_config` that pass +`host_confirmed` on, and the wrapper `launch_listing_document`. + +One finding for the owner, not acted on: *Release Policy* rule 9 says the +candidate workflow refuses a candidate whose test-run record has no run on +its revision or a failing one. No script or workflow reads +`test-runs.json`, on this branch or on `main`. + **The holding pen emptied; the mounted-settings bug is `fixed`, 2026-11-13.** Owner direction: delete the `test_home.py` test, fix `test_trust.py`. From a8c8408fc9aff59e5fc94de7ba23349e352703c7 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Fri, 13 Nov 2026 01:08:40 +0000 Subject: [PATCH 55/75] Bug record: this repository's own project configuration predates 0.3; blocking for 0.3.1 Owner's rating, 2026-11-13. The committed manifest is schema 1 and the lock is from matrix embedded-28; the release ships embedded-33. A refreshed .devcapsule, written on the host by the release's launcher, is committed before the final tag. Co-Authored-By: Claude --- ...tory-project-configuration-predates-0.3.md | 97 +++++++++++++++++++ engineering-docs/releases/v0.3.1/bugs.md | 1 + .../2026-09-18-maintenance/CURRENT-STATUS.md | 5 + 3 files changed, 103 insertions(+) create mode 100644 engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md diff --git a/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md b/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md new file mode 100644 index 00000000..8bdda92b --- /dev/null +++ b/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md @@ -0,0 +1,97 @@ +--- +status: confirmed +severity: blocking +target: 0.3.1 +owner: maintenance +opened: 2026-11-13 +requirements: [] +--- + +# This repository's own project configuration predates 0.3: the committed manifest and lock are not what the release writes + +## Symptom and expected behavior + +The committed `.devcapsule/devcapsule.toml` is a schema-1 manifest and the +committed `.devcapsule/devcapsule.linux-amd64.lock` was generated from the +resolution matrix `embedded-28`. 0.3.1 ships `embedded-33` and writes +schema-2 manifests. The owner's checkout carries an uncommitted rewrite of +both files, made by a launcher on 2026-11-04, which is itself two matrix +generations behind the release. + +Expected: the repository that ships 0.3.1 commits the project +configuration that a 0.3.1 launcher writes for it, a schema-2 manifest and +a lock from the release's matrix, written by a DevCapsule command and +validated as *Keep The Development Checkout Launchable* in +`WORKFLOW-LOCAL.md` requires. + +Owner's rating, 2026-11-13: blocking for 0.3.1. A refreshed `.devcapsule` +is committed before the release ships. + +## Environment and evidence + +Read on 2026-11-13 in the owner's capsule, launcher `v0.3.1-rc2`, on +`ws-maintenance/launch-phases` at `ed232fea`. + +| | Committed | Uncommitted in the owner's checkout | 0.3.1 | +|---|---|---|---| +| Manifest schema | 1, `need = [...]` with `python-ide` | 2, `required = [...]`, the IDE recommended | 2 | +| Last written | manifest `3dbe4cb9`, 2026-10-04; lock `dedb485b`, 2026-10-25 | both files, 2026-11-04 00:34 | | +| Matrix | `embedded-28` | `embedded-31` | `embedded-33` | +| Base digest | `8c97d308…` | `d7047ced…` | `d7047ced…`, what `project init` gives today | +| IDE in the lock | PyCharm 2026.2.0.1 | none, the project no longer requires one | | +| Antigravity CLI | 1.4.2 | 1.4.12 | | +| Claude Code | 2.1.302 | 2.1.314 | 2.1.321 | +| Codex | 0.163.0 | 0.166.0 | 0.167.0 | + +The uncommitted manifest also drops the top-level `workflow-type` key and +the hand-written comment that explains why `runtime.devcapsule-command` +declares no `runtime-effect`. + +Which command wrote the uncommitted files is not recorded. The lock's base +table carries the build name `v0.3.0-local-linux-x86_64`. + +Consequences seen while the files differed: + +- Three tests that read these files failed in the owner's checkout and + passed on the hosted runner, which sees the commit. They are deleted in + pull request #29; `tests/unit/devcapsule/configuration/test_capability_commands.py` + reads a frozen copy of the committed pair instead, + `tests/resources/compat/repository-2026-10-25/`. +- `tests/test_base_contract.py` still reads `.devcapsule/`. It passes with + the uncommitted files and with the committed ones. + +## Fix notes + +- Only a DevCapsule command writes these files, and inside a capsule a + command that changes the capsule's own project is refused: the refresh + runs on the host, with the launcher that is to be the release's. + `project init --regenerate` rewrites the lock from the embedded matrix + and migrates a schema-1 manifest to schema 2, keeping its leading + comments; see `docs/reference/cli.md`. +- Record the writing executable, its `version --json`, the validation + command and its result, as the local rule asks. Validate with + `config check` before and after. +- The uncommitted files of 2026-11-04 are not the fix: they are from + `embedded-31`. Regenerate; do not commit them as they are. +- A schema-2 manifest cannot be read by launchers older than 0.3.0. The + owner ruled on 2026-11-12 that compatibility with 0.2.14, 0.2.15 and + earlier may be dropped. +- Decide whether the IDE stays a recommendation, as the uncommitted + manifest has it, or is required again; and whether the comment on + `runtime.devcapsule-command` is kept. +- After the refresh, check `tests/test_base_contract.py` on the new files. + The frozen copy under `tests/resources/compat/` is not regenerated. + +## Verification target and close criteria + +1. The committed manifest is schema 2 and the committed lock names the + matrix of the release candidate that carries it. +2. `config check` with that candidate's launcher passes on a clean + checkout of the release branch, and the record of the refresh names the + executable and the command. +3. A launch of this repository's capsule from that clean checkout starts. +4. `nox -s tests` passes on the commit, on the hosted runner and inside the + capsule. + +Reopen if a later candidate's matrix moves and the committed lock is left +behind before the final tag. diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 425e4a2e..2a6a387d 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -13,6 +13,7 @@ before each candidate and record the reconciliation revision here. | Record | Status | Severity | Owner | Disposition | Next action | |---|---|---|---|---|---| +| [This repository's own project configuration predates 0.3: the committed manifest and lock are not what the release writes](../../bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md) | confirmed | blocking | maintenance | rated blocking by the owner on 2026-11-13: the committed manifest is schema 1 and the lock is from `embedded-28`, the release ships `embedded-33`; an uncommitted rewrite of 2026-11-04 in the owner's checkout is from `embedded-31` and is not the fix | on the host, with the release's launcher, regenerate and validate `.devcapsule`, record the executable and the command, commit before the final tag | | [Eclipse cannot be acquired from scratch on amd64: the libsoup package URLs return 404](../../bugs/devcapsule/2026-11-07-eclipse-amd64-libsoup-urls-return-404.md) | closed | major | maintenance | found by PR #338 on 2026-11-04, confirmed at the cut; both packages repinned at `3.4.4-5ubuntu0.10` (PR #10), matrix `embedded-32`; closed 2026-11-08 by a fresh amd64 Eclipse acquisition with an empty home on the downloaded `v0.3.1-rc1` | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index cee555c6..252578c1 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -5435,6 +5435,11 @@ claimed. No final release or graphical/end-user acceptance is claimed yet. ## Open Threads +- Blocking for 0.3.1, owner's rating of 2026-11-13: this repository's own + `.devcapsule` is committed in its pre-0.3 form, a schema-1 manifest and a + lock from `embedded-28`. A refreshed pair is committed before the release + ships; the refresh runs on the host with the release's launcher. Record: + [the 2026-11-13 bug](../../bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md). - Owner ruling, 2026-11-12: compatibility with 0.2.14, 0.2.15 and earlier may be dropped. The compatibility promise to users needs a defined story and a packaging, targeted for after 0.3.1; not started. Sent to From 7c78483f099c3f8243940bad00ce76c3b55067af Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Fri, 13 Nov 2026 11:26:40 +0000 Subject: [PATCH 56/75] Records: the mounted-settings bug closed; the configuration refresh checked on a copy, the write waits for the host The owner merged pull request #29 into release-0.3.1 at 82b9c07e and asked for the record to be closed. nox -s tests on the merged tree in the owner's capsule: 3212 passed, 1 expected to fail, 1 unexpectedly passed, the counts of the hosted run at the pull request's head. The repository's own .devcapsule is not committed here. The checkout's uncommitted pair is still the one of 2026-11-04, from embedded-31. With v0.3.1-rc2, project init --regenerate on a copy leaves the manifest as it is and moves the lock to embedded-33, Claude Code 2.1.321 and Codex 0.167.0. Inside the capsule the command refuses to write the capsule's own project; the record names the host command. Co-Authored-By: Claude --- ...-the-capsules-mounted-launcher-settings.md | 13 +++++- ...tory-project-configuration-predates-0.3.md | 40 +++++++++++++++++++ engineering-docs/releases/v0.3.1/bugs.md | 4 +- .../2026-09-18-maintenance/CURRENT-STATUS.md | 8 +++- 4 files changed, 60 insertions(+), 5 deletions(-) diff --git a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md index 869d3dec..413edd6a 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md +++ b/engineering-docs/bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md @@ -1,5 +1,5 @@ --- -status: fixed +status: closed severity: blocking target: 0.3.1 owner: maintenance @@ -325,6 +325,17 @@ The integration tests that need no Docker now pass inside the owner's capsule: 146 passed, 3 skipped. `.venv/bin/python -m pytest tests/`, with the stale interpreter, passes too: 3212 passed. +## Closed, 2026-11-13 + +Closed on the owner's word, after their merge of pull request #29 into +`release-0.3.1` at `82b9c07e`. The merge commit's tree is the tree of the +pull request's head, `a8c8408f`, whose hosted run passed. + +On the merged tree, in the owner's capsule, `nox -s tests`: 3212 passed, 1 +expected to fail, 1 unexpectedly passed, in 143 seconds; the hosted run at +the pull request's head gave the same counts. The conventions check counts +no breach. The four close criteria hold as the section above records them. + ## Verification target and close criteria 1. `nox -s tests` passes inside a capsule whose mounted settings carry diff --git a/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md b/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md index 8bdda92b..f8b43c65 100644 --- a/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md +++ b/engineering-docs/bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md @@ -82,6 +82,46 @@ Consequences seen while the files differed: - After the refresh, check `tests/test_base_contract.py` on the new files. The frozen copy under `tests/resources/compat/` is not regenerated. +## Progress, 2026-11-13: the refresh checked on a copy; the write waits for the host + +The owner asked for `.devcapsule` to be committed. The files in the +checkout were still the pair of 2026-11-04, so nothing is committed yet: +the first fix note stands. + +The proposed result, checked before it is applied, as the local rule asks. +Executable: `/usr/local/bin/devcapsule0`, SHA-256 `2c3ace0f…`, +`version --json` gives `0.3.1rc2`, `v0.3.1-rc2`, source revision +`be0140ca`. Its matrix is `embedded-33`, the one `release-0.3.1` carries at +`82b9c07e`; `resolution_matrix.py` is unchanged since the candidate. + +- On a copy of the checkout's uncommitted pair, in a scratch directory with + a home of its own, `project init --regenerate` exits 0. The manifest + comes out byte for byte as it went in. The lock changes in three places: + the matrix, `embedded-31` to `embedded-33`; Claude Code, 2.1.314 to + 2.1.321; Codex, 0.166.0 to 0.167.0. The base and the Antigravity CLI stay. +- `project config check` on the regenerated copy: "Configuration contract + valid", exit 3 for the decisions an empty home has not taken. +- On a copy of the committed pair the same command stops, exit 2, and asks + for the base and the two download authorizations: that manifest requires + an IDE. This path was not followed further. +- `devcapsule0 project config check` on the checkout as it is: "Configuration + contract valid", exit 0; host decisions cannot be assessed inside the + capsule. + +The write itself is refused inside the capsule, as designed: + + devcapsule: This command needs launcher-owned configuration or state. + Inside this capsule that configuration is read-only. Run outside the + capsule: devcapsule project --path + /home/costin/work.provisional/costin3/myProjects/devcapsule init --regenerate + +The regenerated copy was not copied over the checkout's files: only a +DevCapsule command writes them. Next: that command on the host with the +candidate's launcher, `config check` there, then the commit of the two +files. The manifest that results keeps the IDE as a recommendation and is +without the comment on `runtime.devcapsule-command`, unless the owner +decides otherwise first. + ## Verification target and close criteria 1. The committed manifest is schema 2 and the committed lock names the diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 2a6a387d..1ac35711 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -13,12 +13,12 @@ before each candidate and record the reconciliation revision here. | Record | Status | Severity | Owner | Disposition | Next action | |---|---|---|---|---|---| -| [This repository's own project configuration predates 0.3: the committed manifest and lock are not what the release writes](../../bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md) | confirmed | blocking | maintenance | rated blocking by the owner on 2026-11-13: the committed manifest is schema 1 and the lock is from `embedded-28`, the release ships `embedded-33`; an uncommitted rewrite of 2026-11-04 in the owner's checkout is from `embedded-31` and is not the fix | on the host, with the release's launcher, regenerate and validate `.devcapsule`, record the executable and the command, commit before the final tag | +| [This repository's own project configuration predates 0.3: the committed manifest and lock are not what the release writes](../../bugs/devcapsule/2026-11-13-repository-project-configuration-predates-0.3.md) | confirmed | blocking | maintenance | rated blocking by the owner on 2026-11-13: the committed manifest is schema 1 and the lock is from `embedded-28`, the release ships `embedded-33`; an uncommitted rewrite of 2026-11-04 in the owner's checkout is from `embedded-31` and is not the fix; the refresh was checked on a copy with `v0.3.1-rc2` on 2026-11-13: the manifest is unchanged and the lock moves to `embedded-33`, Claude Code 2.1.321 and Codex 0.167.0; the write is refused inside the capsule | the owner runs `devcapsule project --path /home/costin/work.provisional/costin3/myProjects/devcapsule init --regenerate` on the host and `config check` there; then the two files are committed, before the final tag | | [Eclipse cannot be acquired from scratch on amd64: the libsoup package URLs return 404](../../bugs/devcapsule/2026-11-07-eclipse-amd64-libsoup-urls-return-404.md) | closed | major | maintenance | found by PR #338 on 2026-11-04, confirmed at the cut; both packages repinned at `3.4.4-5ubuntu0.10` (PR #10), matrix `embedded-32`; closed 2026-11-08 by a fresh amd64 Eclipse acquisition with an empty home on the downloaded `v0.3.1-rc1` | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Codex status and version checks fail: the npm registry document exceeds the channel's 16 MiB cap](../../bugs/devcapsule/2026-11-08-codex-npm-metadata-exceeds-16-mib.md) | closed | major | maintenance | found 2026-11-08 reading the feed: Codex `inconclusive` for 45 runs since 2026-10-01; the full registry document is 18.7 MB against the channel's 16 MiB cap; resolved via PR #20 (`eb8ff8cf`, `Accept: application/vnd.npm.install-v1+json` in `NpmChannel.check()`); closed 2026-11-10 on `origin/component-status` (`0bc31c64`, `result: "ok"`, `consecutive_failures: 0`) and `project versions check` on downloaded `v0.3.1-rc2` (`2c3ace0f…`) | none; the 0.3.0 executable stays affected, 0.3.1 is the remedy | | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | -| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | fixed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed | make the isolation fixture a private home, then clear the expected-to-fail marks this cause explains; in pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture is fixed there too, so no unit test sees the capsule it runs in; since `8af31910` no mark depends on the capsule and the capsule's counts equal the hosted run's, 3129 passed; closes on the owner's validation and the merge of #29 | +| [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | closed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed; resolved in pull request #29, where the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture is fixed there too, so no unit test sees the capsule it runs in; since `8af31910` no mark depends on the capsule; closed 2026-11-13 on the owner's word after the merge of #29 (`82b9c07e`): `nox -s tests` on the merged tree in the owner's capsule gives the hosted run's counts, 3212 passed | none | | [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index 252578c1..e94b3cb3 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,7 +4,7 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; one blocking bug open since 2026-11-10, unit tests reading the capsule's mounted launcher settings, in fixing: on pull request #29 the 17 pass and `nox -s tests` passes in the owner's capsule, the shared fixture and 14 marks still to do; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; a first slice of the owner's read-then-decide direction on `ws-maintenance/launch-phases`, with the launch's decisions testable from values and the six legacy files of the 17 still to retire +State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; the blocking bug of 2026-11-10, unit tests reading the capsule's mounted launcher settings, closed 2026-11-13 on the owner's word after the merge of pull request #29 (`82b9c07e`); one blocking bug open since 2026-11-13, this repository's own project configuration predates 0.3: the refresh is checked on a copy and waits for the owner's `project init --regenerate` on the host; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; the owner's read-then-decide direction merged through #29, on top of #26: the launch's decisions are testable from values, the holding pen is empty and three files remain in the command-line debt list Definition read: WORKFLOW.md@e83f22a20701, WORKFLOW-LOCAL.md@e84d2678942b @@ -12,7 +12,7 @@ Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/launch-phases` from `ws-maintenance/host-inputs-at-source` c92d5254, stacked on PR #26; `ws-maintenance/host-inputs-at-source` from release-0.3.1 2f1109db, PR #26 open, the owner merges; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/0.3.1-blocking-bugs` from release-0.3.1 82b9c07e, records of the two blocking bugs, the owner merges; `ws-maintenance/launch-phases` merged through #29 and closed; `ws-maintenance/host-inputs-at-source` merged through #26 and closed; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` @@ -311,6 +311,10 @@ its revision or a failing one. No script or workflow reads The bug record is `fixed`: all four close criteria hold. It closes on the owner's validation and the merge of pull request #29. +Closed 2026-11-13: the owner merged #29 at `82b9c07e` and asked for the +record to be closed. `nox -s tests` on the merged tree in the capsule: 3212 +passed, 1 expected to fail, 1 unexpectedly passed, the hosted counts. + **The shared fixture fixed and the last two failing marked cases rewritten, 2026-11-12.** Owner direction: go at the first item of the debt list. From e3620b6b05a32942395f5681b7262b08c9c886df Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Fri, 13 Nov 2026 17:17:40 +0000 Subject: [PATCH 57/75] Drop the owner's idea in the pile: the processes we proved, advertised as reusable assets The owner's idea of 2026-11-13: package the development processes proved while building DevCapsule with DevCapsule, and advertise them. Inside a DevCapsule project the tooling gives them almost for free; how they reach a project outside is to be decided. The examples are pair review, unit testing by module, and recorded end-to-end scenarios. A section added by Claude says where each example stands today: pair review ships in the workflow definition, the unit test rules and the scenario recorder do not. Co-Authored-By: Claude Fable 5.2 --- ...-processes-we-proved-as-reusable-assets.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 engineering-docs/pile-of-ideas/2026-11-13-advertise-the-processes-we-proved-as-reusable-assets.md diff --git a/engineering-docs/pile-of-ideas/2026-11-13-advertise-the-processes-we-proved-as-reusable-assets.md b/engineering-docs/pile-of-ideas/2026-11-13-advertise-the-processes-we-proved-as-reusable-assets.md new file mode 100644 index 00000000..f9826a30 --- /dev/null +++ b/engineering-docs/pile-of-ideas/2026-11-13-advertise-the-processes-we-proved-as-reusable-assets.md @@ -0,0 +1,81 @@ +# Advertise the processes we proved while dogfooding as reusable assets + +From: Costin Cozianu, 2026-11-13, written up with Claude. + +While building DevCapsule with DevCapsule we worked out several development +processes, then tested, verified and validated them on our own work. Each one +is a trusted process we can hand to someone else. The idea: package them as +reusable assets and advertise them as such. + +An asset must be usable in two places: + +- Inside a DevCapsule project, where the user gets it almost for free from + our tooling. +- Outside a DevCapsule project. How is to be decided; see part 3. + +Examples of what we have: + +- The pair review process: one agent pair implements, a review partner of a + different engine reviews, and pull requests carry every step. +- Unit testing for real, in the sense of Parnas's modularity: a test belongs + to one module and constructs its own inputs. +- End-to-end tests with video recording, driven by scripts written in human + language. + +Why it could be worth doing: any of these can be implemented rather cheaply +these days, so the implementation is not what we offer. What we offer is that +they are at our users' fingertips, already implemented and already tested on +real work. That is a big thing. + +## 1. Name the assets and say what each one is + +Decide which processes qualify, and what an asset consists of: the rule text, +the tooling that carries it out, the evidence that it worked for us. The three +examples above are the starting list, not the whole list. + +## 2. Inside a DevCapsule project: almost for free + +A user of a DevCapsule project gets each asset from our tooling with little +or no setup. + +## 3. Outside a DevCapsule project + +To be decided. One possibility: the `devcapsule` command line, integrated +with the user's own agent command line. This part is the least settled of the +four. + +## 4. Advertise them + +Present the assets on the website and in the documentation as a reason to +choose DevCapsule, each with the evidence from our own use. + +## What exists today + +Added by Claude from the code and records on `release-0.3.1`, as input to +part 1. The three examples are at three different distances from a user. + +- Pair review ships already. It is topic 9.11 of the workflow definition + that `devcapsule bootstrap project` installs into an adopter's repository + (`devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md`). + How this checkout applies it, with the engines named, is the section *Pair + Review Loop In This Checkout* of `WORKFLOW-LOCAL.md`, which is not shipped. +- The unit test rules do not ship. They are the sections *Unit Tests* and + *Host Inputs* of this repository's `WORKFLOW-LOCAL.md`, with the checkers + and guards that enforce them in `devcapsule-src`. They are written for this + project's layout and for Python. +- The recorded end-to-end scenarios do not ship. The recorder is test code, + `devcapsule-src/tests/e2e/scenario_recorder.py`, run through + `nox -s ide-smoke -- --scenario`; one scenario exists, + `eclipse-hello-time-debug`. A scenario is a JSON file of recorded actions + that an agent authors through the recorder's interactive mode. The guide is + `engineering-docs/development/running-e2e-scenario-recordings.md`. + +## Not checked + +- How far the scenario format is from a script in human language. I read the + implementation note, not the scenario file or the recorder. +- Whether the recorder can drive anything other than an IDE in a capsule's + contained display, which decides what it is worth to a user's own project. +- Which other processes from our dogfooding would qualify. +- What the website and the user documentation already say about any of + these. From 29fca19c6a87c5368669ef30d7b407f9833e93bb Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Sat, 14 Nov 2026 01:51:13 +0000 Subject: [PATCH 58/75] Standardize E2E scenario evidence under tests/e2e/evidence// Write recorded end-to-end scenario outputs to devcapsule-src/tests/e2e/evidence//scenario-video.webm inside the project mount so clean builds of dist/ do not delete recordings and the capsule web console can stream them directly. Ignore tests/e2e/evidence/ in Git, exclude evidence/ from pytest, mypy, and validate_unittests_follow_conventions.py tree walks, default --evidence in scenario_recorder.py and --scenario IDE smoke runs to EVIDENCE_DIR / spec.id, support launch_browser steps, and update the workflow rules, humane companions, and E2E developer guides. Co-authored-by: Gemini 4 Carbon (Medium) Antigravity --- WORKFLOW-LOCAL-humane.md | 5 +- WORKFLOW-LOCAL.md | 6 +- WORKFLOW-humane.md | 64 +++++++++-------- WORKFLOW.md | 11 ++- devcapsule-src/.gitignore | 4 ++ devcapsule-src/pyproject.toml | 2 + .../validate_unittests_follow_conventions.py | 2 +- devcapsule-src/tests/e2e/scenario_recorder.py | 70 ++++++++++++++++--- .../tests/e2e/test_ide_comes_alive.py | 4 +- ...t_validate_unittests_follow_conventions.py | 18 +++++ engineering-docs/development/e2e-tests.md | 28 +++++--- .../running-e2e-scenario-recordings.md | 29 +++++--- 12 files changed, 177 insertions(+), 66 deletions(-) diff --git a/WORKFLOW-LOCAL-humane.md b/WORKFLOW-LOCAL-humane.md index 1c66232f..a1ee9dce 100644 --- a/WORKFLOW-LOCAL-humane.md +++ b/WORKFLOW-LOCAL-humane.md @@ -152,7 +152,10 @@ what it is not testing; it runs on demand, and a test that needs the daemon says so with a marker; the type check and the documentation contract are checks of the gate, not tests. An end-to-end test drives the product as a user does, fakes nothing, and reads the result from outside; -it runs on demand, and at least one runs for every release. +it runs on demand, at least one runs for every release, smoke-run logs land +under `devcapsule-src/dist/e2e-evidence/`, and recorded scenarios land under +`devcapsule-src/tests/e2e/evidence//scenario-video.webm` outside +`dist/`. **Intended effect.** Any agent on any machine can build and test the project without guessing, and "the tool is missing" is a finding only after following diff --git a/WORKFLOW-LOCAL.md b/WORKFLOW-LOCAL.md index e84d2678..94a29cb6 100644 --- a/WORKFLOW-LOCAL.md +++ b/WORKFLOW-LOCAL.md @@ -159,8 +159,10 @@ in [`INFORMATION-MODEL.md`](devcapsule-src/devcapsule/assets/project_workflow/de `pex_clean_machine`, `recursive_dogfood_e2e`, and `ide-smoke`. An end-to-end test drives the product through its user entry point, fakes nothing, and reads the result from outside. Each needs Docker and is - opt-in. At least one runs for every release. Evidence lands under - `devcapsule-src/dist/e2e-evidence/`. See + opt-in. At least one runs for every release. Smoke-run logs land under + `devcapsule-src/dist/e2e-evidence/`. Recorded scenarios land under + `devcapsule-src/tests/e2e/evidence//scenario-video.webm`, + ignored by Git and outside `dist/`. See [end-to-end tests](engineering-docs/development/e2e-tests.md). - **Smoke test**: `.venv/bin/python -m nox -s smoke` starts the built executable and proves its commands answer. `nox -s ide-smoke` launches each diff --git a/WORKFLOW-humane.md b/WORKFLOW-humane.md index 2e920e46..61581e8b 100644 --- a/WORKFLOW-humane.md +++ b/WORKFLOW-humane.md @@ -695,38 +695,46 @@ be, the console's process topology, and a release's branch and tag history. ### 9.6 rule 7 Recorded visual tests, and the no on explainer videos **Rule.** Prefer a recording harness for end-to-end tests of visual software, -keep the recording as acceptance evidence, and do not generate explainer -videos for the human. +keep the recording as acceptance evidence under +`/evidence//scenario-video.webm` inside the project +mount, ignored by Git and outside build directories that a clean build removes, +and do not generate explainer videos for the human. **Intended effect.** When a test says an IDE came alive and a file was saved, -a human can watch it happen rather than trust a log line, and nobody spends -tokens producing a narrated video about work when the recording of the work -itself exists. +a human can watch it happen through the capsule web console without a clean +build deleting the movie, every agent writes scenario evidence to the same +project-relative path, and nobody spends tokens producing a narrated video +about work when the recording of the work itself exists. **Motivation.** Owner decisions of 2026-10-09, closing the last item of the -Karpathy list. His fourth step, bespoke generated explainer videos, was judged -not worth adopting: one owner, a text-native project, no evidence of need, and -a recorded no so that nobody reopens it without new evidence. The recording -preference is the exception that the discussion surfaced: the IDE smokes of -2026-10-04 kept Playwright movies and screenshots of IntelliJ, Rider and -Eclipse coming alive and saving a file, and those recordings were what the -owner could accept at a glance when a textual report could not have carried -the same conviction. The rule is a bias, not a mandate, because some visual -software cannot be driven by a recording harness; where it can, the recording -is the cheapest acceptance evidence there is. - -**The example, as this project does it.** The IDE smoke in -`devcapsule-src/tests/e2e/ide_session.py` opens a Playwright browser context -with `record_video_dir=` and `record_video_size=`, -drives noVNC to the IDE, takes `canvas.screenshot(path=".../desktop.png")` at -the moment it asserts the desktop is alive, and after the session saves the -context's video with `video.save_as(".../desktop.webm")`. The evidence -directory, one per run under `devcapsule-src/dist/e2e-evidence/ide-smoke/`, -then holds the report, the screenshot and the movie together, and the report -names the movie file so a reader can find it. The same pattern appears in -`visual_smoke.py`. Any other harness qualifies if it can produce the same -three things: a movie of the whole session, screenshots at cited moments, and -a report that names both. +Karpathy list, and 2026-11-14, standardizing the scenario evidence path after +two agents placed `.webm` recordings in different trees (`dist/` vs `e2e/`). +His fourth step, bespoke generated explainer videos, was judged not worth +adopting: one owner, a text-native project, no evidence of need, and a recorded +no so that nobody reopens it without new evidence. The recording preference is +the exception that the discussion surfaced: the IDE smokes of 2026-10-04 kept +Playwright movies and screenshots of IntelliJ, Rider and Eclipse coming alive +and saving a file, and those recordings were what the owner could accept at a +glance when a textual report could not have carried the same conviction. Placing +scenario recordings under `/evidence//scenario-video.webm` +keeps them inside the project mount (where the web console can serve them), +colocated with `scenarios/` under the project's single end-to-end test root, +and safe from `dist/` wipes. The rule is a bias, not a mandate, because some +visual software cannot be driven by a recording harness; where it can, the +recording is the cheapest acceptance evidence there is. + +**The example, as this project does it.** Recorded scenarios in +`devcapsule-src/tests/e2e/scenario_recorder.py` load `` from +`devcapsule-src/tests/e2e/scenarios/.json` and write +`scenario-video.webm`, `poster.png`, `step-NNN.png`, and `scenario-result.json` +under `devcapsule-src/tests/e2e/evidence//`. Surface-level IDE +smokes in `devcapsule-src/tests/e2e/ide_session.py` and `visual_smoke.py` open a +Playwright browser context with `record_video_dir=` and +`record_video_size=`, drive noVNC to the IDE, capture screenshots at +asserted moments, and save the context's `.webm` movie alongside the report +under `devcapsule-src/dist/e2e-evidence/ide-smoke/`. Any other harness +qualifies if it can produce the same three things: a movie of the whole +session, screenshots at cited moments, and a report that names both. ### 9.8 and 9.9 Checkpoints and session close diff --git a/WORKFLOW.md b/WORKFLOW.md index e83f22a2..196d3760 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -243,6 +243,11 @@ file's frontmatter names the release this text ships in; see topic 4.1. Rules changed since 0.3.0: +- **Build-safe scenario evidence path.** Topic 9.6 rule 7: write recorded + end-to-end scenario evidence under `/evidence//scenario-video.webm` + inside the project mount, ignored by Git and outside directories that a clean + build removes. Migration: move retained scenario recordings out of build + output directories and ignore `/evidence/` in Git. - **Pile of ideas.** Topic 12.13: an idea nobody has triaged is one file under `engineering-docs/pile-of-ideas/`; anyone adds one on the working branch; `project-management` reads the pile at its session starts and @@ -1331,8 +1336,10 @@ session-resumption feature. `record_video_dir` and `record_video_size`, save the context's video as a `.webm` beside the test's report, and take `page.screenshot` at the moments the report cites. Keep the recording as acceptance evidence. - Do not generate explainer videos as a way to explain work to the human; - the recording of what ran is the video the project keeps. + Write recorded scenario evidence under `/evidence//scenario-video.webm` + inside the project mount, ignored by Git and outside directories that a + clean build removes. Do not generate explainer videos as a way to explain + work to the human; the recording of what ran is the video the project keeps. ### 9.7 Responsibilities diff --git a/devcapsule-src/.gitignore b/devcapsule-src/.gitignore index 73187a29..35432f28 100644 --- a/devcapsule-src/.gitignore +++ b/devcapsule-src/.gitignore @@ -19,3 +19,7 @@ dist/ .coverage.* diff-cover.json diff-cover.md + +# Recorded end-to-end scenario evidence, kept inside the project mount for the +# web console and outside dist/ so clean builds never remove recordings. +tests/e2e/evidence/ diff --git a/devcapsule-src/pyproject.toml b/devcapsule-src/pyproject.toml index 1ce643d1..37dc4aba 100644 --- a/devcapsule-src/pyproject.toml +++ b/devcapsule-src/pyproject.toml @@ -79,6 +79,7 @@ include = ["devcapsule*"] [tool.pytest.ini_options] testpaths = ["tests"] pythonpath = ["."] +norecursedirs = ["evidence", "resources", ".*", "build", "dist", "*.egg"] addopts = [ "--cov=devcapsule", "--cov-report=term-missing", @@ -109,6 +110,7 @@ skip_covered = true [tool.mypy] python_version = "3.12" files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py", "scripts/validate_unittests_follow_conventions.py", "scripts/publish_coverage_numbers_to_pr.py"] +exclude = ["^tests/e2e/evidence/"] warn_unused_configs = true show_error_codes = true pretty = true diff --git a/devcapsule-src/scripts/validate_unittests_follow_conventions.py b/devcapsule-src/scripts/validate_unittests_follow_conventions.py index 1b51f303..642ed8dd 100644 --- a/devcapsule-src/scripts/validate_unittests_follow_conventions.py +++ b/devcapsule-src/scripts/validate_unittests_follow_conventions.py @@ -84,7 +84,7 @@ ``devcapsule-src``; a ``#`` starts a comment. """ -_EXCLUDED_PARTS = frozenset({"resources"}) +_EXCLUDED_PARTS = frozenset({"resources", "evidence"}) @dataclass(frozen=True) diff --git a/devcapsule-src/tests/e2e/scenario_recorder.py b/devcapsule-src/tests/e2e/scenario_recorder.py index a8dd8352..d1435790 100644 --- a/devcapsule-src/tests/e2e/scenario_recorder.py +++ b/devcapsule-src/tests/e2e/scenario_recorder.py @@ -47,7 +47,8 @@ ) SCENARIOS_DIR = Path(__file__).resolve().parent / "scenarios" -VALID_STEP_ACTIONS = ("click", "double_click", "right_click", "type", "press", "wait") +EVIDENCE_DIR = Path(__file__).resolve().parent / "evidence" +VALID_STEP_ACTIONS = ("click", "double_click", "right_click", "type", "press", "wait", "launch_browser") MAX_WAIT_MS = 30_000 """Longest ``wait`` step; ``seconds`` is accepted up to the same bound.""" CONTROLLER_COMMAND_TIMEOUT = 120.0 @@ -179,7 +180,7 @@ def parse(cls, value: object) -> ActionStep: raise DriverError(f"Invalid wait ms: {ms!r}") if not isinstance(text, str) or not isinstance(reason, str): raise DriverError("ActionStep text and reason must be strings") - if action in ("type", "press") and not text: + if action in ("type", "press", "launch_browser") and not text: raise DriverError(f"Scenario action {action!r} requires non-empty text") return cls(action=action, x=x, y=y, text=text, ms=ms, reason=reason) @@ -281,6 +282,38 @@ def seed_scenario_workspace(workspace: Path, spec: ScenarioSpec) -> list[Path]: return written +def _launch_capsule_browser(container: str, url: str) -> None: + """Launch headed Chromium on the child capsule's X11 display pointing at ``url``.""" + script = f""" +set -euo pipefail +DISP_NUM=$(ls /tmp/.X11-unix | sort | head -n 1 | cut -c2-) +XAUTH=$(ls /tmp/devcapsule-runtime-*/display/Xauthority | sort | head -n 1) +CHROME=$(ls /opt/playwright/browsers/chromium-*/chrome-linux*/chrome | sort | tail -n 1) +export DISPLAY=":$DISP_NUM" +export XAUTHORITY="$XAUTH" +nohup "$CHROME" \\ + --no-sandbox \\ + --disable-dev-shm-usage \\ + --disable-gpu \\ + --no-first-run \\ + --no-default-browser-check \\ + --disable-infobars \\ + --user-data-dir=/tmp/scenario-chrome-profile \\ + --window-position=470,46 \\ + --window-size=1105,910 \\ + --app="{url}" /tmp/scenario-chrome.log 2>&1 & +""" + res = subprocess.run( + ["docker", "exec", "-d", "--user", f"{os.getuid()}:{os.getgid()}", container, "bash", "-lc", script], + capture_output=True, + text=True, + check=False, + timeout=30.0, + ) + if res.returncode != 0: + raise DriverError(f"Failed to launch browser in capsule: {res.stdout}\n{res.stderr}") + + class BurstFrameRecorder: """Captures active UI transition frames to eliminate LLM-thinking dead air.""" @@ -296,7 +329,7 @@ def record_frames(self, page: Any, count: int = 4, interval_ms: int = 120) -> No if interval_ms > 0: page.wait_for_timeout(interval_ms) - def apply_step(self, page: Any, step: ActionStep) -> None: + def apply_step(self, page: Any, step: ActionStep, container: str | None = None) -> None: kind = step.action if kind == "click": page.mouse.move(step.x, step.y, steps=6) @@ -330,6 +363,11 @@ def apply_step(self, page: Any, step: ActionStep) -> None: rem = step.ms - recorded * 150 if rem > 0: page.wait_for_timeout(rem) + elif kind == "launch_browser": + if not container: + raise DriverError("Scenario action 'launch_browser' requires an active capsule container") + _launch_capsule_browser(container, step.text) + self.record_frames(page, count=16, interval_ms=160) else: raise DriverError(f"Unsupported action step: {kind}") @@ -486,7 +524,7 @@ def run_scenario_replay( for index, raw_step in enumerate(spec.actions, start=1): step = raw_step.substitute(variables) - recorder.apply_step(page, step) + recorder.apply_step(page, step, container=session.container) executed.append(asdict(step)) shot = evidence / f"step-{index:03d}.png" page.screenshot(path=str(shot)) @@ -680,7 +718,7 @@ def serve_interactive_controller( raw_actions = payload.get("actions", []) for raw in raw_actions: step = ActionStep.parse(raw).substitute(variables) - recorder.apply_step(page, step) + recorder.apply_step(page, step, container=session.container) action_log.append(asdict(step)) step_counter += 1 shot = evidence / f"step-{step_counter:03d}.png" @@ -762,7 +800,12 @@ def main(argv: list[str] | None = None) -> int: serve_p = sub.add_parser("serve", help="Start an interactive E2E IDE session controller") serve_p.add_argument("--scenario", required=True, help="Scenario ID or path to JSON") - serve_p.add_argument("--evidence", type=Path, required=True, help="Evidence output directory") + serve_p.add_argument( + "--evidence", + type=Path, + default=None, + help="Evidence output directory (default: tests/e2e/evidence/)", + ) serve_p.add_argument("--pex", type=Path, required=True, help="Path to devcapsule PEX executable") ctl_p = sub.add_parser("ctl", help="Send a JSON command to a running controller") @@ -771,7 +814,12 @@ def main(argv: list[str] | None = None) -> int: replay_p = sub.add_parser("replay", help="Run a scenario deterministically and record video") replay_p.add_argument("--scenario", required=True, help="Scenario ID or path to JSON") - replay_p.add_argument("--evidence", type=Path, required=True, help="Evidence output directory") + replay_p.add_argument( + "--evidence", + type=Path, + default=None, + help="Evidence output directory (default: tests/e2e/evidence/)", + ) replay_p.add_argument("--pex", type=Path, required=True, help="Path to devcapsule PEX executable") args = parser.parse_args(argv) @@ -781,7 +829,8 @@ def main(argv: list[str] | None = None) -> int: return 0 if args.subcommand == "serve": spec = load_scenario(args.scenario) - serve_interactive_controller(args.pex, spec, args.evidence) + evidence = args.evidence if args.evidence is not None else EVIDENCE_DIR / spec.id + serve_interactive_controller(args.pex, spec, evidence) return 0 if args.subcommand == "ctl": try: @@ -796,12 +845,13 @@ def main(argv: list[str] | None = None) -> int: if args.subcommand == "replay": os.environ["DEVCAPSULE_SMOKE_COMPONENT_BROWSER"] = "1" spec = load_scenario(args.scenario) + evidence = args.evidence if args.evidence is not None else EVIDENCE_DIR / spec.id surface = next(s for s in SURFACES if s.name == spec.surface) with tempfile.TemporaryDirectory() as tmp_str: - with ide_session(args.pex, surface, Path(tmp_str), args.evidence) as session: + with ide_session(args.pex, surface, Path(tmp_str), evidence) as session: assert desktop_page_answers(session.desktop_url) == 200 wait_for_ide_window(session) - result = run_scenario_replay(session, args.evidence, spec) + result = run_scenario_replay(session, evidence, spec) print(json.dumps(result, indent=2)) return 0 return 1 diff --git a/devcapsule-src/tests/e2e/test_ide_comes_alive.py b/devcapsule-src/tests/e2e/test_ide_comes_alive.py index 465a45a7..7f7f8762 100644 --- a/devcapsule-src/tests/e2e/test_ide_comes_alive.py +++ b/devcapsule-src/tests/e2e/test_ide_comes_alive.py @@ -123,11 +123,11 @@ def test_ide_comes_alive(surface: IdeSurface, built_pex: Path, tmp_path: Path, e (evidence / "component-browser.json").write_text(browser.stdout, encoding="utf-8") assert json.loads(browser.stdout)["text"] == "component browser alive" if scenario_name := os.environ.get("DEVCAPSULE_SMOKE_SCENARIO"): - from tests.e2e.scenario_recorder import load_scenario, run_scenario_replay + from tests.e2e.scenario_recorder import EVIDENCE_DIR, load_scenario, run_scenario_replay spec = load_scenario(scenario_name) assert spec.surface == surface.name, f"Scenario {spec.id} targets {spec.surface}, not {surface.name}" - run_scenario_replay(session, evidence, spec) + run_scenario_replay(session, EVIDENCE_DIR / spec.id, spec) if os.environ.get("DEVCAPSULE_SMOKE_AGENT") == "1": from tests.e2e.visual_smoke import run_visual_smoke diff --git a/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py b/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py index ad9ae601..4cc1d515 100644 --- a/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py +++ b/devcapsule-src/tests/unit/scripts/test_validate_unittests_follow_conventions.py @@ -335,6 +335,24 @@ def test_main_fails_when_the_base_cannot_be_resolved(tmp_path: Path, capsys: pyt assert "cannot resolve base 'nowhere'" in capsys.readouterr().err +def test_main_ignores_python_files_under_excluded_resources_and_evidence_trees( + tmp_path: Path, capsys: pytest.CaptureFixture[str] +) -> None: + """Precondition: a repository whose ``tests/resources`` and ``tests/e2e/evidence`` + trees hold undocumented ``test_*.py`` and ``conftest.py`` files that import the + command line. Action: run ``main``. Postcondition: exit 0 with 0 checked files + and 0 breaches.""" + root = tmp_path / "devcapsule-src" + for excluded in (root / "tests" / "resources", root / "tests" / "e2e" / "evidence" / "demo-run"): + excluded.mkdir(parents=True) + (excluded / "test_captured.py").write_text("from devcapsule import cli\n" + UNDOCUMENTED) + (excluded / "conftest.py").write_text("from devcapsule import cli\n") + _git(root, "init", "-q", "-b", "main") + _git(root, "commit", "-q", "--allow-empty", "-m", "base") + assert conventions.main(["--base", "main", "--project-root", str(root)]) == 0 + assert "0 files follow the convention; 0 breaches" in capsys.readouterr().out + + # Rule 4, the command line. ``_mirror`` gives each case a mirror file that the # other rules accept, so that a breach reported here is rule 4's. diff --git a/engineering-docs/development/e2e-tests.md b/engineering-docs/development/e2e-tests.md index 16d77a72..fc65f398 100644 --- a/engineering-docs/development/e2e-tests.md +++ b/engineering-docs/development/e2e-tests.md @@ -35,9 +35,12 @@ or names the date it was added. a pass; a test that passes on its second run has found a bug or a bad test, and either gets a record. Added 2026-11-06, from the claim test of 2026-09-22. -6. Every run leaves evidence under `dist/e2e-evidence/`, named by the +6. Every smoke run leaves evidence under `dist/e2e-evidence/`, named by the executable's identity and the environment: the host, the daemon, the - base image by digest. The acceptance record cites it; nobody + base image by digest; recorded scenarios (`scenario_recorder.py` and + `--scenario`) write build-safe recordings under + `tests/e2e/evidence//scenario-video.webm` (ignored by Git and + outside `dist/`). The acceptance record cites it; nobody reconstructs it from memory. 7. Each test proves one thing a user would notice, and the table below names it, so a failure names the broken journey. A test that proves a @@ -125,6 +128,11 @@ to installing `xprop` in every image. - `dist/e2e-base-build.json`: the base a `--build-base` run built, its image id, and the builder's identity and checksum. +- `tests/e2e/evidence//`: recorded scenario videos + (`scenario-video.webm`, `agent-desktop-raw.webm`), step screenshots + (`step-NNN.png`, `poster.png`), and `scenario-result.json`, kept inside the + project mount for Web Console playback and outside `dist/` so clean builds + keep them intact. - `dist/e2e-evidence/ide-smoke/-/`: one directory per IDE smoke run, never overwritten, with `run.json` naming the executable and, per surface, the launcher and init logs, the window found, the records @@ -148,18 +156,20 @@ Run a catalog scenario through `ide-smoke`; `--scenario` needs exactly one .venv/bin/python -m nox -s ide-smoke -- --surface eclipse --scenario eclipse-hello-time-debug --component-browser ``` -Or invoke the recorder module directly against an existing PEX executable: +Or invoke the recorder module directly against an existing PEX executable +(`--evidence` defaults to `tests/e2e/evidence/`): ```sh PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder replay \ --scenario eclipse-hello-time-debug \ - --evidence dist/e2e-evidence/eclipse-debug \ + --evidence tests/e2e/evidence/eclipse-hello-time-debug \ --pex dist/devcapsule-local.pex ``` The replay seeds `seed_files` into the disposable project workspace, executes each `ActionStep` (`click`, `double_click`, `right_click`, `type`, `press`, -`wait`) with `${PROJECT_PATH}` and `${WORKSPACE}` substitution, and writes: +`wait`) with `${PROJECT_PATH}` and `${WORKSPACE}` substitution, and writes into +`tests/e2e/evidence//`: - `scenario-video.webm`: pause-free 12 fps VP8 WebM encoded by `BurstFrameRecorder` using `ffmpeg` (`image2pipe` `mjpeg` $\rightarrow$ `libvpx`) from either the host or @@ -180,21 +190,21 @@ inner capsule's desktop turn by turn without recording LLM thinking pauses: # Start the child IDE capsule and local HTTP controller: PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder serve \ --scenario eclipse-hello-time-debug \ - --evidence /tmp/scenario-run \ + --evidence tests/e2e/evidence/eclipse-hello-time-debug \ --pex dist/devcapsule-local.pex # Inspect the current screen and X11 window list: PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ - --evidence /tmp/scenario-run '{"cmd":"screenshot"}' + --evidence tests/e2e/evidence/eclipse-hello-time-debug '{"cmd":"screenshot"}' # Execute a batch of keyboard/mouse steps (frames are recorded only during active steps): PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ - --evidence /tmp/scenario-run \ + --evidence tests/e2e/evidence/eclipse-hello-time-debug \ '{"cmd":"act","actions":[{"action":"press","text":"F11"},{"action":"wait","ms":3000}]}' # Finalize and encode scenario-video.webm: PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ - --evidence /tmp/scenario-run '{"cmd":"stop"}' + --evidence tests/e2e/evidence/eclipse-hello-time-debug '{"cmd":"stop"}' ``` When the interactive session finishes, `action-log.json` holds the exact diff --git a/engineering-docs/development/running-e2e-scenario-recordings.md b/engineering-docs/development/running-e2e-scenario-recordings.md index 8510239f..67392157 100644 --- a/engineering-docs/development/running-e2e-scenario-recordings.md +++ b/engineering-docs/development/running-e2e-scenario-recordings.md @@ -78,14 +78,20 @@ nox -s ide-smoke -- \ ## 3. Where to find the recorded video and screenshots -Every `nox -s ide-smoke` run creates a fresh, timestamped directory under: +Recorded scenario runs (`--scenario` or `scenario_recorder`) write their +artifacts into the build-safe, git-ignored `evidence//` directory +beside `scenarios/` (so clean `dist/` builds never remove recordings, and the +DevCapsule web console can stream them directly from the project mount): ```text -devcapsule-src/dist/e2e-evidence/ide-smoke/-// +devcapsule-src/tests/e2e/evidence// ``` -For example, an Eclipse run writes into -`dist/e2e-evidence/ide-smoke/20261021T165500Z-a1b2c3/eclipse/`: +(Surface-level `nox -s ide-smoke` logs remain under +`devcapsule-src/dist/e2e-evidence/ide-smoke/-//`.) + +For example, replaying `eclipse-hello-time-debug` writes into +`devcapsule-src/tests/e2e/evidence/eclipse-hello-time-debug/`: | File | Contents | |---|---| @@ -104,10 +110,11 @@ scenario to act out live against an IDE capsule, run the interactive HTTP controller so LLM thinking time between turns is never recorded into the video: ```sh -# 1. Start the child IDE capsule and local HTTP controller in the background: +# 1. Start the child IDE capsule and local HTTP controller in the background +# (--evidence defaults to tests/e2e/evidence/): PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder serve \ --scenario eclipse-hello-time-debug \ - --evidence /tmp/scenario-live \ + --evidence tests/e2e/evidence/eclipse-hello-time-debug \ --pex dist/devcapsule-local.pex ``` @@ -118,11 +125,11 @@ Once `controller.json` appears in `--evidence`, the agent drives the IDE with ```sh # 2. Capture the current screen and X11 window list: PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ - --evidence /tmp/scenario-live '{"cmd":"screenshot"}' + --evidence tests/e2e/evidence/eclipse-hello-time-debug '{"cmd":"screenshot"}' # 3. Send mouse/keyboard actions (frames are recorded only while actions execute): PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ - --evidence /tmp/scenario-live \ + --evidence tests/e2e/evidence/eclipse-hello-time-debug \ '{"cmd":"act","actions":[ {"action":"press","text":"F11","reason":"Launch Eclipse debugger"}, {"action":"wait","ms":5000,"reason":"Wait for breakpoint hit"} @@ -130,9 +137,9 @@ PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ # 4. Stop the session and encode scenario-video.webm: PYTHONPATH=src:. .nox/ide-smoke/bin/python -m tests.e2e.scenario_recorder ctl \ - --evidence /tmp/scenario-live '{"cmd":"stop"}' + --evidence tests/e2e/evidence/eclipse-hello-time-debug '{"cmd":"stop"}' ``` To package an interactive run as a permanent repeatable scenario, copy the -generated `/tmp/scenario-live/action-log.json` array into a new file under -`devcapsule-src/tests/e2e/scenarios/.json`. +generated `tests/e2e/evidence//action-log.json` array into a new +file under `devcapsule-src/tests/e2e/scenarios/.json`. From bd2f4d1c9b6e9e0fc1307b6c8d148b72c5269096 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Sat, 14 Nov 2026 01:51:14 +0000 Subject: [PATCH 59/75] Add FastAPI + PostgreSQL + React E2E scenario and Spring Boot script Promote the recorded 56-step FastAPI + PostgreSQL 17 + React Todo E2E scenario, its plain-English source script, seed generator, and full-stack controller to tests/e2e/, alongside the prepared Java 25 + Spring Boot + PostgreSQL 17 scenario script and seed generator. Add unit tests for the new seed generators and step parser under tests/unit/tests/e2e/ and register both permanent script markdown files in index.md. Co-authored-by: Gemini 4 Carbon (Medium) Antigravity --- .../todo-fastapi-postgres-react.json | 300 +++++++++ .../e2e/scripts/springboot-postgres-java.md | 47 ++ .../scripts/todo-fastapi-postgres-react.md | 48 ++ devcapsule-src/tests/e2e/springboot_seed.py | 444 ++++++++++++++ .../tests/e2e/todo_demo_controller.py | 545 +++++++++++++++++ devcapsule-src/tests/e2e/todo_seed.py | 574 ++++++++++++++++++ .../tests/unit/tests/e2e/__init__.py | 0 .../unit/tests/e2e/test_springboot_seed.py | 21 + .../tests/e2e/test_todo_demo_controller.py | 39 ++ .../tests/unit/tests/e2e/test_todo_seed.py | 25 + index.md | 2 + 11 files changed, 2045 insertions(+) create mode 100644 devcapsule-src/tests/e2e/scenarios/todo-fastapi-postgres-react.json create mode 100644 devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md create mode 100644 devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md create mode 100644 devcapsule-src/tests/e2e/springboot_seed.py create mode 100644 devcapsule-src/tests/e2e/todo_demo_controller.py create mode 100644 devcapsule-src/tests/e2e/todo_seed.py create mode 100644 devcapsule-src/tests/unit/tests/e2e/__init__.py create mode 100644 devcapsule-src/tests/unit/tests/e2e/test_springboot_seed.py create mode 100644 devcapsule-src/tests/unit/tests/e2e/test_todo_demo_controller.py create mode 100644 devcapsule-src/tests/unit/tests/e2e/test_todo_seed.py diff --git a/devcapsule-src/tests/e2e/scenarios/todo-fastapi-postgres-react.json b/devcapsule-src/tests/e2e/scenarios/todo-fastapi-postgres-react.json new file mode 100644 index 00000000..6ee2f17b --- /dev/null +++ b/devcapsule-src/tests/e2e/scenarios/todo-fastapi-postgres-react.json @@ -0,0 +1,300 @@ +{ + "id": "todo-fastapi-postgres-react", + "surface": "codium", + "title": "DevCapsule Full-Stack Todo App: FastAPI + PostgreSQL 17 + React (IDE Coding + Live Browser)", + "description": "Open a full-stack FastAPI + PostgreSQL 17 + React Todo project in VSCodium, type the parameterized PostgreSQL INSERT endpoint and React fetch handler, start the stack from the integrated terminal, exercise the web UI in Chromium, and confirm durable rows in PostgreSQL.", + "script": "scripts/todo-fastapi-postgres-react.md", + "actions": [ + { + "action": "click", + "x": 1575, + "y": 86, + "reason": "1. Close empty secondary sidebar in VSCodium" + }, + { + "action": "click", + "x": 670, + "y": 50, + "reason": "1. Click Manage on Workspace Trust banner" + }, + { + "action": "click", + "x": 531, + "y": 645, + "reason": "1. Click Trust to enable full DevCapsule workspace features" + }, + { + "action": "wait", + "ms": 1000, + "reason": "1. Apply workspace zoom and editor settings" + }, + { + "action": "press", + "text": "Control+p", + "reason": "2. Open Quick Open dialog" + }, + { + "action": "wait", + "ms": 400, + "reason": "2. Focus Quick Open input" + }, + { + "action": "type", + "text": "backend/main.py", + "reason": "2. Filter to FastAPI backend/main.py" + }, + { + "action": "wait", + "ms": 300, + "reason": "2. Highlight backend/main.py" + }, + { + "action": "press", + "text": "Enter", + "reason": "2. Open backend/main.py" + }, + { + "action": "wait", + "ms": 600, + "reason": "2. Render Python syntax highlighting" + }, + { + "action": "press", + "text": "Control+g", + "reason": "2. Open Go to Line prompt" + }, + { + "action": "wait", + "ms": 300, + "reason": "2. Focus Go to Line input" + }, + { + "action": "type", + "text": "75", + "reason": "2. Target Line 75 inside create_todo" + }, + { + "action": "press", + "text": "Enter", + "reason": "2. Jump cursor to Line 75" + }, + { + "action": "type", + "text": " with psycopg.connect(DB_URL) as conn:\n row = conn.execute(\n 'INSERT INTO todos (title, category) VALUES (%s, %s) RETURNING id, title, category, completed',\n (payload.title.strip(), payload.category),\n ).fetchone()\n return {'id': row[0], 'title': row[1], 'category': row[2], 'completed': row[3]}\n\n", + "reason": "2. Type parameterized PostgreSQL INSERT in FastAPI create_todo" + }, + { + "action": "press", + "text": "Control+s", + "reason": "2. Save backend/main.py" + }, + { + "action": "wait", + "ms": 900, + "reason": "2. Hold on saved FastAPI + PostgreSQL endpoint" + }, + { + "action": "press", + "text": "Control+p", + "reason": "3. Open Quick Open for React frontend" + }, + { + "action": "wait", + "ms": 400, + "reason": "3. Focus Quick Open input" + }, + { + "action": "type", + "text": "frontend/src/App.jsx", + "reason": "3. Filter to frontend/src/App.jsx" + }, + { + "action": "wait", + "ms": 300, + "reason": "3. Highlight App.jsx" + }, + { + "action": "press", + "text": "Enter", + "reason": "3. Open frontend/src/App.jsx" + }, + { + "action": "wait", + "ms": 600, + "reason": "3. Render JSX syntax highlighting" + }, + { + "action": "press", + "text": "Control+g", + "reason": "3. Open Go to Line prompt" + }, + { + "action": "wait", + "ms": 300, + "reason": "3. Focus Go to Line input" + }, + { + "action": "type", + "text": "30", + "reason": "3. Target Line 30 inside handleCreate" + }, + { + "action": "press", + "text": "Enter", + "reason": "3. Jump cursor to Line 30" + }, + { + "action": "type", + "text": " const res = await fetch('/api/todos', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ title, category }),\n });\n const created = await res.json();\n setTodos((prev) => [...prev, created]);\n setTitle('');\n", + "reason": "3. Type fetch('/api/todos') POST request and React state update" + }, + { + "action": "press", + "text": "Control+s", + "reason": "3. Save frontend/src/App.jsx" + }, + { + "action": "wait", + "ms": 900, + "reason": "3. Hold on completed React handleCreate implementation" + }, + { + "action": "press", + "text": "Control+Backquote", + "reason": "4. Open VSCodium integrated terminal" + }, + { + "action": "wait", + "ms": 1400, + "reason": "4. Wait for shell prompt" + }, + { + "action": "type", + "text": "./run-stack.sh\n", + "reason": "4. Check PostgreSQL 17 via psql and start FastAPI + Vite" + }, + { + "action": "wait", + "ms": 3800, + "reason": "4. Display PostgreSQL 17 version, initial psql rows, and STACK_READY" + }, + { + "action": "launch_browser", + "text": "http://127.0.0.1:15173", + "reason": "5. Launch Chromium on capsule desktop showing CapsuleTask React UI" + }, + { + "action": "wait", + "ms": 2200, + "reason": "5. Show CapsuleTask initial load with 2 seeded PostgreSQL rows" + }, + { + "action": "click", + "x": 600, + "y": 256, + "reason": "6. Focus New task title input" + }, + { + "action": "type", + "text": "Record FastAPI + React customer pitch demo", + "reason": "6. Type first task title" + }, + { + "action": "click", + "x": 1163, + "y": 256, + "reason": "6. Click Add Task" + }, + { + "action": "wait", + "ms": 800, + "reason": "6. Show pg#3 added to task list" + }, + { + "action": "click", + "x": 600, + "y": 256, + "reason": "6. Focus New task title input for second task" + }, + { + "action": "type", + "text": "Verify PostgreSQL 17 persistence across reloads", + "reason": "6. Type second task title" + }, + { + "action": "press", + "text": "Tab", + "reason": "6. Focus Category selector" + }, + { + "action": "press", + "text": "ArrowDown", + "reason": "6. Select Database category" + }, + { + "action": "click", + "x": 1163, + "y": 256, + "reason": "6. Click Add Task" + }, + { + "action": "wait", + "ms": 800, + "reason": "6. Show pg#4 added with Database badge" + }, + { + "action": "click", + "x": 403, + "y": 381, + "reason": "6. Toggle completion checkbox on pg#1" + }, + { + "action": "wait", + "ms": 800, + "reason": "6. Show Completed counter increment to 2" + }, + { + "action": "click", + "x": 1165, + "y": 325, + "reason": "7. Click Refresh from DB button" + }, + { + "action": "wait", + "ms": 1000, + "reason": "7. Show Reloaded from PostgreSQL (4 rows)" + }, + { + "action": "click", + "x": 85, + "y": 986, + "reason": "7. Switch to VSCodium via tint2 taskbar to inspect database in terminal" + }, + { + "action": "wait", + "ms": 700, + "reason": "7. Focus VSCodium integrated terminal" + }, + { + "action": "type", + "text": "./query-db.sh\n", + "reason": "7. Query PostgreSQL todos table directly via psql" + }, + { + "action": "wait", + "ms": 1800, + "reason": "7. Hold on psql table showing all 4 persisted rows and completion flags" + }, + { + "action": "click", + "x": 245, + "y": 986, + "reason": "7. Return to CapsuleTask browser window for closing poster frame" + }, + { + "action": "wait", + "ms": 1400, + "reason": "7. Hold final frame on working FastAPI + PostgreSQL 17 + React app" + } + ] +} diff --git a/devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md b/devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md new file mode 100644 index 00000000..c17bcc0b --- /dev/null +++ b/devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md @@ -0,0 +1,47 @@ +# E2E Scenario Script: Java 25 + Spring Boot + PostgreSQL 17 In IntelliJ IDEA + +## Goal + +Demonstrate a Java backend and web UI workflow inside an isolated **DevCapsule** +container combining **IntelliJ IDEA** (`java-ide`), **OpenJDK 25** + **Maven** +(`java`), **PostgreSQL 17** client tools (`postgresql-client`), and **Chromium** +(`browser-automation`), recording human-paced Java coding in IntelliJ IDEA and +live browser verification against PostgreSQL 17. + +## Stack And Capabilities + +- **Scenario ID:** `springboot-postgres-java` +- **DevCapsule surface:** `intellij` (`java-ide`, `java`, `postgresql-client`, `browser-automation`) +- **Database:** PostgreSQL 17 (`sprintdb`, table `sprint_items`, `127.0.0.1:15432`) +- **Application server:** Spring Boot `3.4.5` (`21`) with fluent `JdbcClient` on `http://127.0.0.1:18085` +- **Recorded evidence path:** `devcapsule-src/tests/e2e/evidence/springboot-postgres-java/scenario-video.webm` + +## Steps + +1. **Open the Maven Spring Boot project in IntelliJ IDEA inside DevCapsule.** + - *User action:* Launch the project capsule, accept workspace trust if prompted, and display the `capsule-sprint` Maven project on the `1600×1000` capsule desktop. + - *Expected observation:* IntelliJ IDEA displays the indexed Maven project tree (`pom.xml`, `src/main/java/io/devcapsule/demo/SprintController.java`) with clean syntax highlighting. + +2. **Navigate to `SprintController.java` at `@PostMapping("/api/items")`.** + - *User action:* Open Go to File (`Ctrl+Shift+N`), filter to `SprintController.java`, press `Enter`, jump to line `38` (`Ctrl+G`), and delete the `NOT_IMPLEMENTED` placeholder line (`Ctrl+Y`). + - *Expected observation:* The editor focuses inside `createItem(@RequestBody CreateItemRequest req)` below the `// Live demo placeholder:` marker. + +3. **Type the parameterized PostgreSQL `INSERT ... RETURNING` query using `JdbcClient` and save.** + - *User action:* Type the fluent `jdbc.sql("INSERT INTO sprint_items ...")` implementation at human cadence and save (`Ctrl+S`). + - *Expected observation:* `SprintController.java` saves cleanly on disk with zero unresolved symbols or syntax errors. + +4. **Verify PostgreSQL 17 and start Spring Boot from IntelliJ's integrated terminal.** + - *User action:* Open IntelliJ's integrated Terminal (`Alt+F12`) and run `./run-stack.sh` to check PostgreSQL 17 via `psql`, compile offline (`mvn -o -q compile`), and start Spring Boot (`:18085`). + - *Expected observation:* The terminal prints the PostgreSQL 17 banner, the two seeded rows (`CAP-101`, `CAP-102`), and `STACK_READY: Spring Boot listening on http://127.0.0.1:18085`. + +5. **Open the CapsuleSprint web application in Chromium on the capsule desktop.** + - *User action:* Launch Chromium in `--app=http://127.0.0.1:18085` mode on the capsule X11 display. + - *Expected observation:* **CapsuleSprint** renders with `Java 25 · Spring Boot`, `PostgreSQL 17 · Connected`, metric cards (`Total: 2`, `Open: 0`, `Resolved: 2`), and `CAP-101` / `CAP-102`. + +6. **Create two new sprint items and toggle resolution state in the browser.** + - *User action:* Focus the item input, type `"Implement Spring Boot JdbcClient endpoint"`, click **Create Item** (`CAP-103`); type `"Verify PostgreSQL 17 transaction durability"`, click **Create Item** (`CAP-104`); then toggle `CAP-103` to resolved. + - *Expected observation:* `CAP-103` (resolved) and `CAP-104` (open) render immediately, updating the counters to `Total: 4`, `Open: 1`, `Resolved: 3`. + +7. **Reload from PostgreSQL and confirm durable rows via `psql` in IntelliJ's terminal.** + - *User action:* Click **Refresh from DB**, switch to IntelliJ's terminal to run `./query-db.sh`, and return to **CapsuleSprint** for the final poster frame. + - *Expected observation:* Both `psql` and the browser UI display all four rows (`CAP-101`..`CAP-104`) and their exact `resolved` booleans (`t, t, t, f`). diff --git a/devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md b/devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md new file mode 100644 index 00000000..8fdc3970 --- /dev/null +++ b/devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md @@ -0,0 +1,48 @@ +# E2E Scenario Script: FastAPI + PostgreSQL 17 + React Todo Application + +## Goal + +Demonstrate a full-stack web development session inside a single isolated +**DevCapsule** container combining **VSCodium** (`frontend-ide`), **Python 3.12** +(`FastAPI` + `psycopg`), **PostgreSQL 17** client tools (`psql`), **Node.js 22** +(`React` + `Vite`), and **Chromium** (`browser-automation`), recording both +human-paced code editing in the IDE and live interaction in the browser. + +## Stack And Capabilities + +- **Scenario ID:** `todo-fastapi-postgres-react` +- **DevCapsule surface:** `codium` (`frontend-ide`, `python`, `node`, `postgresql-client`, `browser-automation`) +- **Database:** PostgreSQL 17 (`tododb`, table `todos`, `127.0.0.1:15432`) +- **Backend:** Python FastAPI (`backend/main.py` on `http://127.0.0.1:18080`) +- **Frontend:** React + Vite (`frontend/src/App.jsx` on `http://127.0.0.1:15173`, proxying `/api` to `:18080`) +- **Recorded evidence path:** `devcapsule-src/tests/e2e/evidence/todo-fastapi-postgres-react/scenario-video.webm` + +## Steps + +1. **Open the workspace in VSCodium inside DevCapsule.** + - *User action:* Launch the project capsule, trust the workspace if prompted, and focus VSCodium showing `.devcapsule/`, `backend/`, and `frontend/`. + - *Expected observation:* VSCodium renders on the `1600×1000` capsule desktop with the workspace loaded. + +2. **Implement `POST /api/todos` in `backend/main.py`.** + - *User action:* Quick-open `backend/main.py` (`Ctrl+P`), jump to line `75` (`Ctrl+G`) inside `@app.post("/api/todos")`, type the parameterized `INSERT INTO todos (title, category) VALUES (%s, %s) RETURNING id, title, category, completed` query and JSON response, and save (`Ctrl+S`). + - *Expected observation:* `backend/main.py` shows the completed PostgreSQL insert handler with no unsaved indicator and compiles cleanly on disk. + +3. **Implement `handleCreate` in `frontend/src/App.jsx`.** + - *User action:* Quick-open `frontend/src/App.jsx` (`Ctrl+P`), jump to line `30` (`Ctrl+G`) inside `handleCreate`, type the `fetch('/api/todos', { method: 'POST', ... })` request and `setTodos` state update, and save (`Ctrl+S`). + - *Expected observation:* `frontend/src/App.jsx` shows the completed `fetch` call and state update saved on disk. + +4. **Verify PostgreSQL 17 and start FastAPI + Vite from VSCodium's integrated terminal.** + - *User action:* Open VSCodium's integrated terminal (`Ctrl+\``) and run `./run-stack.sh` to verify PostgreSQL 17 connectivity via `psql`, start Uvicorn (`:18080`), and start Vite (`:15173`). + - *Expected observation:* The terminal prints the PostgreSQL 17 banner, the initial seeded rows from `psql`, and `STACK_READY`. + +5. **Open the CapsuleTask React application in Chromium on the capsule desktop.** + - *User action:* Launch Chromium on the capsule X11 display pointing at `http://127.0.0.1:15173` alongside VSCodium. + - *Expected observation:* **CapsuleTask** renders with `PostgreSQL 17 Connected`, header counters, and the two initial seeded tasks (`pg#1`, `pg#2`). + +6. **Create two new tasks and toggle completion in the browser.** + - *User action:* Click the task input box, type `"Record FastAPI + React customer pitch demo"`, click **Add Task** (`pg#3`); then type `"Verify PostgreSQL 17 persistence across reloads"`, select category `"Database"`, click **Add Task** (`pg#4`); then click the completion checkbox on `pg#1`. + - *Expected observation:* Both new tasks appear immediately with PostgreSQL IDs `pg#3` and `pg#4`, and the header counters update to `Total: 4`, `Done: 2`. + +7. **Reload from PostgreSQL and confirm durable database state via `psql`.** + - *User action:* Click **Refresh from DB** in the React UI, switch back to VSCodium's terminal to run `./query-db.sh`, and return to **CapsuleTask** for the final poster frame. + - *Expected observation:* Both `psql` and the browser UI show all four persisted rows (`1`..`4`) and their completion flags (`t, t, f, f`). diff --git a/devcapsule-src/tests/e2e/springboot_seed.py b/devcapsule-src/tests/e2e/springboot_seed.py new file mode 100644 index 00000000..83e6b609 --- /dev/null +++ b/devcapsule-src/tests/e2e/springboot_seed.py @@ -0,0 +1,444 @@ +"""Seed generator for the Java + Spring Boot + PostgreSQL 17 customer pitch E2E scenario. + +Generates a Maven Spring Boot 3.4.5 project ('CapsuleSprint') configured with +21 so it compiles and runs +cleanly under OpenJDK 25 inside DevCapsule, using Spring's fluent JdbcClient +against PostgreSQL 17 and serving an interactive single-page web UI. +""" + +from __future__ import annotations + +import json +import stat +import sys +from pathlib import Path + +__all__ = [ + "POM_XML", + "SPRINT_CONTROLLER_JAVA", + "TYPED_JAVA_SNIPPET", + "materialize", +] + +POM_XML = """ + + 4.0.0 + + org.springframework.boot + spring-boot-starter-parent + 3.4.5 + + + + io.devcapsule.demo + capsule-sprint + 0.1.0 + CapsuleSprint + DevCapsule Spring Boot + PostgreSQL 17 Customer Pitch Demo + + + 21 + UTF-8 + + + + + org.springframework.boot + spring-boot-starter-web + + + org.springframework.boot + spring-boot-starter-jdbc + + + org.postgresql + postgresql + runtime + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +""" + +MAVEN_CONFIG = "-Dmaven.repo.local=.m2/repository\n" + +APPLICATION_PROPERTIES = """server.port=${APP_PORT:18085} +spring.application.name=capsule-sprint +spring.datasource.url=${SPRING_DATASOURCE_URL:jdbc:postgresql://127.0.0.1:15432/sprintdb} +spring.datasource.username=${SPRING_DATASOURCE_USERNAME:postgres} +spring.datasource.password=${SPRING_DATASOURCE_PASSWORD:postgres} +spring.sql.init.mode=always +logging.level.root=WARN +logging.level.io.devcapsule.demo=INFO +logging.level.org.springframework.boot.web.embedded.tomcat=INFO +""" + +SCHEMA_SQL = """CREATE TABLE IF NOT EXISTS sprint_items ( + id SERIAL PRIMARY KEY, + code VARCHAR(24) NOT NULL, + title TEXT NOT NULL, + service VARCHAR(48) NOT NULL DEFAULT 'Core API', + resolved BOOLEAN NOT NULL DEFAULT FALSE +); +""" + +APPLICATION_JAVA = """package io.devcapsule.demo; + +import org.springframework.boot.CommandLineRunner; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; +import org.springframework.context.annotation.Bean; +import org.springframework.jdbc.core.simple.JdbcClient; + +@SpringBootApplication +public class CapsuleSprintApplication { + + public static void main(String[] args) { + SpringApplication.run(CapsuleSprintApplication.class, args); + } + + @Bean + CommandLineRunner seedDatabase(JdbcClient jdbc) { + return args -> { + Long count = jdbc.sql("SELECT COUNT(*) FROM sprint_items") + .query(Long.class) + .single(); + if (count == 0) { + jdbc.sql("INSERT INTO sprint_items (code, title, service, resolved) VALUES " + + "('CAP-101', 'Bootstrap isolated IntelliJ + Java 25 capsule', 'Platform', true), " + + "('CAP-102', 'Wire HikariCP pool to PostgreSQL 17', 'Database', true)") + .update(); + } + }; + } +} +""" + +SPRINT_ITEM_JAVA = """package io.devcapsule.demo; + +public record SprintItem( + Long id, + String code, + String title, + String service, + boolean resolved +) {} +""" + +CREATE_ITEM_REQUEST_JAVA = """package io.devcapsule.demo; + +public record CreateItemRequest( + String title, + String service +) {} +""" + +RESOLVE_REQUEST_JAVA = """package io.devcapsule.demo; + +public record ResolveRequest( + boolean resolved +) {} +""" + +# Note: createItem (@PostMapping("/api/items")) is intentionally left with a single +# placeholder line at line 45 so IntelliJ IDEA live-types the JdbcClient INSERT ... RETURNING +# implementation during the recorded demo! +SPRINT_CONTROLLER_JAVA = """package io.devcapsule.demo; + +import java.util.List; +import java.util.Map; +import org.springframework.http.HttpStatus; +import org.springframework.jdbc.core.simple.JdbcClient; +import org.springframework.web.bind.annotation.*; +import org.springframework.web.server.ResponseStatusException; + +@RestController +public class SprintController { + + private final JdbcClient jdbc; + + public SprintController(JdbcClient jdbc) { + this.jdbc = jdbc; + } + + @GetMapping("/api/health") + public Map health() { + String pgVersion = jdbc.sql("SHOW server_version").query(String.class).single(); + Long total = jdbc.sql("SELECT COUNT(*) FROM sprint_items").query(Long.class).single(); + return Map.of("ok", true, "postgres", pgVersion, "java", Runtime.version().toString(), "items", total); + } + + @GetMapping("/api/items") + public List listItems() { + return jdbc.sql("SELECT id, code, title, service, resolved FROM sprint_items ORDER BY id ASC") + .query(SprintItem.class) + .list(); + } + + @PostMapping("/api/items") + @ResponseStatus(HttpStatus.CREATED) + public SprintItem createItem(@RequestBody CreateItemRequest req) { + String nextCode = "CAP-" + (101 + jdbc.sql("SELECT COUNT(*) FROM sprint_items").query(Long.class).single()); + // Live IDE demo: insert sprint item into PostgreSQL and return mapped record + throw new ResponseStatusException(HttpStatus.NOT_IMPLEMENTED, "Live demo placeholder"); + } + + @PatchMapping("/api/items/{id}") + public SprintItem toggleResolved(@PathVariable Long id, @RequestBody ResolveRequest patch) { + return jdbc.sql("UPDATE sprint_items SET resolved = :resolved WHERE id = :id " + + "RETURNING id, code, title, service, resolved") + .param("resolved", patch.resolved()) + .param("id", id) + .query(SprintItem.class) + .optional() + .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Item not found")); + } +} +""" + +TYPED_JAVA_SNIPPET = """ return jdbc.sql("INSERT INTO sprint_items (code, title, service) VALUES (:code, :title, :svc) RETURNING id, code, title, service, resolved") + .param("code", nextCode) + .param("title", req.title().trim()) + .param("svc", req.service()) + .query(SprintItem.class) + .single(); +""" + +INDEX_HTML = """ + + + + + CapsuleSprint — Spring Boot + PostgreSQL 17 + + + +
+
+
+

CapsuleSprint

+
DevCapsule Enterprise Java Workspace · Spring Boot 3.4 + JdbcClient + PostgreSQL 17
+
+
+
Java · Loading
+
PostgreSQL · Connecting
+
+
+ +
+
Total Sprint Items
0
+
Open
0
+
Resolved
0
+
+ +
+ + + +
+ +
+ Persisted Sprint Backlog + +
+ +
+
+ + + + +""" + +RUN_STACK_SH = """#!/usr/bin/env bash +set -euo pipefail +export LC_ALL=C.UTF-8 LANG=C.UTF-8 +export PGPASSWORD="${SPRING_DATASOURCE_PASSWORD:-postgres}" + +echo "==> Checking PostgreSQL 17 connection via psql..." +psql -h 127.0.0.1 -p 15432 -U postgres -d sprintdb -c "SELECT version();" -t | head -n 1 + +echo "==> Compiling & starting Spring Boot 3.4 (offline Maven cache)..." +mvn -o -q compile +nohup mvn -o -q spring-boot:run > /tmp/springboot.log 2>&1 & + +for _ in $(seq 1 40); do + if curl -fsS http://127.0.0.1:18085/api/health >/dev/null 2>&1; then + break + fi + sleep 0.5 +done + +echo "==> Seeded rows in sprint_items:" +psql -h 127.0.0.1 -p 15432 -U postgres -d sprintdb -c "SELECT id, code, service, resolved, title FROM sprint_items ORDER BY id;" +echo "STACK_READY: Spring Boot listening on http://127.0.0.1:18085" +""" + +QUERY_DB_SH = """#!/usr/bin/env bash +set -euo pipefail +export LC_ALL=C.UTF-8 LANG=C.UTF-8 +export PGPASSWORD="${SPRING_DATASOURCE_PASSWORD:-postgres}" +psql -h 127.0.0.1 -p 15432 -U postgres -d sprintdb -c "SELECT id, code, service, resolved, title FROM sprint_items ORDER BY id;" +""" + + +def materialize(workspace: Path) -> dict[str, object]: + workspace.mkdir(parents=True, exist_ok=True) + (workspace / ".mvn").mkdir(parents=True, exist_ok=True) + (workspace / ".mvn" / "maven.config").write_text(MAVEN_CONFIG, encoding="utf-8") + (workspace / "pom.xml").write_text(POM_XML, encoding="utf-8") + + java_dir = workspace / "src" / "main" / "java" / "io" / "devcapsule" / "demo" + java_dir.mkdir(parents=True, exist_ok=True) + (java_dir / "CapsuleSprintApplication.java").write_text(APPLICATION_JAVA, encoding="utf-8") + (java_dir / "SprintItem.java").write_text(SPRINT_ITEM_JAVA, encoding="utf-8") + (java_dir / "CreateItemRequest.java").write_text(CREATE_ITEM_REQUEST_JAVA, encoding="utf-8") + (java_dir / "ResolveRequest.java").write_text(RESOLVE_REQUEST_JAVA, encoding="utf-8") + controller_path = java_dir / "SprintController.java" + controller_path.write_text(SPRINT_CONTROLLER_JAVA, encoding="utf-8") + + res_dir = workspace / "src" / "main" / "resources" + static_dir = res_dir / "static" + static_dir.mkdir(parents=True, exist_ok=True) + (res_dir / "application.properties").write_text(APPLICATION_PROPERTIES, encoding="utf-8") + (res_dir / "schema.sql").write_text(SCHEMA_SQL, encoding="utf-8") + (static_dir / "index.html").write_text(INDEX_HTML, encoding="utf-8") + + for name, body in (("run-stack.sh", RUN_STACK_SH), ("query-db.sh", QUERY_DB_SH)): + script = workspace / name + script.write_text(body, encoding="utf-8") + script.chmod(script.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) + + lines = SPRINT_CONTROLLER_JAVA.splitlines() + placeholder_line = next( + idx for idx, line in enumerate(lines, 1) if "Live demo placeholder" in line + ) + return { + "workspace": str(workspace), + "controller_file": "src/main/java/io/devcapsule/demo/SprintController.java", + "controller_placeholder_line": placeholder_line, + "typed_java_lines": len(TYPED_JAVA_SNIPPET.splitlines()), + } + + +if __name__ == "__main__": + target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("/tmp/springboot-seed-check") + print(json.dumps(materialize(target), indent=2)) diff --git a/devcapsule-src/tests/e2e/todo_demo_controller.py b/devcapsule-src/tests/e2e/todo_demo_controller.py new file mode 100644 index 00000000..87769e73 --- /dev/null +++ b/devcapsule-src/tests/e2e/todo_demo_controller.py @@ -0,0 +1,545 @@ +"""Interactive controller and deterministic replayer for the FastAPI + PostgreSQL + React Todo scenario. + +Builds on ``tests.e2e.ide_session``, ``tests.e2e.browser_session``, and +``tests.e2e.scenario_recorder``, adding disposable PostgreSQL 17 orchestration, +offline/pre-recording dependency installation, cursor overlay visualization, +and outside-in HTTP + ``psql`` postcondition verification. +""" +from __future__ import annotations + +import argparse +from contextlib import contextmanager +from dataclasses import asdict, dataclass +import json +import os +from pathlib import Path +import shutil +import subprocess +import tempfile +import time +from typing import Any, Iterator +import urllib.request + +from tests.e2e.browser_session import smoke_browser +from tests.e2e.ide_session import ( + IdeSurface, + SessionFacts, + command, + desktop_page_answers, + initialize_project, + launched_ide, + remove_project_records, + top_level_windows, + wait_for_ide_window, + workspace_root, +) +from tests.e2e.scenario_recorder import ( + EVIDENCE_DIR, + SCENARIOS_DIR, + BurstFrameRecorder, + ControllerQueue, + send_controller_command, + start_controller_server, + write_json_atomically, +) +from tests.e2e.todo_seed import ( + API_PORT, + DB_URL, + PG_PORT, + VITE_PORT, + write_seed_project, +) + +__all__ = [ + "DEMO_SCENARIO_ID", + "DEMO_SURFACE", + "DemoStep", + "apply_demo_step", + "main", + "replay_mode", + "serve_mode", +] + +DEMO_SCENARIO_ID = "todo-fastapi-postgres-react" + +DEMO_SURFACE = IdeSurface( + name="codium", + needs=("frontend-ide", "python", "node", "postgresql-client", "browser-automation"), + window_class="codium", + ready_timeout=240.0, +) + +CURSOR_OVERLAY_JS = """ +(() => { + const install = () => { + if (document.getElementById('__pitch_cursor')) return; + const dot = document.createElement('div'); + dot.id = '__pitch_cursor'; + dot.style.cssText = + 'position:fixed;left:-40px;top:-40px;width:20px;height:20px;' + + 'margin:-10px 0 0 -10px;border-radius:50%;' + + 'background:rgba(59,130,246,0.45);border:2px solid #ffffff;' + + 'box-shadow:0 0 0 2px rgba(15,23,42,0.65), 0 0 12px rgba(59,130,246,0.8);' + + 'pointer-events:none;z-index:2147483647;transition:transform 0.08s ease;'; + document.documentElement.appendChild(dot); + window.addEventListener('mousemove', (e) => { + dot.style.left = e.clientX + 'px'; + dot.style.top = e.clientY + 'px'; + }, true); + window.addEventListener('mousedown', () => { + dot.style.transform = 'scale(1.65)'; + dot.style.background = 'rgba(16,185,129,0.65)'; + }, true); + window.addEventListener('mouseup', () => { + dot.style.transform = 'scale(1)'; + dot.style.background = 'rgba(59,130,246,0.45)'; + }, true); + }; + if (document.documentElement) install(); + window.addEventListener('DOMContentLoaded', install); +})(); +""" + + +@dataclass(frozen=True) +class DemoStep: + """One mouse, keyboard, bounded wait, or capsule browser launch step.""" + + action: str + x: int = 0 + y: int = 0 + text: str = "" + ms: int = 0 + reason: str = "" + + @classmethod + def parse(cls, raw: dict[str, Any]) -> DemoStep: + valid = ("click", "double_click", "right_click", "type", "press", "wait", "launch_browser") + action = str(raw.get("action", "")) + if action not in valid: + raise ValueError(f"Unsupported DemoStep action: {action!r}") + x = raw.get("x", 0) + y = raw.get("y", 0) + ms = raw.get("ms", 0) + if type(x) is not int or not (0 <= x <= 1599): + raise ValueError(f"Invalid DemoStep x coordinate: {x!r}") + if type(y) is not int or not (0 <= y <= 999): + raise ValueError(f"Invalid DemoStep y coordinate: {y!r}") + if type(ms) is not int or ms < 0: + raise ValueError(f"Invalid DemoStep ms: {ms!r}") + text = str(raw.get("text", "")) + if action in ("type", "press", "launch_browser") and not text: + raise ValueError(f"DemoStep action {action!r} requires non-empty text") + return cls( + action=action, + x=x, + y=y, + text=text, + ms=ms, + reason=str(raw.get("reason", "")), + ) + + +@contextmanager +def _postgres_container(run_id: str) -> Iterator[str]: + """Run disposable PostgreSQL 17 container bound to ``127.0.0.1:PG_PORT``.""" + name = f"devcapsule-pitch-pg-{run_id}" + command("docker", "rm", "-f", name, check=False) + command( + "docker", "run", "-d", "--rm", + "--name", name, + "-p", f"127.0.0.1:{PG_PORT}:5432", + "-e", "POSTGRES_USER=devcapsule", + "-e", "POSTGRES_PASSWORD=devcapsule", + "-e", "POSTGRES_DB=tododb", + "postgres:17-alpine", + timeout=60.0, + ) + try: + deadline = time.monotonic() + 30.0 + while True: + probe = command( + "docker", "exec", name, + "pg_isready", "-U", "devcapsule", "-d", "tododb", + check=False, timeout=10.0, + ) + if probe.returncode == 0: + break + if time.monotonic() > deadline: + raise RuntimeError(f"PostgreSQL did not become ready: {probe.stdout} {probe.stderr}") + time.sleep(0.4) + yield name + finally: + command("docker", "rm", "-f", name, check=False, timeout=30.0) + + +def _bootstrap_capsule_deps(container: str, project_path: str, evidence: Path) -> None: + """Install FastAPI/psycopg venv and Vite/React packages inside the capsule before recording.""" + script = f""" +set -euo pipefail +cd "{project_path}" +python3 -m venv backend/.venv +backend/.venv/bin/pip install -q fastapi uvicorn "psycopg[binary]" +npm --prefix frontend install --no-audit --no-fund --loglevel=error +""" + res = subprocess.run( + ["docker", "exec", "--user", f"{os.getuid()}:{os.getgid()}", container, "bash", "-lc", script], + capture_output=True, text=True, check=False, timeout=300.0, + ) + (evidence / "bootstrap-deps.log").write_text(res.stdout + res.stderr, encoding="utf-8") + if res.returncode != 0: + raise RuntimeError(f"Dependency bootstrap failed:\n{res.stdout}\n{res.stderr}") + + +def _launch_capsule_browser(container: str, url: str) -> None: + """Launch headed Chromium on the child capsule's X11 display positioned alongside VSCodium.""" + script = f""" +set -euo pipefail +DISP_NUM=$(ls /tmp/.X11-unix | sort | head -n 1 | cut -c2-) +XAUTH=$(ls /tmp/devcapsule-runtime-*/display/Xauthority | sort | head -n 1) +CHROME=$(ls /opt/playwright/browsers/chromium-*/chrome-linux*/chrome | sort | tail -n 1) +export DISPLAY=":$DISP_NUM" +export XAUTHORITY="$XAUTH" +nohup "$CHROME" \\ + --no-sandbox \\ + --disable-dev-shm-usage \\ + --disable-gpu \\ + --no-first-run \\ + --no-default-browser-check \\ + --disable-infobars \\ + --user-data-dir=/tmp/pitch-chrome-profile \\ + --window-position=470,46 \\ + --window-size=1105,910 \\ + --app="{url}" /tmp/pitch-chrome.log 2>&1 & +""" + res = subprocess.run( + ["docker", "exec", "-d", "--user", f"{os.getuid()}:{os.getgid()}", container, "bash", "-lc", script], + capture_output=True, text=True, check=False, timeout=30.0, + ) + if res.returncode != 0: + raise RuntimeError(f"Failed to launch browser in capsule: {res.stdout}\n{res.stderr}") + + +def apply_demo_step(page: Any, recorder: BurstFrameRecorder, container: str, step: DemoStep) -> None: + """Execute one ``DemoStep`` while capturing smooth burst frames.""" + kind = step.action + if kind in ("click", "double_click", "right_click"): + page.mouse.move(step.x, step.y, steps=8) + recorder.record_frames(page, count=2, interval_ms=55) + if kind == "click": + page.mouse.click(step.x, step.y) + recorder.record_frames(page, count=5, interval_ms=110) + elif kind == "double_click": + page.mouse.dblclick(step.x, step.y) + recorder.record_frames(page, count=6, interval_ms=110) + else: + page.mouse.click(step.x, step.y, button="right") + recorder.record_frames(page, count=5, interval_ms=110) + elif kind == "type": + parts = step.text.split("\n") + for idx, line in enumerate(parts): + if line: + chunk = max(4, len(line) // 5) + for start in range(0, len(line), chunk): + page.keyboard.type(line[start : start + chunk], delay=18) + recorder.record_frames(page, count=1, interval_ms=35) + if idx < len(parts) - 1: + page.keyboard.press("Enter") + recorder.record_frames(page, count=1, interval_ms=45) + recorder.record_frames(page, count=4, interval_ms=100) + elif kind == "press": + page.keyboard.press(step.text) + recorder.record_frames(page, count=5, interval_ms=110) + elif kind == "wait": + slices = max(1, step.ms // 150) + recorded = min(slices, 24) + recorder.record_frames(page, count=recorded, interval_ms=150) + rem = step.ms - recorded * 150 + if rem > 0: + page.wait_for_timeout(rem) + elif kind == "launch_browser": + url = step.text or f"http://127.0.0.1:{VITE_PORT}" + _launch_capsule_browser(container, url) + recorder.record_frames(page, count=16, interval_ms=160) + + +@contextmanager +def _demo_environment(executable: Path, evidence: Path) -> Iterator[tuple[SessionFacts, dict[str, int], str]]: + """Bring up PostgreSQL 17 and a disposable DevCapsule with VSCodium, Python, Node, psql, and Playwright.""" + run_id = f"{int(time.time()) % 100000:05d}" + slug = f"pitch-todo-{run_id}" + container = f"devcapsule-{slug}" + evidence.mkdir(parents=True, exist_ok=True) + os.environ["DEVCAPSULE_SMOKE_COMPONENT_BROWSER"] = "1" + + with tempfile.TemporaryDirectory() as tmp_str: + workspace = workspace_root(Path(tmp_str)) / slug + shutil.rmtree(workspace, ignore_errors=True) + workspace.mkdir(parents=True) + try: + with _postgres_container(run_id) as pg_name: + initialize_project(executable, DEMO_SURFACE, workspace, evidence, slug) + edit_info = write_seed_project(workspace) + with launched_ide(executable, DEMO_SURFACE, workspace, evidence, container) as session: + assert desktop_page_answers(session.desktop_url) == 200 + wait_for_ide_window(session) + _bootstrap_capsule_deps( + session.container, + session.project_path or str(session.workspace), + evidence, + ) + yield session, edit_info, pg_name + finally: + shutil.rmtree(workspace, ignore_errors=True) + remove_project_records(slug) + + +def _verify_outside_postconditions(pg_container: str) -> dict[str, Any]: + """Independently verify FastAPI HTTP responses and PostgreSQL 17 rows from outside.""" + with urllib.request.urlopen(f"http://127.0.0.1:{API_PORT}/api/todos", timeout=10) as resp: + api_todos = json.loads(resp.read().decode("utf-8")) + sql = command( + "docker", "exec", pg_container, + "psql", "-U", "devcapsule", "-d", "tododb", "-t", "-A", "-F", "|", + "-c", "SELECT id, category, completed, title FROM todos ORDER BY id ASC;", + timeout=15.0, + ).stdout.strip().splitlines() + return {"api_todos": api_todos, "psql_rows": sql} + + +def serve_mode(executable: Path, evidence: Path) -> int: + """Start interactive discovery controller for the FastAPI + PostgreSQL + React Todo scenario.""" + from playwright.sync_api import sync_playwright # type: ignore[import-not-found,unused-ignore] + + evidence.mkdir(parents=True, exist_ok=True) + (evidence / "controller.json").unlink(missing_ok=True) + recorder = BurstFrameRecorder(evidence / "video-frames") + action_log: list[dict[str, Any]] = [] + step_counter = 0 + + with _demo_environment(executable, evidence) as (session, edit_info, pg_name): + with sync_playwright() as pw, smoke_browser(pw, session, evidence) as browser: + viewport = {"width": 1600, "height": 1000} + context = browser.new_context( + viewport=viewport, + record_video_dir=str(evidence), + record_video_size=viewport, + ) + context.add_init_script(CURSOR_OVERLAY_JS) + page = context.new_page() + video = page.video + page.goto(session.desktop_url, wait_until="load") + page.locator("canvas").first.wait_for(state="visible", timeout=60_000) + page.wait_for_timeout(3500) + recorder.record_frames(page, count=8, interval_ms=120) + + queue = ControllerQueue() + server = start_controller_server(queue) + info = { + "port": server.server_address[1], + "container": session.container, + "pg_container": pg_name, + "workspace": str(session.workspace), + "project_path": session.project_path, + "edit_lines": edit_info, + "db_url": DB_URL, + "api_port": API_PORT, + "vite_port": VITE_PORT, + } + write_json_atomically(evidence / "controller.json", info) + print(f"CONTROLLER_READY port={info['port']} container={session.container}", flush=True) + + stopped = False + verification: dict[str, Any] = {} + try: + while not stopped: + item = queue.take() + if item is None: + time.sleep(0.05) + continue + payload, done, response = item + try: + cmd = payload.get("cmd", "screenshot") + if cmd == "screenshot": + step_counter += 1 + shot = evidence / f"step-{step_counter:03d}.png" + page.screenshot(path=str(shot)) + response.update( + ok=True, + screenshot=str(shot), + windows=top_level_windows(session.container), + frames_recorded=recorder.frame_count, + ) + elif cmd == "act": + for raw in payload.get("actions", []): + step = DemoStep.parse(raw) + apply_demo_step(page, recorder, session.container, step) + action_log.append(asdict(step)) + step_counter += 1 + shot = evidence / f"step-{step_counter:03d}.png" + page.screenshot(path=str(shot)) + response.update( + ok=True, + screenshot=str(shot), + windows=top_level_windows(session.container), + frames_recorded=recorder.frame_count, + ) + elif cmd == "exec": + proc = subprocess.run( + [ + "docker", "exec", + "--user", f"{os.getuid()}:{os.getgid()}", + session.container, + "bash", "-lc", str(payload.get("shell", "true")), + ], + capture_output=True, text=True, check=False, timeout=60.0, + ) + response.update( + ok=(proc.returncode == 0), + returncode=proc.returncode, + stdout=proc.stdout, + stderr=proc.stderr, + ) + elif cmd == "verify": + verification = _verify_outside_postconditions(pg_name) + response.update(ok=True, **verification) + elif cmd == "stop": + try: + verification = _verify_outside_postconditions(pg_name) + except Exception as ver_exc: + verification = {"verify_error": str(ver_exc)} + step_counter += 1 + final_shot = evidence / f"step-{step_counter:03d}.png" + page.screenshot(path=str(final_shot)) + shutil.copyfile(final_shot, evidence / "poster.png") + recorder.record_frames(page, count=14, interval_ms=120) + encoded = recorder.encode_webm( + page, + evidence / "scenario-video.webm", + container=session.container, + ) + response.update( + ok=True, + stopping=True, + frames_recorded=recorder.frame_count, + pause_free_webm=encoded, + verification=verification, + ) + stopped = True + else: + response.update(ok=False, error=f"Unknown cmd: {cmd!r}") + except Exception as exc: + response.update(ok=False, error=str(exc)) + finally: + done.set() + finally: + server.shutdown() + server.server_close() + (evidence / "action-log.json").write_text( + json.dumps(action_log, indent=2) + "\n", encoding="utf-8" + ) + (evidence / "verification.json").write_text( + json.dumps(verification, indent=2) + "\n", encoding="utf-8" + ) + context.close() + if video is not None: + video.save_as(str(evidence / "agent-desktop-raw.webm")) + video.delete() + return 0 + + +def replay_mode(executable: Path, scenario_file: Path, evidence: Path) -> int: + """Deterministically replay a saved scenario JSON with zero LLM calls and assert PostgreSQL state.""" + from playwright.sync_api import sync_playwright # type: ignore[import-not-found,unused-ignore] + + spec = json.loads(scenario_file.read_text(encoding="utf-8")) + steps = [DemoStep.parse(item) for item in spec["actions"]] + recorder = BurstFrameRecorder(evidence / "video-frames") + shots: list[str] = [] + + with _demo_environment(executable, evidence) as (session, _, pg_name): + with sync_playwright() as pw, smoke_browser(pw, session, evidence) as browser: + viewport = {"width": 1600, "height": 1000} + context = browser.new_context( + viewport=viewport, + record_video_dir=str(evidence), + record_video_size=viewport, + ) + context.add_init_script(CURSOR_OVERLAY_JS) + page = context.new_page() + video = page.video + try: + page.goto(session.desktop_url, wait_until="load") + page.locator("canvas").first.wait_for(state="visible", timeout=60_000) + page.wait_for_timeout(3500) + recorder.record_frames(page, count=8, interval_ms=120) + + for idx, step in enumerate(steps, start=1): + apply_demo_step(page, recorder, session.container, step) + shot = evidence / f"step-{idx:03d}.png" + page.screenshot(path=str(shot)) + shots.append(shot.name) + + if shots: + shutil.copyfile(evidence / shots[-1], evidence / "poster.png") + recorder.record_frames(page, count=14, interval_ms=120) + encoded = recorder.encode_webm( + page, + evidence / "scenario-video.webm", + container=session.container, + ) + verification = _verify_outside_postconditions(pg_name) + finally: + context.close() + if video is not None: + video.save_as(str(evidence / "agent-desktop-raw.webm")) + video.delete() + + todos = verification.get("api_todos", []) + passed = encoded and len(todos) >= 4 and any(t.get("completed") for t in todos) + result = { + "scenario_id": spec.get("id"), + "status": "passed" if passed else "failed", + "steps_executed": len(steps), + "frames_recorded": recorder.frame_count, + "pause_free_webm": "scenario-video.webm" if encoded else None, + "todos_verified": todos, + "psql_rows": verification.get("psql_rows", []), + } + (evidence / "scenario-result.json").write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8") + print(json.dumps(result, indent=2)) + return 0 if passed else 1 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(prog="python -m tests.e2e.todo_demo_controller") + sub = parser.add_subparsers(dest="cmd", required=True) + + default_evidence = EVIDENCE_DIR / DEMO_SCENARIO_ID + default_scenario = SCENARIOS_DIR / f"{DEMO_SCENARIO_ID}.json" + + s_p = sub.add_parser("serve") + s_p.add_argument("--pex", type=Path, required=True) + s_p.add_argument("--evidence", type=Path, default=default_evidence) + + c_p = sub.add_parser("ctl") + c_p.add_argument("--evidence", type=Path, default=default_evidence) + c_p.add_argument("payload", nargs="?", default='{"cmd":"screenshot"}') + + r_p = sub.add_parser("replay") + r_p.add_argument("--pex", type=Path, required=True) + r_p.add_argument("--scenario", type=Path, default=default_scenario) + r_p.add_argument("--evidence", type=Path, default=default_evidence) + + args = parser.parse_args(argv) + if args.cmd == "serve": + return serve_mode(args.pex, args.evidence) + if args.cmd == "ctl": + res = send_controller_command(args.evidence, json.loads(args.payload), timeout=300.0) + print(json.dumps(res, indent=2)) + return 0 if res.get("ok") else 1 + return replay_mode(args.pex, args.scenario, args.evidence) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/devcapsule-src/tests/e2e/todo_seed.py b/devcapsule-src/tests/e2e/todo_seed.py new file mode 100644 index 00000000..fcd4a501 --- /dev/null +++ b/devcapsule-src/tests/e2e/todo_seed.py @@ -0,0 +1,574 @@ +"""Seed files and typed code snippets for the FastAPI + PostgreSQL + React Todo capsule demo.""" +from __future__ import annotations + +import json +from pathlib import Path + +__all__ = [ + "API_PORT", + "BACKEND_TYPED_SNIPPET", + "DB_URL", + "PG_PORT", + "VITE_PORT", + "write_seed_project", +] + +PG_PORT = 15432 +API_PORT = 18080 +VITE_PORT = 15173 +DB_URL = f"postgresql://devcapsule:devcapsule@127.0.0.1:{PG_PORT}/tododb" + +VSCODE_SETTINGS = { + "workbench.colorTheme": "Default Dark Modern", + "workbench.startupEditor": "none", + "workbench.tips.enabled": False, + "workbench.welcomePage.walkthroughs.openOnInstall": False, + "security.workspace.trust.enabled": False, + "telemetry.telemetryLevel": "off", + "update.mode": "none", + "extensions.ignoreRecommendations": True, + "window.zoomLevel": 0.5, + "editor.fontSize": 15, + "terminal.integrated.fontSize": 14, + "editor.minimap.enabled": False, + "editor.autoIndent": "none", + "editor.autoClosingBrackets": "never", + "editor.autoClosingQuotes": "never", + "editor.autoSurround": "never", + "editor.quickSuggestions": { + "other": "off", + "comments": "off", + "strings": "off", + }, + "editor.suggestOnTriggerCharacters": False, + "editor.acceptSuggestionOnEnter": "off", + "editor.parameterHints.enabled": False, + "editor.hover.enabled": False, +} + +BACKEND_MAIN_INITIAL = f'''"""FastAPI + PostgreSQL 17 backend for the CapsuleTask Todo application.""" +from __future__ import annotations + +from contextlib import asynccontextmanager +import os +from typing import AsyncIterator + +from fastapi import FastAPI, HTTPException +from pydantic import BaseModel +import psycopg + +DB_URL = os.environ.get("DATABASE_URL", "{DB_URL}") + + +class TodoCreate(BaseModel): + title: str + category: str = "Engineering" + + +class TodoPatch(BaseModel): + completed: bool + + +@asynccontextmanager +async def lifespan(_: FastAPI) -> AsyncIterator[None]: + with psycopg.connect(DB_URL) as conn: + conn.execute( + """ + CREATE TABLE IF NOT EXISTS todos ( + id SERIAL PRIMARY KEY, + title TEXT NOT NULL, + category TEXT NOT NULL DEFAULT 'Engineering', + completed BOOLEAN NOT NULL DEFAULT FALSE + ) + """ + ) + count = conn.execute("SELECT COUNT(*) FROM todos").fetchone()[0] + if count == 0: + conn.cursor().executemany( + "INSERT INTO todos (title, category, completed) VALUES (%s, %s, %s)", + [ + ("Provision isolated DevCapsule workspace", "Platform", False), + ("Connect FastAPI service to PostgreSQL 17", "Database", True), + ], + ) + yield + + +app = FastAPI(title="CapsuleTask API", lifespan=lifespan) + + +@app.get("/api/health") +def health() -> dict[str, object]: + with psycopg.connect(DB_URL) as conn: + pg_ver = conn.execute("SHOW server_version").fetchone()[0] + total = conn.execute("SELECT COUNT(*) FROM todos").fetchone()[0] + return {{"ok": True, "postgres": pg_ver, "todos": total}} + + +@app.get("/api/todos") +def list_todos() -> list[dict[str, object]]: + with psycopg.connect(DB_URL) as conn: + rows = conn.execute( + "SELECT id, title, category, completed FROM todos ORDER BY id ASC" + ).fetchall() + return [ + {{"id": r[0], "title": r[1], "category": r[2], "completed": r[3]}} + for r in rows + ] + + +@app.post("/api/todos", status_code=201) +def create_todo(payload: TodoCreate) -> dict[str, object]: + # Live IDE demo: insert task into PostgreSQL and return created row + +@app.patch("/api/todos/{{todo_id}}") +def toggle_todo(todo_id: int, patch: TodoPatch) -> dict[str, object]: + with psycopg.connect(DB_URL) as conn: + row = conn.execute( + "UPDATE todos SET completed = %s WHERE id = %s RETURNING id, title, category, completed", + (patch.completed, todo_id), + ).fetchone() + if row is None: + raise HTTPException(status_code=404, detail="Todo not found") + return {{"id": row[0], "title": row[1], "category": row[2], "completed": row[3]}} +''' + +BACKEND_TYPED_SNIPPET = ( + " with psycopg.connect(DB_URL) as conn:\n" + " row = conn.execute(\n" + " 'INSERT INTO todos (title, category) VALUES (%s, %s) RETURNING id, title, category, completed',\n" + " (payload.title.strip(), payload.category),\n" + " ).fetchone()\n" + " return {'id': row[0], 'title': row[1], 'category': row[2], 'completed': row[3]}\n" +) + +FRONTEND_PACKAGE_JSON = { + "name": "capsuletask-ui", + "private": True, + "version": "0.1.0", + "type": "module", + "scripts": { + "dev": f"vite --host 127.0.0.1 --port {VITE_PORT} --strictPort", + }, + "dependencies": { + "react": "^18.3.1", + "react-dom": "^18.3.1", + }, + "devDependencies": { + "@vitejs/plugin-react": "^4.3.4", + "vite": "^5.4.11", + }, +} + +FRONTEND_VITE_CONFIG = f"""import {{ defineConfig }} from 'vite'; +import react from '@vitejs/plugin-react'; + +export default defineConfig({{ + plugins: [react()], + server: {{ + host: '127.0.0.1', + port: {VITE_PORT}, + strictPort: true, + proxy: {{ + '/api': 'http://127.0.0.1:{API_PORT}', + }}, + }}, +}}); +""" + +FRONTEND_INDEX_HTML = """ + + + + + CapsuleTask — FastAPI + PostgreSQL + React + + +
+ + + +""" + +FRONTEND_MAIN_JSX = """import React from 'react'; +import { createRoot } from 'react-dom/client'; +import App from './App.jsx'; +import './styles.css'; + +createRoot(document.getElementById('root')).render(); +""" + +FRONTEND_STYLES_CSS = """* { box-sizing: border-box; } +body { + margin: 0; + font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + background: #0f172a; + color: #f8fafc; +} +.shell { + max-width: 920px; + margin: 0 auto; + padding: 28px 32px; +} +.topbar { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 20px; + padding-bottom: 16px; + border-bottom: 1px solid #1e293b; +} +.brand h1 { + margin: 0; + font-size: 24px; + letter-spacing: -0.02em; +} +.brand p { + margin: 4px 0 0; + font-size: 13px; + color: #94a3b8; +} +.db-pill { + display: inline-flex; + align-items: center; + gap: 8px; + padding: 7px 14px; + border-radius: 999px; + background: rgba(16, 185, 129, 0.14); + border: 1px solid rgba(16, 185, 129, 0.4); + color: #34d399; + font-size: 13px; + font-weight: 600; +} +.dot { + width: 8px; + height: 8px; + border-radius: 50%; + background: #10b981; + box-shadow: 0 0 8px #10b981; +} +.stats { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 12px; + margin-bottom: 20px; +} +.stat-card { + background: #1e293b; + border: 1px solid #334155; + border-radius: 10px; + padding: 12px 16px; +} +.stat-label { font-size: 12px; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.04em; } +.stat-val { font-size: 24px; font-weight: 700; margin-top: 4px; color: #f1f5f9; } +.composer { + display: flex; + gap: 10px; + margin-bottom: 20px; + background: #1e293b; + padding: 12px; + border-radius: 12px; + border: 1px solid #334155; +} +.composer input { + flex: 1; + padding: 11px 14px; + border-radius: 8px; + border: 1px solid #475569; + background: #0f172a; + color: #f8fafc; + font-size: 15px; +} +.composer select { + padding: 11px 12px; + border-radius: 8px; + border: 1px solid #475569; + background: #0f172a; + color: #e2e8f0; + font-size: 14px; +} +.btn-primary { + padding: 11px 20px; + border-radius: 8px; + border: none; + background: #3b82f6; + color: #ffffff; + font-weight: 600; + font-size: 14px; + cursor: pointer; +} +.btn-secondary { + padding: 8px 14px; + border-radius: 8px; + border: 1px solid #475569; + background: #1e293b; + color: #e2e8f0; + font-size: 13px; + font-weight: 500; + cursor: pointer; +} +.list-header { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 10px; +} +.list-header h2 { margin: 0; font-size: 15px; color: #cbd5e1; } +.todo-list { display: flex; flex-direction: column; gap: 10px; } +.todo-row { + display: flex; + align-items: center; + gap: 14px; + padding: 14px 16px; + border-radius: 10px; + background: #1e293b; + border: 1px solid #334155; +} +.todo-row.done { opacity: 0.72; background: #172033; } +.todo-check { + width: 22px; + height: 22px; + cursor: pointer; + accent-color: #10b981; +} +.todo-title { flex: 1; font-size: 15px; font-weight: 500; } +.todo-row.done .todo-title { text-decoration: line-through; color: #94a3b8; } +.badge { + padding: 4px 10px; + border-radius: 6px; + font-size: 12px; + font-weight: 600; + background: rgba(59, 130, 246, 0.16); + color: #93c5fd; + border: 1px solid rgba(59, 130, 246, 0.35); +} +.row-id { font-family: monospace; font-size: 12px; color: #64748b; } +""" + +FRONTEND_APP_INITIAL = """import React, { useEffect, useState } from 'react'; + +export default function App() { + const [todos, setTodos] = useState([]); + const [pgVersion, setPgVersion] = useState('connecting...'); + const [title, setTitle] = useState(''); + const [category, setCategory] = useState('Engineering'); + const [syncStamp, setSyncStamp] = useState('Initial load'); + + async function loadAll(label = 'Synced from PostgreSQL') { + const [healthRes, todosRes] = await Promise.all([ + fetch('/api/health'), + fetch('/api/todos'), + ]); + const health = await healthRes.json(); + const rows = await todosRes.json(); + setPgVersion(`PostgreSQL ${health.postgres}`); + setTodos(rows); + setSyncStamp(`${label} (${rows.length} rows)`); + } + + useEffect(() => { + loadAll('Initial load'); + }, []); + + async function handleCreate(e) { + e.preventDefault(); + if (!title.trim()) return; + // Live IDE demo: POST new task to FastAPI and append returned PostgreSQL row + + } + + async function handleToggle(todo) { + const res = await fetch(`/api/todos/${todo.id}`, { + method: 'PATCH', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ completed: !todo.completed }), + }); + const updated = await res.json(); + setTodos((prev) => prev.map((t) => (t.id === updated.id ? updated : t))); + setSyncStamp(`Updated row #${updated.id} in PostgreSQL`); + } + + const doneCount = todos.filter((t) => t.completed).length; + + return ( +
+
+
+

CapsuleTask

+

DevCapsule Full-Stack Workspace · FastAPI + PostgreSQL + React

+
+
+ + {pgVersion} · Connected +
+
+ +
+
+
Total Tasks
+
{todos.length}
+
+
+
Open
+
{todos.length - doneCount}
+
+
+
Completed
+
{doneCount}
+
+
+ +
+ setTitle(e.target.value)} + /> + + +
+ +
+

Persisted Tasks ({syncStamp})

+ +
+ +
+ {todos.map((todo) => ( +
+ handleToggle(todo)} + /> + {todo.title} + {todo.category} + pg#{todo.id} +
+ ))} +
+
+ ); +} +""" + +FRONTEND_TYPED_SNIPPET = ( + " const res = await fetch('/api/todos', {\n" + " method: 'POST',\n" + " headers: { 'Content-Type': 'application/json' },\n" + " body: JSON.stringify({ title, category }),\n" + " });\n" + " const created = await res.json();\n" + " setTodos((prev) => [...prev, created]);\n" + " setTitle('');\n" +) + +RUN_STACK_SH = f"""#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")" +export LC_ALL=C.UTF-8 LANG=C.UTF-8 +export DATABASE_URL="{DB_URL}" +echo "=== [1/3] Checking PostgreSQL 17 via DevCapsule psql component ===" +psql "$DATABASE_URL" -c "SELECT version();" -t | head -n 1 + +echo "=== [2/3] Starting FastAPI (Uvicorn on 127.0.0.1:{API_PORT}) ===" +nohup ./backend/.venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port {API_PORT} /tmp/fastapi.log 2>&1 & +echo $! > /tmp/fastapi.pid + +for i in $(seq 1 40); do + if curl -fsS http://127.0.0.1:{API_PORT}/api/health >/dev/null 2>&1; then + break + fi + sleep 0.25 +done +curl -fsS http://127.0.0.1:{API_PORT}/api/health && echo "" + +echo "=== [3/3] Starting React + Vite dev server (127.0.0.1:{VITE_PORT}) ===" +nohup npm --prefix frontend run dev /tmp/vite.log 2>&1 & +echo $! > /tmp/vite.pid + +for i in $(seq 1 40); do + if curl -fsS http://127.0.0.1:{VITE_PORT}/ >/dev/null 2>&1; then + break + fi + sleep 0.25 +done + +echo "=== Initial rows in PostgreSQL todos table ===" +psql "$DATABASE_URL" -c "SELECT id, category, completed, title FROM todos ORDER BY id;" +echo "STACK_READY api=http://127.0.0.1:{API_PORT} ui=http://localhost:{VITE_PORT}" +""" + +QUERY_DB_SH = f"""#!/usr/bin/env bash +set -euo pipefail +export LC_ALL=C.UTF-8 LANG=C.UTF-8 +export DATABASE_URL="{DB_URL}" +psql "$DATABASE_URL" -c "SELECT id, category, completed, title FROM todos ORDER BY id;" +""" + + +def write_seed_project(workspace: Path) -> dict[str, int]: + """Write initial Todo project files into ``workspace`` and return exact target edit lines.""" + (workspace / ".vscode").mkdir(parents=True, exist_ok=True) + (workspace / ".vscode" / "settings.json").write_text( + json.dumps(VSCODE_SETTINGS, indent=2) + "\n", encoding="utf-8" + ) + (workspace / "backend").mkdir(parents=True, exist_ok=True) + (workspace / "backend" / "__init__.py").write_text("", encoding="utf-8") + (workspace / "backend" / "main.py").write_text(BACKEND_MAIN_INITIAL, encoding="utf-8") + + (workspace / "frontend" / "src").mkdir(parents=True, exist_ok=True) + (workspace / "frontend" / "package.json").write_text( + json.dumps(FRONTEND_PACKAGE_JSON, indent=2) + "\n", encoding="utf-8" + ) + (workspace / "frontend" / "vite.config.js").write_text(FRONTEND_VITE_CONFIG, encoding="utf-8") + (workspace / "frontend" / "index.html").write_text(FRONTEND_INDEX_HTML, encoding="utf-8") + (workspace / "frontend" / "src" / "main.jsx").write_text(FRONTEND_MAIN_JSX, encoding="utf-8") + (workspace / "frontend" / "src" / "styles.css").write_text(FRONTEND_STYLES_CSS, encoding="utf-8") + (workspace / "frontend" / "src" / "App.jsx").write_text(FRONTEND_APP_INITIAL, encoding="utf-8") + + for name, body in (("run-stack.sh", RUN_STACK_SH), ("query-db.sh", QUERY_DB_SH)): + p = workspace / name + p.write_text(body, encoding="utf-8") + p.chmod(0o755) + + backend_lines = BACKEND_MAIN_INITIAL.splitlines() + backend_marker = next( + idx + 2 for idx, line in enumerate(backend_lines) if "# Live IDE demo:" in line + ) + frontend_lines = FRONTEND_APP_INITIAL.splitlines() + frontend_marker = next( + idx + 2 for idx, line in enumerate(frontend_lines) if "// Live IDE demo:" in line + ) + return {"backend_edit_line": backend_marker, "frontend_edit_line": frontend_marker} + + +if __name__ == "__main__": + import tempfile + + with tempfile.TemporaryDirectory() as d: + info = write_seed_project(Path(d)) + print("Edit lines:", info) + # Verify completed backend compiles cleanly when BACKEND_TYPED_SNIPPET is inserted! + lines = (Path(d) / "backend" / "main.py").read_text().splitlines(keepends=True) + idx = info["backend_edit_line"] - 1 + completed = "".join(lines[:idx] + [BACKEND_TYPED_SNIPPET] + lines[idx:]) + compile(completed, "backend/main.py", "exec") + print("Compiled completed backend/main.py successfully!") diff --git a/devcapsule-src/tests/unit/tests/e2e/__init__.py b/devcapsule-src/tests/unit/tests/e2e/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/devcapsule-src/tests/unit/tests/e2e/test_springboot_seed.py b/devcapsule-src/tests/unit/tests/e2e/test_springboot_seed.py new file mode 100644 index 00000000..87314633 --- /dev/null +++ b/devcapsule-src/tests/unit/tests/e2e/test_springboot_seed.py @@ -0,0 +1,21 @@ +"""Unit tests for ``tests.e2e.springboot_seed``.""" +from __future__ import annotations + +from pathlib import Path + +from tests.e2e.springboot_seed import materialize + + +def test_materialize_writes_maven_spring_boot_layout_and_placeholder_marker(tmp_path: Path) -> None: + """``materialize`` writes the Maven project, Spring Boot Java sources, static UI, and reports the placeholder line.""" + workspace = tmp_path / "springboot-workspace" + + info = materialize(workspace) + + assert isinstance(info["controller_placeholder_line"], int) + assert info["controller_placeholder_line"] > 1 + assert (workspace / "pom.xml").is_file() + assert (workspace / ".mvn" / "maven.config").is_file() + assert (workspace / "src" / "main" / "java" / "io" / "devcapsule" / "demo" / "SprintController.java").is_file() + assert (workspace / "src" / "main" / "resources" / "static" / "index.html").is_file() + assert (workspace / "run-stack.sh").is_file() diff --git a/devcapsule-src/tests/unit/tests/e2e/test_todo_demo_controller.py b/devcapsule-src/tests/unit/tests/e2e/test_todo_demo_controller.py new file mode 100644 index 00000000..9f03294f --- /dev/null +++ b/devcapsule-src/tests/unit/tests/e2e/test_todo_demo_controller.py @@ -0,0 +1,39 @@ +"""Unit tests for ``tests.e2e.todo_demo_controller``.""" +from __future__ import annotations + +import pytest + +from tests.e2e.todo_demo_controller import DemoStep + + +def test_demo_step_parse_accepts_launch_browser_with_url() -> None: + """``DemoStep.parse`` accepts ``launch_browser`` when given a non-empty target URL.""" + step = DemoStep.parse( + { + "action": "launch_browser", + "text": "http://127.0.0.1:15173", + "reason": "Open web application", + } + ) + + assert step.action == "launch_browser" + assert step.text == "http://127.0.0.1:15173" + assert step.reason == "Open web application" + + +@pytest.mark.parametrize( + "payload", + [ + {"action": "unknown"}, + {"action": "click", "x": 1600, "y": 10}, + {"action": "click", "x": 10, "y": -1}, + {"action": "wait", "ms": -5}, + {"action": "type", "text": ""}, + {"action": "press"}, + {"action": "launch_browser", "text": ""}, + ], +) +def test_demo_step_parse_rejects_out_of_range_or_empty_inputs(payload: dict[str, object]) -> None: + """``DemoStep.parse`` raises ``ValueError`` when action, coordinates, wait duration, or required text is invalid.""" + with pytest.raises(ValueError): + DemoStep.parse(payload) diff --git a/devcapsule-src/tests/unit/tests/e2e/test_todo_seed.py b/devcapsule-src/tests/unit/tests/e2e/test_todo_seed.py new file mode 100644 index 00000000..73ca9d5b --- /dev/null +++ b/devcapsule-src/tests/unit/tests/e2e/test_todo_seed.py @@ -0,0 +1,25 @@ +"""Unit tests for ``tests.e2e.todo_seed``.""" +from __future__ import annotations + +from pathlib import Path + +from tests.e2e.todo_seed import BACKEND_TYPED_SNIPPET, write_seed_project + + +def test_write_seed_project_materializes_backend_frontend_and_edit_markers(tmp_path: Path) -> None: + """``write_seed_project`` writes the Todo layout and returns the exact line where ``BACKEND_TYPED_SNIPPET`` produces valid Python.""" + workspace = tmp_path / "todo-workspace" + + markers = write_seed_project(workspace) + + assert markers["backend_edit_line"] > 1 + assert markers["frontend_edit_line"] > 1 + assert (workspace / ".vscode" / "settings.json").is_file() + assert (workspace / "backend" / "main.py").is_file() + assert (workspace / "frontend" / "src" / "App.jsx").is_file() + assert (workspace / "run-stack.sh").is_file() + assert (workspace / "query-db.sh").is_file() + lines = (workspace / "backend" / "main.py").read_text(encoding="utf-8").splitlines(keepends=True) + insert_at = markers["backend_edit_line"] - 1 + completed = "".join([*lines[:insert_at], BACKEND_TYPED_SNIPPET, *lines[insert_at:]]) + compile(completed, "backend/main.py", "exec") diff --git a/index.md b/index.md index 022abe87..e574815a 100644 --- a/index.md +++ b/index.md @@ -45,6 +45,8 @@ status file; internal WIP/archive documents use the local index in that status. - [Integration tests](engineering-docs/development/integration-tests.md) - [End-to-end tests](engineering-docs/development/e2e-tests.md) - [Running E2E scenario recordings from a shell with nox](engineering-docs/development/running-e2e-scenario-recordings.md) +- [E2E scenario script: FastAPI + PostgreSQL 17 + React Todo application](devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md) +- [E2E scenario script: Java 25 + Spring Boot + PostgreSQL 17 in IntelliJ IDEA](devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md) - [Pair Review Loop](engineering-docs/development/review-partner-loop.md) ## Releases From 8f31a2fafb16c57819dbdd9f0e475f5d0b218e85 Mon Sep 17 00:00:00 2001 From: Costin Cozianu Date: Sat, 14 Nov 2026 11:09:07 +0000 Subject: [PATCH 60/75] Web console: presentations, a recorded scenario as slides beside its recording A recorded end-to-end scenario leaves a fast video, a screenshot per action and logs. Nothing helped a person follow it. A folder that holds a presentation.json now opens at /presentations/ as a deck: an overview slide, then one slide per step of the scenario's script with the step's text, its screenshot and a button that plays only that step's part of the one recording, at half speed by default, with captions. Play all runs the recording through and changes the slide as the time passes. - /presentations lists the project's presentations as cards and is linked from the top band of every page and from Home. Files offers the link on a folder that holds a presentation.json. - GET /api/project/presentations finds those folders with find_project_folders: by descriptor, entering no symbolic link, no directory whose name starts with a dot and no node_modules, within a budget of directories. - The page reads the document, the recording and the screenshots through the raw route, as media of a console page, and writes nothing. It checks the document against the contract in PRESENTATIONS.md and refuses a broken one whole, naming every breach. - resources/presentations/todo-fastapi-postgres-react is the sample to open when changing the page: the recording, poster and seven screenshots of the 2026-11-13 run, with a presentation.json written from its script. The resources are not part of the distribution. Checked: nox -s webconsole (type check, 473 tests, among them the page run with a hand-driven video and clock), the docs contract, and the page in Chromium at three window sizes. Co-Authored-By: Claude Fable 5.2 --- devcapsule-webconsole/PRESENTATIONS.md | 129 +++++ devcapsule-webconsole/README.md | 13 + .../devcapsule_webconsole/app.py | 23 +- .../devcapsule_webconsole/security.py | 45 +- .../static/configuration.html | 2 +- .../devcapsule_webconsole/static/console.css | 3 +- .../devcapsule_webconsole/static/console.js | 14 +- .../static/decisions.html | 2 +- .../devcapsule_webconsole/static/files.html | 2 +- .../devcapsule_webconsole/static/index.html | 3 +- .../static/notifications.html | 2 +- .../static/presentation.css | 161 ++++++ .../static/presentation.html | 23 + .../static/presentation.js | 506 ++++++++++++++++++ .../static/processes.html | 2 +- .../devcapsule_webconsole/static/project.html | 2 +- .../devcapsule_webconsole/static/records.html | 2 +- .../static/versions.html | 2 +- .../todo-fastapi-postgres-react/poster.png | Bin 0 -> 135098 bytes .../presentation.json | 209 ++++++++ .../scenario-result.json | 39 ++ .../scenario-video.webm | Bin 0 -> 3144116 bytes .../todo-fastapi-postgres-react/step-004.png | Bin 0 -> 199451 bytes .../todo-fastapi-postgres-react/step-017.png | Bin 0 -> 375133 bytes .../todo-fastapi-postgres-react/step-030.png | Bin 0 -> 371542 bytes .../todo-fastapi-postgres-react/step-034.png | Bin 0 -> 358336 bytes .../todo-fastapi-postgres-react/step-036.png | Bin 0 -> 98058 bytes .../todo-fastapi-postgres-react/step-048.png | Bin 0 -> 129023 bytes .../todo-fastapi-postgres-react/step-054.png | Bin 0 -> 373799 bytes devcapsule-webconsole/tests/files-script.cjs | 22 +- .../tests/presentation-script.cjs | 293 ++++++++++ .../tests/test_presentations.py | 163 ++++++ docs/sessions/web-console.md | 11 +- 33 files changed, 1653 insertions(+), 20 deletions(-) create mode 100644 devcapsule-webconsole/PRESENTATIONS.md create mode 100644 devcapsule-webconsole/devcapsule_webconsole/static/presentation.css create mode 100644 devcapsule-webconsole/devcapsule_webconsole/static/presentation.html create mode 100644 devcapsule-webconsole/devcapsule_webconsole/static/presentation.js create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/poster.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/presentation.json create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/scenario-result.json create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/scenario-video.webm create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-004.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-017.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-030.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-034.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-036.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-048.png create mode 100644 devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react/step-054.png create mode 100644 devcapsule-webconsole/tests/presentation-script.cjs create mode 100644 devcapsule-webconsole/tests/test_presentations.py diff --git a/devcapsule-webconsole/PRESENTATIONS.md b/devcapsule-webconsole/PRESENTATIONS.md new file mode 100644 index 00000000..335fe904 --- /dev/null +++ b/devcapsule-webconsole/PRESENTATIONS.md @@ -0,0 +1,129 @@ +# Presentations: a recorded scenario as slides + +A recorded end-to-end scenario leaves a folder: one recording, a screenshot +per action, logs. The presentation page shows such a folder to a person who +wants to follow what happened: an overview slide, then one slide per step of +the scenario's script, each with the step's text, its screenshot and a button +that plays only that step's part of the recording, with captions. + +`/presentations/` presents the project folder ``, and +`/presentations`, linked from the top band of every page, lists the project's +presentations as cards. The Files page offers the link on any folder that +holds a `presentation.json`. + +The page is `static/presentation.html` with `static/presentation.js` and +`static/presentation.css`. It reads `/presentation.json`, the +recording and the screenshots through `/api/project/raw`, as media of a +console page, so the raw route's policy for opened documents does not apply +to them. It writes nothing. + +## Finding the presentations + +`GET /api/project/presentations` answers +`{"folders": ["path/of/a/folder", …], "complete": true}`: the folders below +the project root that hold a regular file named `presentation.json`, sorted. +The search (`find_project_folders` in `security.py`) opens each directory by +descriptor from its parent and enters no symbolic link, so it stays inside +the mount. It does not enter a directory whose name starts with a dot or a +`node_modules` directory, and it visits at most 20,000 directories; when it +stops there, `complete` is false and the list page says a presentation may +be missing. The project root itself is not a presentation. + +The list page reads and checks each folder's document as the deck would, so +a card states the title, the summary, the number of steps and the length the +document gives, and a folder whose document breaks the contract shows the +refusal in place of a card. + +## The folder + +| File | What it is | +| --- | --- | +| `presentation.json` | The document below. Its presence makes the folder a presentation. | +| the recording | One video file the browser plays, named by `video.file`. | +| the poster | One image for the overview slide, named by `video.poster`. | +| the screenshots | One image per step, named by each step's `screenshot`. | + +Every file name is relative to the folder and stays inside it. A folder may +hold anything else; the page reads only what the document names. + +## `presentation.json` + +```json +{ + "schema_version": 1, + "scenario_id": "todo-fastapi-postgres-react", + "title": "Full-stack work in one capsule", + "overview": { + "summary": "What the viewer is about to see.", + "intent": "Why the scenario exists.", + "illustrates": ["One thing it shows.", "Another."], + "stack": [{"name": "Editor", "detail": "VSCodium"}] + }, + "video": {"file": "scenario-video.webm", "poster": "poster.png", "duration": 39.75}, + "steps": [ + { + "title": "Open the workspace", + "action": "What the user does.", + "expected": "What the viewer should see.", + "screenshot": "step-004.png", + "start": 0, + "end": 2.917, + "captions": [{"start": 0, "end": 1.25, "text": "Shown while this part plays."}] + } + ] +} +``` + +- `schema_version` is `1`. `title`, `overview.summary`, `video` and at least + one step are required; `overview.intent`, `overview.illustrates`, + `overview.stack` and `scenario_id` are optional. +- Times are seconds of the recording. `video.duration` is its length. +- Steps are in order and do not overlap: each starts at or after the end of + the one before, and none ends after the recording. A step's captions are in + order, do not overlap, and stay inside the step. +- A text may mark `` `code` ``, `**strong**` and `*emphasis*`. Nothing else is + interpreted; every text reaches the page as text, never as HTML. + +The page checks all of this before it shows anything. A document that breaks +the contract is refused whole, and the page names every breach. + +## What the page does + +- **Slides.** The overview, then one per step. The chips at the bottom, the + arrow keys, Page Up and Page Down, and Home change the slide. The address + ends in `#`, so a link opens on a step. +- **Show this step.** Plays the recording from the step's start to its end + and stops on its last frame. The step's captions are listed under + *Moments*; the one being played is lit, and selecting one plays from there. +- **Play all.** Plays the recording through. The slide follows the time, and + the recording waits a moment on each new step so its title can be read. +- **Speed.** Half speed by default, because recordings of scripted actions + run faster than a person reads; 0.75× and 1× are offered. +- **Space** plays, pauses and resumes. **Larger video** puts the recording + above the text at the page's full width. + +When the recording's own length differs from `video.duration` by more than +half a second, the page says so: a scenario recorded again without a new +`presentation.json` is the likely cause. A recording that does not state its +length cannot be compared. + +## Trying a change + +From `devcapsule-src`: + +```sh +.venv/bin/python -m nox -s webconsole-preview +``` + +serves this checkout's console on `http://127.0.0.1:8787` and prints two +links carrying a token made for the run: the console's home, and the sample +presentation. The console is installed editable, so an edit to a page, a +script or a stylesheet shows on a browser reload; an edit to the Python +needs the command run again. `-- --port ` chooses another port and +`-- --project ` another DevCapsule project. Ctrl+C ends it. + +The sample is `resources/presentations/todo-fastapi-postgres-react/`: the +recording, the poster and seven screenshots of the 2026-11-13 run of the +`todo-fastapi-postgres-react` scenario, with a `presentation.json` written +from the scenario's script. It is the folder to open when changing the page. +The resources are not part of the distribution. diff --git a/devcapsule-webconsole/README.md b/devcapsule-webconsole/README.md index 9d65d804..3e0c066a 100644 --- a/devcapsule-webconsole/README.md +++ b/devcapsule-webconsole/README.md @@ -43,6 +43,12 @@ imports none of the runtime's internals. Its API is the runtime CLI's and adds an attachment disposition only when `download=1` is requested. DOT output is an image, so its links are inactive. Record headings have fragment targets; relative URL paths are decoded before resolution inside the project. +- A presentation is a project folder that holds a `presentation.json`: the + page at `/presentations/` shows a recorded scenario as slides beside + its recording, with captions, and `/presentations` lists the project's + presentations (see [PRESENTATIONS.md](PRESENTATIONS.md)). The search for + them enters no symbolic link, no directory whose name starts with a dot and + no `node_modules`. The page reads through the raw route and writes nothing. ## Running it on a host @@ -57,6 +63,13 @@ printf '%s\n' "$(python3 -c 'import secrets; print(secrets.token_hex(24))')" > / Then open `http://127.0.0.1:8080/?token=$(cat /tmp/console-token)`. +## Trying a change + +From `devcapsule-src`, `.venv/bin/python -m nox -s webconsole-preview` serves +this checkout's console on `http://127.0.0.1:8787` with the package installed +editable, and prints the links to open. See +[PRESENTATIONS.md](PRESENTATIONS.md#trying-a-change). + ## Checks From `devcapsule-src`: `.venv/bin/python -m nox -s webconsole` runs this diff --git a/devcapsule-webconsole/devcapsule_webconsole/app.py b/devcapsule-webconsole/devcapsule_webconsole/app.py index 554d7274..176dcf58 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/app.py +++ b/devcapsule-webconsole/devcapsule_webconsole/app.py @@ -6,9 +6,10 @@ files that fetch their facts from the ``/api`` routes, which run the runtime CLI, read the capsule's processes and cgroup, list or read inside the project mount, or read the decisions directory. The records page -renders any markdown file of the project in the browser, and the files page -lists and serves the mounted project's files. The token gate wraps the whole -application, static files included. +renders any markdown file of the project in the browser, the files page +lists and serves the mounted project's files, and the presentation page lists +the folders that hold a ``presentation.json`` and shows one as slides beside +its recording, read through the raw route. The token gate wraps the whole application, static files included. """ from __future__ import annotations @@ -34,7 +35,9 @@ from .decisions import ( KEY_PATTERN, MAXIMUM_ANSWER_BYTES, Decision, DecisionError, DecisionStore, answer_from_mapping, ) -from .security import PathRefused, TokenGate, list_project_directory, open_project_file, read_project_text +from .security import ( + PathRefused, TokenGate, find_project_folders, list_project_directory, open_project_file, read_project_text, +) from .settings import Settings PAGES = { @@ -75,6 +78,8 @@ ".wav": "audio/wav", } RAW_CHUNK_BYTES = 64 * 1024 +# The file whose presence makes a project folder a presentation (PRESENTATIONS.md). +PRESENTATION_FILE = "presentation.json" RAW_SECURITY_HEADERS = { "Accept-Ranges": "bytes", "Content-Security-Policy": "sandbox; default-src 'none'; style-src 'unsafe-inline'", @@ -99,6 +104,11 @@ def document(read: Callable[[], dict[str, Any]]) -> JSONResponse: # One page for every record or directory: the script reads the path from the URL. app.add_api_route("/records/{record:path}", _page(settings, "records.html"), methods=["GET"], include_in_schema=False) app.add_api_route("/files/{path:path}", _page(settings, "files.html"), methods=["GET"], include_in_schema=False) + # One page for the list of presentations and for each of them: the script + # reads the folder from the URL, and its presentation.json, recording and + # screenshots through the raw route. + app.add_api_route("/presentations", _page(settings, "presentation.html"), methods=["GET"], include_in_schema=False) + app.add_api_route("/presentations/{path:path}", _page(settings, "presentation.html"), methods=["GET"], include_in_schema=False) app.add_api_route("/decisions/{decision_id}", _page(settings, "decisions.html"), methods=["GET"], include_in_schema=False) @app.get("/filetree", include_in_schema=False) @@ -302,6 +312,11 @@ def project_tree(path: str = "") -> Response: return PlainTextResponse(f"cannot read {path!r} in the project\n", status_code=403) return JSONResponse(listing) + @app.get("/api/project/presentations") + def project_presentations() -> JSONResponse: + """The project's folders that hold a presentation, and whether the search visited every directory.""" + return JSONResponse(find_project_folders(settings.project, PRESENTATION_FILE)) + @app.get("/api/project/file") def project_file(path: str = Query(...)) -> PlainTextResponse: try: diff --git a/devcapsule-webconsole/devcapsule_webconsole/security.py b/devcapsule-webconsole/devcapsule_webconsole/security.py index 2c4edc5e..b8611142 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/security.py +++ b/devcapsule-webconsole/devcapsule_webconsole/security.py @@ -4,8 +4,8 @@ the launcher prints and is kept in a port-scoped cookie from then on. Every file or directory the console reads lies inside the project mount; a path that escapes it is refused before its contents are read. Public operations on the -project mount are ``confine``, ``list_project_directory``, ``open_project_file``, -``read_project_bytes`` and ``read_project_text``. +project mount are ``confine``, ``find_project_folders``, ``list_project_directory``, +``open_project_file``, ``read_project_bytes`` and ``read_project_text``. """ from __future__ import annotations @@ -31,6 +31,7 @@ "TOKEN_QUERY_PARAMETER", "TokenGate", "confine", + "find_project_folders", "list_project_directory", "open_project_file", "read_project_bytes", @@ -43,6 +44,12 @@ TOKEN_HEADER = "x-devcapsule-token" TOKEN_HEADER_BYTES = TOKEN_HEADER.encode("ascii") REFUSAL_BODY = b"devcapsule web console: missing or invalid run token\n" +# Where find_project_folders does not look: a directory whose name starts with +# a dot (version control, environments, caches), and the package trees named +# here. They hold other people's files by the tens of thousands. +UNSEARCHED_DIRECTORIES = frozenset({"node_modules"}) +# The most directories one search visits before it reports itself incomplete. +FOLDER_SEARCH_BUDGET = 20_000 def token_cookie_name(port: int | None = None) -> str: @@ -324,3 +331,37 @@ def list_project_directory(root: Path, requested: str = "") -> dict[str, Any]: }) entries.sort(key=lambda item: (item["kind"] != "directory", item["name"].casefold(), item["name"])) return {"path": clean_path, "entries": entries} + + +def find_project_folders(root: Path, marker: str, *, budget: int = FOLDER_SEARCH_BUDGET) -> dict[str, Any]: + """The folders below ``root`` that hold a regular file named ``marker``. + + The result is ``{"folders": [...], "complete": bool}``: paths relative to + ``root`` with ``/`` separators, sorted, and whether every directory was + visited. The root itself is never among them. The walk opens each + directory by descriptor from its parent and enters no symbolic link, so it + cannot leave the mount; a ``marker`` that is itself a link or a directory + does not count. It does not enter a directory whose name starts with a dot + or is in ``UNSEARCHED_DIRECTORIES``, visits directories in name order, and + stops after ``budget`` of them with ``complete`` false. A directory that + cannot be read is passed over. + """ + base = root.resolve() + folders: list[str] = [] + visited = 0 + for path, directories, files, descriptor in os.fwalk(base, follow_symlinks=False): + if visited == budget: + return {"folders": sorted(folders), "complete": False} + visited += 1 + directories[:] = sorted( + name for name in directories if not name.startswith(".") and name not in UNSEARCHED_DIRECTORIES + ) + if marker not in files or Path(path) == base: + continue + try: + mode = os.stat(marker, dir_fd=descriptor, follow_symlinks=False).st_mode + except OSError: + continue + if stat.S_ISREG(mode): + folders.append(Path(path).relative_to(base).as_posix()) + return {"folders": sorted(folders), "complete": True} diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/configuration.html b/devcapsule-webconsole/devcapsule_webconsole/static/configuration.html index bb98442c..0bda6851 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/configuration.html +++ b/devcapsule-webconsole/devcapsule_webconsole/static/configuration.html @@ -10,7 +10,7 @@
diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/console.css b/devcapsule-webconsole/devcapsule_webconsole/static/console.css index adbd132f..0f935458 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/console.css +++ b/devcapsule-webconsole/devcapsule_webconsole/static/console.css @@ -1,4 +1,5 @@ -/* The console's one stylesheet: clean, aerated, readable first. */ +/* The console's stylesheet: clean, aerated, readable first. The presentation + page adds presentation.css to it. */ :root { --ink: #1b2622; --lead: #4a5a52; diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/console.js b/devcapsule-webconsole/devcapsule_webconsole/static/console.js index 445a5b61..c830b83e 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/console.js +++ b/devcapsule-webconsole/devcapsule_webconsole/static/console.js @@ -1,7 +1,9 @@ -// The console's one script. Each page names itself with data-page on ; +// The console's script. Each page names itself with data-page on ; // the matching renderer fetches the page's document from /api and builds the // DOM with textContent. Records use markdown-it with raw HTML disabled; // Graphviz output is displayed as an image, never inserted into the DOM. +// The presentation page has its own script, presentation.js, beside this one, +// which gives it the console bar and the bell. (function () { "use strict"; @@ -574,6 +576,13 @@ container.replaceChildren(crumbs, el("p", { class: "notice", text: "This directory is empty." })); return; } + // A folder that holds a presentation.json is a recorded scenario: offer its slides. + const presented = listing.entries.some((entry) => entry.kind === "file" && entry.name === "presentation.json"); + const presentation = presented ? [el("p", { class: "notice" }, [ + "This folder is a recorded scenario. ", + el("a", { href: "/presentations/" + encodeSegments(directory), text: "Open its presentation" }), + ".", + ])] : []; const head = el("tr", {}, [ el("th", { text: "Name" }), el("th", { class: "num", text: "Size" }), @@ -602,7 +611,8 @@ el("td", { class: "keep", text: scalar(entry.modified) }), ]); }); - container.replaceChildren(crumbs, el("table", { class: "data" }, [el("thead", {}, [head]), el("tbody", {}, rows)])); + container.replaceChildren(crumbs, ...presentation, + el("table", { class: "data" }, [el("thead", {}, [head]), el("tbody", {}, rows)])); }; // Decision pages (deliverable 5): the list, and one decision as a form. diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/decisions.html b/devcapsule-webconsole/devcapsule_webconsole/static/decisions.html index 694b5608..2f4a2319 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/decisions.html +++ b/devcapsule-webconsole/devcapsule_webconsole/static/decisions.html @@ -12,7 +12,7 @@
diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/files.html b/devcapsule-webconsole/devcapsule_webconsole/static/files.html index 5a17ab29..291e20cc 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/files.html +++ b/devcapsule-webconsole/devcapsule_webconsole/static/files.html @@ -10,7 +10,7 @@
diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/index.html b/devcapsule-webconsole/devcapsule_webconsole/static/index.html index b7e3e7d7..87d4ea47 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/index.html +++ b/devcapsule-webconsole/devcapsule_webconsole/static/index.html @@ -10,7 +10,7 @@
@@ -24,6 +24,7 @@

This capsule

ProcessesLive processes with CPU and memory, and the capsule's use against its limits. RecordsThe project's markdown records rendered, with index.md as the navigation and DOT diagrams drawn. FilesEvery file of the mounted project as it is: directories, Markdown records, images, videos and downloads. +PresentationsRecorded scenarios of the project as slides beside their recordings: each step's text and screenshot, played one step at a time with captions. DecisionsQuestions an agent handed to you, with the records beside each option; your answer goes back to the agent. NotificationsWhat this checkout's environment tells you: posted by agents and tools, with the decisions still waiting. diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/notifications.html b/devcapsule-webconsole/devcapsule_webconsole/static/notifications.html index 176ca891..73897ade 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/static/notifications.html +++ b/devcapsule-webconsole/devcapsule_webconsole/static/notifications.html @@ -12,7 +12,7 @@
diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/presentation.css b/devcapsule-webconsole/devcapsule_webconsole/static/presentation.css new file mode 100644 index 00000000..bf899226 --- /dev/null +++ b/devcapsule-webconsole/devcapsule_webconsole/static/presentation.css @@ -0,0 +1,161 @@ +/* The presentation page: a deck of slides beside one recording. The colours + and the type are console.css's; the screen is dark because recordings are. */ +body[data-page="presentation"] { --measure: 112rem; } +main.presentation { padding-top: 1.25rem; padding-bottom: 0; } +.presentation .deck { + display: grid; + grid-template-columns: minmax(19rem, 5fr) 9fr; + gap: 2.5rem; + align-items: start; +} +.presentation .deck.wide { grid-template-columns: 1fr; } +.presentation .deck.wide .stage { order: -1; } +@media (max-width: 62rem) { + .presentation .deck { grid-template-columns: 1fr; } + .presentation .deck .stage { order: -1; } +} + +/* The slide's text. */ +.presentation .slide { min-width: 0; } +.presentation .eyebrow { + margin: 0 0 0.5rem; + color: var(--brand); + font-size: 0.8rem; + font-weight: 600; + letter-spacing: 0.08em; + text-transform: uppercase; +} +.presentation .slide { font-size: 0.97rem; } +.presentation .slide h1 { font-size: 1.7rem; line-height: 1.25; margin: 0 0 0.9rem; } +.presentation .slide h1 code { font-size: 0.85em; } +.presentation .slide h2 { + margin: 1.5rem 0 0.35rem; + color: var(--muted); + font-size: 0.8rem; + font-weight: 600; + letter-spacing: 0.06em; + text-transform: uppercase; +} +.presentation .slide p { margin: 0; max-width: 40rem; } +.presentation .slide p.summary { color: var(--lead); font-size: 1.08rem; } +.presentation .slide details { margin-top: 1.5rem; } +.presentation .slide details summary { + color: var(--muted); font-size: 0.8rem; font-weight: 600; letter-spacing: 0.06em; text-transform: uppercase; cursor: pointer; +} +.presentation .slide details dl { margin-top: 0.6rem; } +.presentation .slide ul { margin: 0; padding-left: 1.1rem; max-width: 40rem; } +.presentation .slide ul li { margin: 0.3rem 0; } +.presentation dl.stack { display: grid; grid-template-columns: max-content 1fr; gap: 0.3rem 1.25rem; margin: 0; } +.presentation dl.stack dt { color: var(--muted); } +.presentation dl.stack dd { margin: 0; } +.presentation ol.outline { margin: 0; padding-left: 1.4rem; } +.presentation ol.outline li { margin: 0.2rem 0; } +.presentation button.link { + font: inherit; text-align: left; color: var(--brand); background: none; border: 0; padding: 0; cursor: pointer; +} +.presentation button.link:hover { text-decoration: underline; } + +/* The captions of a step, as a list that follows the recording. */ +.presentation ol.moments { list-style: none; margin: 0; padding: 0; max-width: 40rem; } +.presentation button.moment { + display: grid; grid-template-columns: 2.6rem 1fr; gap: 0.5rem; width: 100%; + font: inherit; text-align: left; color: var(--lead); + background: none; border: 0; border-left: 3px solid var(--line); + padding: 0.4rem 0.6rem; cursor: pointer; +} +.presentation button.moment:hover { background: var(--code-bg); } +.presentation button.moment .at { color: var(--muted); font-variant-numeric: tabular-nums; } +.presentation button.moment[aria-current] { color: var(--ink); background: var(--brand-soft); border-left-color: var(--brand); } + +/* The stage: the screen, the caption under it, the transport. */ +.presentation .stage { min-width: 0; position: sticky; top: 1rem; } +.presentation .deck.wide .stage { position: static; } +/* Beside the text, the player is as wide as its column unless that would push + the transport and the slide buttons below the window; --aspect is the + recording's width over its height, set by the script. */ +.presentation .player { width: min(100%, calc((100vh - 21rem) * var(--aspect, 1.6))); margin: 0 auto; } +.presentation .deck.wide .player { width: 100%; } +.presentation .screen { + position: relative; + aspect-ratio: var(--aspect, 1.6); + background: #0f1417; + border-radius: 8px 8px 0 0; + overflow: hidden; +} +.presentation .screen video, +.presentation .screen .still { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; } +.presentation .screen video { cursor: pointer; } +.presentation .screen .still[hidden], .presentation .screen .overlay[hidden] { display: none; } +.presentation .screen .overlay { + position: absolute; inset: 0; width: 100%; + display: flex; align-items: center; justify-content: center; + background: rgba(15, 20, 23, 0.28); border: 0; cursor: pointer; +} +.presentation .screen .overlay:hover { background: rgba(15, 20, 23, 0.4); } +.presentation .screen .pill { + font: inherit; font-weight: 600; color: #fff; + background: var(--brand); border-radius: 2rem; padding: 0.7rem 1.6rem; + box-shadow: 0 6px 24px rgba(0, 0, 0, 0.35); +} +.presentation .caption { + margin: 0; + min-height: 4.2rem; + display: flex; align-items: center; justify-content: center; + padding: 0.6rem 1.25rem; + background: #0f1417; color: #f2f5f3; + border-radius: 0 0 8px 8px; + font-size: 1.1rem; line-height: 1.4; text-align: center; +} +.presentation .caption code { background: rgba(255, 255, 255, 0.14); color: inherit; } +.presentation .caption .hint { color: #8a968f; font-size: 0.95rem; } +.presentation .transport { display: flex; align-items: center; gap: 1rem; margin-top: 0.9rem; flex-wrap: wrap; } +.presentation .progress { flex: 1 1 8rem; height: 0.4rem; background: var(--line); border-radius: 3px; overflow: hidden; } +.presentation .progress span { display: block; height: 100%; width: 0; background: var(--brand); } +.presentation .time { color: var(--muted); font-size: 0.9rem; font-variant-numeric: tabular-nums; white-space: nowrap; } +.presentation .speed { color: var(--muted); font-size: 0.9rem; white-space: nowrap; } +.presentation .speed select { font: inherit; padding: 0.15rem 0.3rem; border: 1px solid var(--line); border-radius: 4px; background: var(--surface); } +.presentation .stage .notice { margin: 0.9rem 0 0; max-width: none; } +.presentation .stage .notice[hidden] { display: none; } + +.presentation button.primary { + font: inherit; font-weight: 600; color: #fff; background: var(--brand); + border: 0; border-radius: 4px; padding: 0.45rem 1.1rem; cursor: pointer; min-width: 11.5rem; +} +.presentation button.quiet { + font: inherit; color: var(--ink); background: var(--surface); + border: 1px solid var(--line); border-radius: 4px; padding: 0.4rem 0.9rem; cursor: pointer; +} +.presentation button.quiet:hover:not([disabled]) { border-color: var(--brand); } +.presentation button[disabled] { opacity: 0.45; cursor: default; } + +/* The slides, in order. */ +.presentation .deck-nav { + position: sticky; bottom: 0; z-index: 2; + display: flex; align-items: center; gap: 0.9rem; flex-wrap: wrap; + margin-top: 1.5rem; padding: 0.8rem 0; background: var(--page); border-top: 1px solid var(--line); +} +.presentation .chips { display: flex; gap: 0.35rem; flex-wrap: wrap; } +.presentation button.chip { + font: inherit; font-size: 0.9rem; color: var(--lead); background: var(--surface); + border: 1px solid var(--line); border-radius: 2rem; min-width: 2.1rem; padding: 0.2rem 0.7rem; cursor: pointer; +} +.presentation button.chip:hover { border-color: var(--brand); } +.presentation button.chip[aria-current] { color: #fff; background: var(--brand); border-color: var(--brand); } +.presentation .deck-nav button.quiet:last-child { margin-left: auto; } +body[data-page="presentation"] footer.console-foot { padding-top: 1rem; } + +/* The list of the project's presentations. */ +.presentation .shows { display: grid; grid-template-columns: repeat(auto-fill, minmax(21rem, 1fr)); gap: 1.5rem; } +.presentation .show { + display: flex; flex-direction: column; gap: 0.45rem; + background: var(--surface); border: 1px solid var(--line); border-radius: 8px; padding: 0 0 1rem; + color: var(--ink); text-decoration: none; overflow: hidden; +} +.presentation a.show:hover { border-color: var(--brand); } +.presentation .show img { width: 100%; aspect-ratio: 16 / 10; object-fit: cover; background: #0f1417; margin-bottom: 0.4rem; } +.presentation .show strong, .presentation .show span { padding: 0 1.1rem; } +.presentation .show strong { color: var(--brand); font-size: 1.05rem; line-height: 1.3; } +.presentation .show .summary { color: var(--lead); font-size: 0.95rem; } +.presentation .show .meta { color: var(--muted); font-size: 0.85rem; overflow-wrap: anywhere; } +.presentation .show.refused { padding-top: 1rem; } +.presentation .show.refused .failure { margin: 0 1.1rem; padding: 0.6rem 0.8rem; font-size: 0.8rem; } diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/presentation.html b/devcapsule-webconsole/devcapsule_webconsole/static/presentation.html new file mode 100644 index 00000000..2114c6f0 --- /dev/null +++ b/devcapsule-webconsole/devcapsule_webconsole/static/presentation.html @@ -0,0 +1,23 @@ + + + + + +Presentation · DevCapsule console + + + + + + +
+
+

Loading…

+
+
Read-only. A presentation is a project folder's presentation.json with the recording and the screenshots it names; the arrow keys change the slide and the space bar plays or pauses.
+ + diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/presentation.js b/devcapsule-webconsole/devcapsule_webconsole/static/presentation.js new file mode 100644 index 00000000..da5b0816 --- /dev/null +++ b/devcapsule-webconsole/devcapsule_webconsole/static/presentation.js @@ -0,0 +1,506 @@ +// The presentation page: a recorded scenario as a deck of slides beside its +// recording. /presentations/ reads /presentation.json from the +// project (the contract is PRESENTATIONS.md) and shows an overview slide, then +// one slide per step: the script's text, the step's screenshot, and a button +// that plays only that step's part of the one recording. "Play all" runs the +// recording through, changing the slide and the caption as the time passes. +// /presentations alone lists the project's folders that hold a presentation. +// +// The page reads; it writes nothing. Every text is placed with textContent. +(function () { + "use strict"; + + const DATA_FILE = "presentation.json"; + const SCHEMA_VERSION = 1; + const RAW_ROUTE = "/api/project/raw?path="; + const LIST_ROUTE = "/api/project/presentations"; + const RATES = [0.5, 0.75, 1]; + const DEFAULT_RATE = 0.5; + // During "Play all" the recording waits this long on each new step, so its title can be read. + const HOLD_MILLISECONDS = 1500; + // A step is over this close to its end: a frame of the recording lasts longer. + const END_TOLERANCE_SECONDS = 0.02; + // The recording and its description disagree when their lengths differ by more than this. + const DURATION_TOLERANCE_SECONDS = 0.5; + + function el(tag, attributes, children) { + const node = document.createElement(tag); + for (const [name, value] of Object.entries(attributes || {})) { + if (name === "text") node.textContent = value; + else node.setAttribute(name, value); + } + for (const child of children || []) node.appendChild(child); + return node; + } + + // The texts of a presentation may mark `code`, **strong** and *emphasis*. + // Nothing else is interpreted, and every piece becomes a text node. + const MARK = /(``.+?``|`[^`]+`|\*\*[^*]+\*\*|\*[^*]+\*)/; + function inline(text) { + return String(text).split(MARK).filter((piece) => piece !== "").map((piece) => { + if (piece.length > 4 && piece.startsWith("``") && piece.endsWith("``")) return el("code", { text: piece.slice(2, -2).trim() }); + if (piece.length > 2 && piece.startsWith("`") && piece.endsWith("`")) return el("code", { text: piece.slice(1, -1) }); + if (piece.length > 4 && piece.startsWith("**") && piece.endsWith("**")) return el("strong", { text: piece.slice(2, -2) }); + if (piece.length > 2 && piece.startsWith("*") && piece.endsWith("*")) return el("em", { text: piece.slice(1, -1) }); + return document.createTextNode(piece); + }); + } + + // A file of a presentation's folder, as the raw route serves it. + function fileUrl(directory, name) { + return RAW_ROUTE + encodeURIComponent(directory + "/" + name); + } + + function pageUrl(directory) { + return "/presentations/" + directory.split("/").map(encodeURIComponent).join("/"); + } + + function stepCount(count) { + return count === 1 ? "1 step" : count + " steps"; + } + + function clock(seconds) { + const whole = Math.max(0, Math.round(seconds)); + return Math.floor(whole / 60) + ":" + String(whole % 60).padStart(2, "0"); + } + + // What is wrong with a presentation document, as sentences; empty when it + // follows the contract. The page shows nothing of a document that does not. + function problems(doc) { + const found = []; + const isText = (value) => typeof value === "string" && value.trim() !== ""; + const isFile = (value) => isText(value) && !value.startsWith("/") && !value.split("/").includes(".."); + const isTime = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0; + if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return ["the document is not a JSON object"]; + if (doc.schema_version !== SCHEMA_VERSION) found.push("schema_version is not " + SCHEMA_VERSION); + if (!isText(doc.title)) found.push("title is missing"); + const overview = doc.overview || {}; + if (!isText(overview.summary)) found.push("overview.summary is missing"); + if (overview.intent !== undefined && !isText(overview.intent)) found.push("overview.intent is not a text"); + if (overview.illustrates !== undefined && !(Array.isArray(overview.illustrates) && overview.illustrates.every(isText))) { + found.push("overview.illustrates is not a list of texts"); + } + if (overview.stack !== undefined && !(Array.isArray(overview.stack) + && overview.stack.every((row) => row && isText(row.name) && isText(row.detail)))) { + found.push("overview.stack is not a list of name and detail"); + } + const video = doc.video || {}; + if (!isFile(video.file)) found.push("video.file is not a file name inside the folder"); + if (!isFile(video.poster)) found.push("video.poster is not a file name inside the folder"); + if (!(isTime(video.duration) && video.duration > 0)) found.push("video.duration is not a positive number of seconds"); + if (!Array.isArray(doc.steps) || doc.steps.length === 0) return found.concat(["steps is not a list with at least one step"]); + let previousEnd = 0; + doc.steps.forEach((step, index) => { + const name = "step " + (index + 1); + if (step === null || typeof step !== "object") { found.push(name + " is not an object"); return; } + for (const field of ["title", "action", "expected"]) if (!isText(step[field])) found.push(name + ": " + field + " is missing"); + if (!isFile(step.screenshot)) found.push(name + ": screenshot is not a file name inside the folder"); + if (!(isTime(step.start) && isTime(step.end) && step.start < step.end)) { + found.push(name + ": start and end are not seconds with start before end"); + return; + } + if (step.start < previousEnd) found.push(name + " starts before the step before it ends"); + if (isTime(video.duration) && step.end > video.duration) found.push(name + " ends after the recording"); + previousEnd = step.end; + if (!Array.isArray(step.captions)) { found.push(name + ": captions is not a list"); return; } + let captionEnd = step.start; + step.captions.forEach((caption, position) => { + const label = name + ", caption " + (position + 1); + if (caption === null || typeof caption !== "object" || !isText(caption.text) + || !(isTime(caption.start) && isTime(caption.end) && caption.start < caption.end)) { + found.push(label + " needs a text, and start before end in seconds"); + return; + } + if (caption.start < captionEnd || caption.end > step.end) found.push(label + " overlaps its neighbour or leaves its step"); + captionEnd = caption.end; + }); + }); + return found; + } + + // The step that is playing at a time of the recording: the last one that + // has started. Steps are in order and do not overlap (problems checks it). + function stepIndexAt(steps, time) { + let index = 0; + for (let candidate = 0; candidate < steps.length; candidate++) if (steps[candidate].start <= time) index = candidate; + return index; + } + + function captionIndexAt(step, time) { + return step.captions.findIndex((caption) => caption.start <= time && time < caption.end); + } + + function directoryFromLocation() { + const tail = window.location.pathname.replace(/^\/presentations\/?/, "").replace(/\/+$/, ""); + return tail ? tail.split("/").map(decodeURIComponent).join("/") : ""; + } + + function crumbs(directory) { + const trail = el("p", { class: "crumbs" }, [el("a", { href: "/files", text: "project" })]); + const parts = directory.split("/"); + parts.forEach((part, index) => { + trail.appendChild(document.createTextNode(" › ")); + trail.appendChild(el("a", { href: "/files/" + parts.slice(0, index + 1).map(encodeURIComponent).join("/"), text: part })); + }); + return trail; + } + + // The checked presentation document of a folder below the project root. + async function read(directory) { + const path = directory + "/" + DATA_FILE; + const response = await fetch(fileUrl(directory, DATA_FILE), { credentials: "same-origin" }); + if (response.status === 404) throw new Error("There is no presentation here: " + directory + " has no " + DATA_FILE + "."); + if (!response.ok) throw new Error(path + ": " + ((await response.text()).trim() || "HTTP " + response.status)); + let doc; + try { doc = JSON.parse(await response.text()); } catch (error) { throw new Error(path + " is not JSON: " + error.message); } + const found = problems(doc); + if (found.length) throw new Error(path + " does not follow the presentation contract:\n" + found.join("\n")); + return doc; + } + + // Build the deck for a checked document and wire it. Slide 0 is the + // overview; slide n is step n. One