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/ci-python-inputs.yml b/.github/ci-python-inputs.yml new file mode 100644 index 00000000..a3208a34 --- /dev/null +++ b/.github/ci-python-inputs.yml @@ -0,0 +1,23 @@ +# 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 + - 'component-status/**' # tests/test_component_status.py + - 'docs/versions.yaml' # tests/test_release_docs.py + - 'engineering-docs/releases/v0.2.14/notes.md' # tests/test_release_docs.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9e4c4a39..7d02e81b 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 @@ -94,10 +102,24 @@ jobs: fetch-depth: 0 fetch-tags: true - name: Fetch documentation refs and the pinned website implementation + id: fetch-website + shell: bash run: | git fetch origin '+refs/heads/docs-*:refs/heads/docs-*' - git config submodule.website.url https://github.com/mycodespace-ai/devcapsule-website.git - git submodule update --init website + website_sha="$(git rev-parse --verify HEAD:website)" + rm -rf website + git -c init.defaultBranch=main init -q website + git -C website remote add origin https://github.com/mycodespace-ai/devcapsule-website.git + git -C website fetch --depth=1 origin "$website_sha" + git -C website checkout --detach FETCH_HEAD + git -c url."https://github.com/".insteadOf="git@github.com:" -C website submodule update --init --recursive + if [[ -f .gitmodules ]]; then + while IFS= read -r -d '' sub_key; do + sub_path="$(git config --file .gitmodules --get "$sub_key")" + [[ -z "$sub_path" || "$sub_path" == "website" ]] && continue + git -c url."https://github.com/".insteadOf="git@github.com:" submodule update --init --recursive -- "$sub_path" + done < <(git config --file .gitmodules --null --name-only --get-regexp '^submodule\..*\.path$' || true) + fi - uses: actions/setup-node@v4 with: node-version: '22' diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 4329c33f..36a6e524 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -51,11 +51,26 @@ jobs: shell: bash run: git fetch origin '+refs/heads/docs-*:refs/heads/docs-*' # Public checkout via HTTPS: no SSH/deployment secret needed in Actions. - - name: Fetch the exact website submodule commit + # `website` is a raw gitlink (no .gitmodules entry), so fetch its pinned + # commit directly and initialize any nested or sibling submodules recursively. + - name: Fetch the exact website gitlink commit + id: fetch-website shell: bash run: | - git config submodule.website.url https://github.com/mycodespace-ai/devcapsule-website.git - git submodule update --init website + website_sha="$(git rev-parse --verify HEAD:website)" + rm -rf website + git -c init.defaultBranch=main init -q website + git -C website remote add origin https://github.com/mycodespace-ai/devcapsule-website.git + git -C website fetch --depth=1 origin "$website_sha" + git -C website checkout --detach FETCH_HEAD + git -c url."https://github.com/".insteadOf="git@github.com:" -C website submodule update --init --recursive + if [[ -f .gitmodules ]]; then + while IFS= read -r -d '' sub_key; do + sub_path="$(git config --file .gitmodules --get "$sub_key")" + [[ -z "$sub_path" || "$sub_path" == "website" ]] && continue + git -c url."https://github.com/".insteadOf="git@github.com:" submodule update --init --recursive -- "$sub_path" + done < <(git config --file .gitmodules --null --name-only --get-regexp '^submodule\..*\.path$' || true) + fi - uses: actions/setup-node@v4 with: node-version: '22' @@ -101,9 +116,23 @@ jobs: with: persist-credentials: false - name: Fetch the pinned website implementation + id: fetch-website + shell: bash run: | - git config submodule.website.url https://github.com/mycodespace-ai/devcapsule-website.git - git submodule update --init website + website_sha="$(git rev-parse --verify HEAD:website)" + rm -rf website + git -c init.defaultBranch=main init -q website + git -C website remote add origin https://github.com/mycodespace-ai/devcapsule-website.git + git -C website fetch --depth=1 origin "$website_sha" + git -C website checkout --detach FETCH_HEAD + git -c url."https://github.com/".insteadOf="git@github.com:" -C website submodule update --init --recursive + if [[ -f .gitmodules ]]; then + while IFS= read -r -d '' sub_key; do + sub_path="$(git config --file .gitmodules --get "$sub_key")" + [[ -z "$sub_path" || "$sub_path" == "website" ]] && continue + git -c url."https://github.com/".insteadOf="git@github.com:" submodule update --init --recursive -- "$sub_path" + done < <(git config --file .gitmodules --null --name-only --get-regexp '^submodule\..*\.path$' || true) + fi - uses: actions/setup-node@v4 with: node-version: '22' diff --git a/.gitmodules b/.gitmodules index 5e3a5fe6..e69de29b 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "website"] - path = website - url = git@github.com:mycodespace-ai/devcapsule-website.git diff --git a/.idea/devcapsule-webconsole.iml b/.idea/devcapsule-webconsole.iml index 0f3ee75c..5aef307e 100644 --- a/.idea/devcapsule-webconsole.iml +++ b/.idea/devcapsule-webconsole.iml @@ -1,7 +1,10 @@ - + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml index 914c4a46..9c321962 100644 --- a/.idea/modules.xml +++ b/.idea/modules.xml @@ -8,7 +8,6 @@ - \ No newline at end of file diff --git a/.idea/rotated-consensus.iml b/.idea/rotated-consensus.iml deleted file mode 100644 index 5d2dc0ee..00000000 --- a/.idea/rotated-consensus.iml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - \ No newline at end of file diff --git a/DEVELOPING.md b/DEVELOPING.md index 355dbc8e..271a2181 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -80,6 +80,7 @@ of the `devcapsule` package. See its [README](devcapsule-webconsole/README.md). | Integration: a subsystem with the real executable, subprocess, git or Docker daemon it uses, the rest faked | `nox -s integration`, on demand, and before a candidate; the CLI smoke, types and docs contract are gate checks inside `build` | [Integration tests](engineering-docs/development/integration-tests.md) | | End-to-end, with Docker: images, capsules, the IDE smoke | `nox -s e2e`, `nox -s ide-smoke`, … | [End-to-end tests](engineering-docs/development/e2e-tests.md) | | The capsule web console, `devcapsule-webconsole/`: types and tests in its own environment | `nox -s webconsole`, queued by `build` | [Web console README](devcapsule-webconsole/README.md) | +| A change to the web console, seen in a browser before anything is built | `nox -s webconsole-preview`, which serves this checkout's console on loopback and prints its links | [Trying a change](devcapsule-webconsole/PRESENTATIONS.md#trying-a-change) | The hosted runner runs no Docker; the end-to-end suites run locally and against downloaded candidates during release acceptance. diff --git a/WORKFLOW-LOCAL-humane.md b/WORKFLOW-LOCAL-humane.md index 7fb5308c..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 @@ -206,7 +209,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 +269,104 @@ 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 +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, +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. + +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 d92bdcbb..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 @@ -218,7 +220,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 @@ -227,13 +232,61 @@ 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 + +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. 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 + 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 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/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/assets/docker4pycharm/entrypoint.sh b/devcapsule-src/devcapsule/assets/docker4pycharm/entrypoint.sh index 06316beb..a3856caf 100755 --- a/devcapsule-src/devcapsule/assets/docker4pycharm/entrypoint.sh +++ b/devcapsule-src/devcapsule/assets/docker4pycharm/entrypoint.sh @@ -17,7 +17,7 @@ export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$IDE_PROJECT_STATE_PATH/home/.cache}" export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}" RUN_AS_IDE_USER=() -if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ]; then +if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ] && { [ "$IDE_UID" != "0" ] || [ "$IDE_GID" != "0" ]; }; then if [ "$ENABLE_SUDO" = "1" ] && getent passwd "$IDE_USER" >/dev/null 2>&1; then RUN_AS_IDE_USER=(gosu "$IDE_USER") else @@ -38,7 +38,7 @@ install_ide_file() { local dst="$2" local mode="$3" - if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ]; then + if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ] && { [ "$IDE_UID" != "0" ] || [ "$IDE_GID" != "0" ]; }; then install -o "$IDE_UID" -g "$IDE_GID" -m "$mode" "$src" "$dst" else install -m "$mode" "$src" "$dst" diff --git a/devcapsule-src/devcapsule/assets/pycharm/entrypoint.sh b/devcapsule-src/devcapsule/assets/pycharm/entrypoint.sh index d992407c..0dd43273 100644 --- a/devcapsule-src/devcapsule/assets/pycharm/entrypoint.sh +++ b/devcapsule-src/devcapsule/assets/pycharm/entrypoint.sh @@ -17,7 +17,7 @@ export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$IDE_PROJECT_STATE_PATH/home/.cache}" export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}" RUN_AS_IDE_USER=() -if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ]; then +if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ] && { [ "$IDE_UID" != "0" ] || [ "$IDE_GID" != "0" ]; }; then if [ "$ENABLE_SUDO" = "1" ] && getent passwd "$IDE_USER" >/dev/null 2>&1; then RUN_AS_IDE_USER=(gosu "$IDE_USER") else @@ -38,7 +38,7 @@ install_ide_file() { local dst="$2" local mode="$3" - if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ]; then + if [ "$(id -u)" -eq 0 ] && [ -n "$IDE_UID" ] && [ -n "$IDE_GID" ] && { [ "$IDE_UID" != "0" ] || [ "$IDE_GID" != "0" ]; }; then install -o "$IDE_UID" -g "$IDE_GID" -m "$mode" "$src" "$dst" else install -m "$mode" "$src" "$dst" 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/_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 new file mode 100644 index 00000000..89aaa862 --- /dev/null +++ b/devcapsule-src/devcapsule/commands/_launch_review.py @@ -0,0 +1,427 @@ +"""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. + +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 + +from copy import deepcopy +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 ( + HOME_CAPABILITY_DEFAULTS, authorization_declarations, normalize_authorization_value, render_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", + "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"} +"""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 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 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: + 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, + 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. ``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, + 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 + 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.""" + 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, accepted_at=state.host.now()) + 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..c7abdadd 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 devcapsule.commands._launch_review import ( + 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 -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, @@ -114,268 +57,125 @@ def prepare_launch( output_stream: TextIO | None = None, print_only: bool = False, check_display: bool = True, + home: Mapping[str, Any] | None = None, ) -> 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. + ``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, home=home) 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, + announce=lambda line: print(line, file=sys.stderr), + 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, *, 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. ``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, home=home) + 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. """ - 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 + 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]: """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: """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) - + 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 +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. -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 + ``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()}) - - -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) + settings = load_settings() if home is None else home + return write_settings({"trust": HomeTrust.read(settings).with_channel(channel).document()}, current=settings) def _settle( @@ -383,7 +183,13 @@ def _settle( 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 +197,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 +241,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 +255,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 +283,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 +294,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/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index 48253ed6..e5e13748 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 ( @@ -50,6 +51,7 @@ from devcapsule.configuration.approvals import render_software_approvals, select_software_approvals from devcapsule import notifications from devcapsule import version_sets +from devcapsule.host_daemon import daemon_is_rootless from devcapsule import runtime_configuration from devcapsule.runtime_configuration import CapsuleAccess from devcapsule.compat import CliError, DecisionPending @@ -81,7 +83,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 @@ -597,13 +599,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 +621,18 @@ 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, + 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): @@ -855,38 +833,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 @@ -1328,37 +1288,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 @@ -2204,7 +2144,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 " @@ -2266,14 +2208,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, @@ -2323,16 +2258,27 @@ def prepare_display(base: ImageDetails) -> None: image_labels: Mapping[str, str] = {} realized = None degraded_download = False + rootless_docker = daemon_is_rootless() 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: @@ -2346,7 +2292,11 @@ def prepare_display(base: ImageDetails) -> None: degraded_download = True image = realized.image.reference image_labels = realized.image.labels - checkout_runtime_plan = project_runtime_plan(selected, realized.locked) + checkout_runtime_plan = ( + project_runtime_plan(selected, realized.locked, uid=0, gid=0, user="root") + if rootless_docker + else project_runtime_plan(selected, realized.locked) + ) use_image_process = True action = "Materialized" if realized.created else "Reused" print(f"{action} canonical environment: {image}") @@ -2471,6 +2421,7 @@ def prepare_display(base: ImageDetails) -> None: display_transport=display_transport, web_console=web_console, capsule_platform=lock_platform(lock), + rootless_docker=rootless_docker, ) ) if command_report is not None: diff --git a/devcapsule-src/devcapsule/commands/version.py b/devcapsule-src/devcapsule/commands/version.py index 487bf51d..05651ee2 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, build_info_text, current_build_info from devcapsule.commands.framework import Command __all__ = ["COMMAND", "VersionCommand"] @@ -24,27 +23,10 @@ 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() - 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}") + info = current_build_info() + print(build_info_json(info) if arguments.as_json else build_info_text(info)) return 0 diff --git a/devcapsule-src/devcapsule/configuration/bindings.py b/devcapsule-src/devcapsule/configuration/bindings.py index 315a6703..8dcbce06 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 @@ -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 @@ -144,9 +151,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 +204,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/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/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/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/devcapsule/configuration/derivation.py b/devcapsule-src/devcapsule/configuration/derivation.py index 89afb695..fb2c32c8 100644 --- a/devcapsule-src/devcapsule/configuration/derivation.py +++ b/devcapsule-src/devcapsule/configuration/derivation.py @@ -14,28 +14,40 @@ 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 datetime import datetime, timezone +from functools import cached_property +import os 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 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 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 @@ -47,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, @@ -55,7 +67,27 @@ 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.""" + 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: @@ -102,44 +134,56 @@ 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.""" + host: Host + 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 +222,15 @@ 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, + host_environment=self.host.environment, directory=self.host.directory, ) - 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]: @@ -212,8 +257,65 @@ def with_selection(self, selection: Selection, *, allow_unverified: bool = False return document -def load_state(root: Path, manifest: dict[str, Any]) -> CheckoutState: - return CheckoutState(root, manifest) +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), + environment=dict(os.environ), directory=host_directory) + + +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) + 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: + 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=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)), + ) def register_checkout(state: CheckoutState, *, write: bool = True) -> Path: @@ -222,6 +324,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 +344,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 @@ -265,16 +372,14 @@ 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) 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/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/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/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/console_tools.py b/devcapsule-src/devcapsule/console_tools.py index 732f9a3f..4a94af77 100644 --- a/devcapsule-src/devcapsule/console_tools.py +++ b/devcapsule-src/devcapsule/console_tools.py @@ -12,86 +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], - *, - environ: Mapping[str, str] | None = None, - console_python: Path | None = None, - runtime_plan_path: Path | None = None, - launcher_console_source: Path | None = None, -) -> 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, - ) - 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 cf109568..d9424671 100644 --- a/devcapsule-src/devcapsule/container_runtime/console.py +++ b/devcapsule-src/devcapsule/container_runtime/console.py @@ -16,7 +16,7 @@ from __future__ import annotations -from contextlib import AbstractContextManager +from dataclasses import dataclass from pathlib import Path import socket import sys @@ -33,11 +33,10 @@ "CONSOLE_READY_TIMEOUT_SECONDS", "CONSOLE_ROOT", "CommandWrapper", - "ConnectionProbe", + "ConsoleInstallation", "LAUNCHER_CONSOLE_SOURCE", "RUNTIME_CLI", - "console_child", - "console_package_path", + "probe_address", ] CONSOLE_CHILD = "console" @@ -53,98 +52,102 @@ 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: - """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 :func:`console_package_path`'s choice. - ``console_python``, ``launcher_source``, and ``connect`` replace the - installed paths and TCP readiness probe. + + +@dataclass(frozen=True) +class ConsoleInstallation: + """Where one image keeps the web console: the base's interpreter and the launcher's package. + + 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 - python = Path(CONSOLE_PYTHON) if console_python is None else console_python - if not 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, ...] = ( - str(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) - 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, connect=connect), - 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 "" - - -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 - ) + return {"0.0.0.0": "127.0.0.1", "::": "::1"}.get(listen_address, listen_address) + + +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/display.py b/devcapsule-src/devcapsule/container_runtime/display.py index ea53a9aa..7adb14e0 100644 --- a/devcapsule-src/devcapsule/container_runtime/display.py +++ b/devcapsule-src/devcapsule/container_runtime/display.py @@ -313,7 +313,7 @@ def field(value: bytes) -> bytes: def _own(path: Path, plan: RuntimePlan) -> None: - if os.geteuid() == 0: + if os.geteuid() == 0 and (plan.identity.uid != 0 or plan.identity.gid != 0): os.chown(path, plan.identity.uid, plan.identity.gid) diff --git a/devcapsule-src/devcapsule/container_runtime/entrypoint.py b/devcapsule-src/devcapsule/container_runtime/entrypoint.py index 697d430b..a0b0d26b 100644 --- a/devcapsule-src/devcapsule/container_runtime/entrypoint.py +++ b/devcapsule-src/devcapsule/container_runtime/entrypoint.py @@ -10,39 +10,36 @@ 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``. + +``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 from contextlib import nullcontext -from dataclasses import replace 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 .components import jetbrains +from .console import ConsoleInstallation from .contract import RuntimePlan, RuntimePlanError -from .display import ContainedDisplay, prepare_contained_display -from .filesystem import plan_filesystem, prepare_filesystem -from .graphics import environment as graphics_environment -from .identity import foreground_command +from .display import prepare_contained_display +from .filesystem import prepare_filesystem +from .identity import CapsuleUser +from .session import Session from .supervisor import SupervisedChild, Supervisor, SupervisorError __all__ = [ - "ConsoleBuilder", - "DisplayPreparer", - "LogConfigurer", "SUPERVISOR_LOG_COMPONENT", - "SupervisorFactory", - "SupervisorRunner", "USAGE", - "log_rotation", - "logged_children", "main", "run", ] @@ -56,123 +53,41 @@ 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 - - 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, +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, ) - 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)) - 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 - 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 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) - - 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) - infrastructure = contained.children - console = make_console(plan, wrap_for_user) - if console is not None: - infrastructure = (*infrastructure, console) - if job is None: - child = SupervisedChild( - name=plan.component.id, - command=wrap_for_user(command), - foreground=True, + 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") + os.environ.update(session.launch.environment) + display_children: tuple[SupervisedChild, ...] = () + if session.shows_contained_display: + display = prepare_contained_display( + plan, session.filesystem.environment["XDG_RUNTIME_DIR"], session.user.command, ) - 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=wrap_for_user(job), - foreground=True, - working_directory=plan.project_path, - ) - 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 make_supervisor( - logged_children((*infrastructure, child), log_directory), - log_owner=owner, segment_bytes=segment_bytes, rotations=rotations, + return Supervisor( + 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 920cd6d1..5d84388c 100644 --- a/devcapsule-src/devcapsule/container_runtime/filesystem.py +++ b/devcapsule-src/devcapsule/container_runtime/filesystem.py @@ -2,16 +2,14 @@ from __future__ import annotations -from collections.abc import Callable from dataclasses import dataclass import os from pathlib import Path -from .contract import Identity, RuntimePlan +from .contract import RuntimePlan +from .identity import CapsuleUser -__all__ = ["ChownFunc", "FilesystemPlan", "plan_filesystem", "prepare_filesystem"] - -ChownFunc = Callable[[Path, int, int], None] +__all__ = ["FilesystemPlan", "create_directories", "plan_filesystem", "prepare_filesystem"] @dataclass(frozen=True) @@ -20,7 +18,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 +27,22 @@ 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": 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, - *, - 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 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] = [] @@ -53,8 +51,18 @@ def prepare_filesystem( missing.append(cursor) cursor = cursor.parent path.mkdir(parents=True, exist_ok=True) - if effective_uid == 0: - for created in reversed(missing): - apply_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 b6077bad..4bc90880 100644 --- a/devcapsule-src/devcapsule/container_runtime/identity.py +++ b/devcapsule-src/devcapsule/container_runtime/identity.py @@ -1,29 +1,58 @@ -"""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, - *, - caller_uid: int | None = None, -) -> 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") - effective_uid = os.geteuid() if caller_uid is None else caller_uid - if effective_uid == 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. When the caller + is root and the target identity is already ``0:0`` (as under rootless + Docker, where host UID/GID map to container root), return ``command`` + unchanged rather than invoking ``gosu 0:0``, which ``--cap-drop ALL`` + refuses. + """ + + if not command: + raise ValueError("foreground command must not be empty") + if self.caller_is_root and (self.identity.uid != 0 or self.identity.gid != 0): + 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 and the + target identity is non-root; none otherwise, since the caller owns them + already. + """ + + if not self.caller_is_root or (self.identity.uid == 0 and self.identity.gid == 0): + 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..a06d75d9 --- /dev/null +++ b/devcapsule-src/devcapsule/container_runtime/session.py @@ -0,0 +1,161 @@ +"""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, 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 + +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 preparing the surface, given ``existing``. + + 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(), + } + 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/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/host_daemon.py b/devcapsule-src/devcapsule/host_daemon.py index ff9844e4..afb80343 100644 --- a/devcapsule-src/devcapsule/host_daemon.py +++ b/devcapsule-src/devcapsule/host_daemon.py @@ -231,3 +231,45 @@ def daemon_architecture() -> str: return host_architecture() reported = completed.stdout.strip() return architecture_key(reported) if completed.returncode == 0 and reported else host_architecture() + + +def security_options_indicate_rootless(security_options: Sequence[str] | str) -> bool: + """Return whether Docker daemon ``SecurityOptions`` report rootless mode.""" + + raw_items: Sequence[str] = ( + security_options.splitlines() if isinstance(security_options, str) else security_options + ) + for item in raw_items: + for token in item.split(","): + if token.strip() in {"rootless", "name=rootless"}: + return True + return False + + +def daemon_is_rootless() -> bool: + """Whether the Docker daemon runs in rootless mode. + + Under rootless Docker, host UID/GID are mapped to ``0:0`` inside the + container user namespace, whereas container UID/GID equal to the host IDs + map to subordinate IDs that cannot access ``0600``/``0700`` bind mounts. + Returns ``False`` when the daemon does not answer or runs rootful. + """ + try: + completed = subprocess.run( + ["docker", "info", "--format", "{{json .SecurityOptions}}"], + capture_output=True, text=True, timeout=30, check=False, + ) + except (OSError, subprocess.TimeoutExpired): + return False + reported = completed.stdout.strip() + if completed.returncode != 0 or not reported or reported == "null": + return False + try: + parsed = json.loads(reported) + except ValueError: + return security_options_indicate_rootless(reported) + if not isinstance(parsed, list): + return False + return security_options_indicate_rootless( + [item for item in parsed if isinstance(item, str)] + ) diff --git a/devcapsule-src/devcapsule/images/contract.py b/devcapsule-src/devcapsule/images/contract.py index e2938bab..d5d053ab 100644 --- a/devcapsule-src/devcapsule/images/contract.py +++ b/devcapsule-src/devcapsule/images/contract.py @@ -64,8 +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's own check at start - remains the backstop for a base the launcher could not inspect. + 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/devcapsule/launch/pycharm/_launcher.py b/devcapsule-src/devcapsule/launch/pycharm/_launcher.py index 97bfdb90..9aed1126 100644 --- a/devcapsule-src/devcapsule/launch/pycharm/_launcher.py +++ b/devcapsule-src/devcapsule/launch/pycharm/_launcher.py @@ -242,6 +242,8 @@ class PycharmRunOptions: # caller (commands/project.py); without it the launcher announces the # absence once and plans no console: no port, no token, no wait. web_console: WebConsoleAvailability = WebConsoleAvailability(True, None) + # True only when the host Docker daemon reports rootless mode. + rootless_docker: bool = False @dataclass @@ -312,6 +314,7 @@ class PycharmRunConfig: libgl_always_software: str = "1" mesa_loader_driver_override: str = "llvmpipe" libgl_dri3_disable: str = "1" + rootless_docker: bool = False HOST_NETWORK_UNAVAILABLE_ON_MACOS = ( @@ -991,7 +994,10 @@ def build_run_config(options: PycharmRunOptions, env: Mapping[str, str]) -> Pych # daemon already holds root on its virtual machine, so the group adds # no authority. Elsewhere the host socket file's group applies. socket_gid = HostOs.current().docker_socket_gid - host_docker_gid = socket_gid if socket_gid is not None else host_docker_socket.stat().st_gid + raw_socket_gid = socket_gid if socket_gid is not None else host_docker_socket.stat().st_gid + host_docker_gid = ( + 0 if options.rootless_docker and raw_socket_gid == host_user.gid else raw_socket_gid + ) if enable_sudo: while ide_sudo_gid in {0, host_user.gid, host_docker_gid}: @@ -1211,6 +1217,7 @@ def build_run_config(options: PycharmRunOptions, env: Mapping[str, str]) -> Pych env.get("MESA_LOADER_DRIVER_OVERRIDE", "llvmpipe"), ), libgl_dri3_disable=env.get("PYCHARM_LIBGL_DRI3_DISABLE", env.get("LIBGL_DRI3_DISABLE", "1")), + rootless_docker=options.rootless_docker, ) @@ -1326,6 +1333,10 @@ def build_docker_args( # launcher is not a case this product has; the recursive dogfood holds # its successor's launcher open exactly as a developer holds `project run`. host_user = current_host_user() + rootless = bool(getattr(config, "rootless_docker", False)) + container_uid, container_gid, container_user = ( + (0, 0, "root") if rootless else (host_user.uid, host_user.gid, host_user.name) + ) args = [ "--rm", "-i", @@ -1358,11 +1369,11 @@ def build_docker_args( "--env", "IDE_PROJECT_STATE_PATH=/ide-project-state", "--env", - f"IDE_UID={host_user.uid}", + f"IDE_UID={container_uid}", "--env", - f"IDE_GID={host_user.gid}", + f"IDE_GID={container_gid}", "--env", - f"IDE_USER={host_user.name}", + f"IDE_USER={container_user}", "--env", f"LIBGL_ALWAYS_SOFTWARE={config.libgl_always_software}", "--env", @@ -1589,12 +1600,16 @@ def _display_mount_args(config: PycharmRunConfig, files: TempRuntimeFiles) -> li def append_docker_mode_args(args: list[str], config: PycharmRunConfig, host_user: HostUser) -> None: + rootless = bool(getattr(config, "rootless_docker", False)) + container_uid, container_gid = ( + (0, 0) if rootless else (host_user.uid, host_user.gid) + ) if config.docker_mode == "host": print_host_docker_warning(config) args.extend( [ "--user", - f"{host_user.uid}:{host_user.gid}", + f"{container_uid}:{container_gid}", "--group-add", str(config.host_docker_gid), "--env", @@ -1631,7 +1646,7 @@ def append_docker_mode_args(args: list[str], config: PycharmRunConfig, host_user args.extend( [ "--user", - f"{host_user.uid}:{host_user.gid}", + f"{container_uid}:{container_gid}", "--env", "ENABLE_DIND=0", "--env", @@ -1839,37 +1854,54 @@ def write_xauthority(xauth_file: Path, env: Mapping[str, str]) -> None: def write_user_files(config: PycharmRunConfig, files: TempRuntimeFiles) -> None: - host_user = current_host_user() - files.passwd_file.write_text( - "\n".join( - [ - "root:x:0:0:root:/root:/bin/bash", - f"{host_user.name}:x:{host_user.uid}:{host_user.gid}:PyCharm Docker User:/home/devcapsule:/bin/bash", - "", - ] + if bool(getattr(config, "rootless_docker", False)): + files.passwd_file.write_text( + "root:x:0:0:PyCharm Docker User:/home/devcapsule:/bin/bash\n" ) - ) - group_lines = [ - "root:x:0:", - f"{host_user.group_name}:x:{host_user.gid}:", - ] - if config.host_docker_gid not in (None, 0, host_user.gid): - group_lines.append(f"host-docker:x:{config.host_docker_gid}:") - if config.enable_sudo: - group_lines.append(f"ide-sudo:x:{config.ide_sudo_gid}:{host_user.name}") - files.shadow_file = make_temp(files.group_file.parent, "pycharm-docker-shadow.") - shadow_last_change = int(time.time()) // 86400 - files.shadow_file.write_text( + group_lines = ["root:x:0:"] + if config.host_docker_gid not in (None, 0): + group_lines.append(f"host-docker:x:{config.host_docker_gid}:") + if config.enable_sudo: + group_lines.append(f"ide-sudo:x:{config.ide_sudo_gid}:root") + files.shadow_file = make_temp(files.group_file.parent, "pycharm-docker-shadow.") + shadow_last_change = int(time.time()) // 86400 + files.shadow_file.write_text( + f"root:*:{shadow_last_change}:0:99999:7:::\n" + ) + files.shadow_file.chmod(0o600) + files.group_file.write_text("\n".join([*group_lines, ""])) + else: + host_user = current_host_user() + files.passwd_file.write_text( "\n".join( [ - f"root:*:{shadow_last_change}:0:99999:7:::", - f"{host_user.name}:*:{shadow_last_change}:0:99999:7:::", + "root:x:0:0:root:/root:/bin/bash", + f"{host_user.name}:x:{host_user.uid}:{host_user.gid}:PyCharm Docker User:/home/devcapsule:/bin/bash", "", ] ) ) - files.shadow_file.chmod(0o600) - files.group_file.write_text("\n".join([*group_lines, ""])) + group_lines = [ + "root:x:0:", + f"{host_user.group_name}:x:{host_user.gid}:", + ] + if config.host_docker_gid not in (None, 0, host_user.gid): + group_lines.append(f"host-docker:x:{config.host_docker_gid}:") + if config.enable_sudo: + group_lines.append(f"ide-sudo:x:{config.ide_sudo_gid}:{host_user.name}") + files.shadow_file = make_temp(files.group_file.parent, "pycharm-docker-shadow.") + shadow_last_change = int(time.time()) // 86400 + files.shadow_file.write_text( + "\n".join( + [ + f"root:*:{shadow_last_change}:0:99999:7:::", + f"{host_user.name}:*:{shadow_last_change}:0:99999:7:::", + "", + ] + ) + ) + files.shadow_file.chmod(0o600) + files.group_file.write_text("\n".join([*group_lines, ""])) files.passwd_file.chmod(0o644) files.group_file.chmod(0o644) @@ -1882,6 +1914,10 @@ def ensure_sudoers_policy_ownership( policy = files.sudoers_file if not config.enable_sudo or policy is None: raise PycharmRunError("Development sudo requires a generated sudoers policy.") + if bool(getattr(config, "rootless_docker", False)): + # Rootless Docker maps files owned by the host user directly to 0:0 + # inside the container while host-side st_uid remains the host UID. + return if not HostOs.current().chown_reaches_bind_mounts: files.sudoers_volume = prepare_sudoers_policy_volume(config, policy, env) return 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/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/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/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/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/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/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/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/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/devcapsule/logs.py b/devcapsule-src/devcapsule/logs.py index ec41310d..af369f3f 100644 --- a/devcapsule-src/devcapsule/logs.py +++ b/devcapsule-src/devcapsule/logs.py @@ -282,9 +282,9 @@ def events_logger(component: str) -> logging.Logger: def own(path: Path, owner: Owner) -> None: - """Give ``path`` to ``owner`` when this process is root; a no-op otherwise.""" + """Give ``path`` to ``owner`` when this process is root and ownership differs.""" - if owner is not None and os.geteuid() == 0: + if owner is not None and os.geteuid() == 0 and owner != (os.geteuid(), os.getegid()): os.chown(path, owner[0], owner[1]) 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/devcapsule/recursive_successor.py b/devcapsule-src/devcapsule/recursive_successor.py index b07c9ee3..bfaa0772 100644 --- a/devcapsule-src/devcapsule/recursive_successor.py +++ b/devcapsule-src/devcapsule/recursive_successor.py @@ -13,6 +13,7 @@ from typing import Any, Callable, Mapping, Sequence from devcapsule.build_info import current_build_info +from devcapsule.host_daemon import daemon_is_rootless from devcapsule.launch.pycharm import DockerMode, PycharmRunOptions from devcapsule.launch.pycharm._launcher import ( PycharmRunError, @@ -154,7 +155,12 @@ def launch_successor( selected = fresh_resolved_project(checkout) realized = realize_environment(selected) - runtime_plan = project_runtime_plan(selected, realized.locked) + rootless_docker = daemon_is_rootless() + runtime_plan = ( + project_runtime_plan(selected, realized.locked, uid=0, gid=0, user="root") + if rootless_docker + else project_runtime_plan(selected, realized.locked) + ) source_revision = current_build_info().source_revision name = successor_container_name(run_id) options = _resolved_run_options( @@ -165,6 +171,7 @@ def launch_successor( run_id=run_id, source_revision=source_revision, image_labels=realized.image.labels, + rootless_docker=rootless_docker, ) config = build_run_config(options, env) successor_display_url: str | None = None @@ -189,7 +196,7 @@ def launch_successor( args = build_docker_args(config, files, launch_env) context = _launch_context(report, config.persistent_home, args) host_args = _translate_bind_sources(args, context) - if files.sudoers_file is not None: + if files.sudoers_file is not None and not rootless_docker: _make_root_owned(files.sudoers_file, launch_env) plan = _expected_plan(host_args, files, realized) _write_expected_plan(run_root, plan) @@ -473,6 +480,7 @@ def _resolved_run_options( run_id: str, source_revision: str, image_labels: Mapping[str, str] | None = None, + rootless_docker: bool = False, ) -> PycharmRunOptions: runtime = selected.resolution.get("runtime", {}) state_root = selected.resolution.get("state", {}) @@ -544,6 +552,7 @@ def _resolved_run_options( "--label", f"devcapsule.e2e.role={SUCCESSOR_ROLE}", ], + rootless_docker=rootless_docker, ) diff --git a/devcapsule-src/noxfile.py b/devcapsule-src/noxfile.py index 65a00ba0..512e03b5 100644 --- a/devcapsule-src/noxfile.py +++ b/devcapsule-src/noxfile.py @@ -5,6 +5,7 @@ import hashlib import uuid import argparse +import secrets import shutil from pathlib import Path @@ -23,6 +24,8 @@ PEX_UNDER_TEST_ENV = "DEVCAPSULE_PEX_UNDER_TEST" VERSION_SCRIPT = PROJECT_ROOT / "scripts" / "bump-version.py" WEBCONSOLE_ROOT = REPO_ROOT / "devcapsule-webconsole" +WEBCONSOLE_PREVIEW_PORT = 8787 +WEBCONSOLE_SAMPLE_PRESENTATION = "devcapsule-webconsole/resources/presentations/todo-fastapi-postgres-react" def install_locked(session: nox.Session) -> None: @@ -532,6 +535,41 @@ def webconsole(session: nox.Session) -> None: run_webconsole_checks(session) +@nox.session(name="webconsole-preview", python="3.12") +def webconsole_preview(session: nox.Session) -> None: + """Serve this checkout's web console on loopback, to try a change before building; Ctrl+C ends it. + + The console is installed editable, so an edit to a page, a script or a + stylesheet shows on a browser reload. ``-- --project `` serves + another DevCapsule project than this repository and ``-- --port `` + another port. The links logged carry a token made for this run; the + console refuses every request without it. + """ + arguments = argparse.ArgumentParser(prog="nox -s webconsole-preview --") + arguments.add_argument("--project", type=Path, default=REPO_ROOT) + arguments.add_argument("--port", type=int, default=WEBCONSOLE_PREVIEW_PORT) + options = arguments.parse_args(session.posargs) + project = options.project.resolve() + session.install("--require-hashes", "-r", str(WEBCONSOLE_ROOT / "requirements-dev.txt")) + session.install("-e", str(WEBCONSOLE_ROOT), "--no-deps") + # The launcher too: the pages show what its commands report about the project. + session.install("-e", str(PROJECT_ROOT)) + state = Path(session.create_tmp()) + token = secrets.token_hex(24) + token_file = state / "console-token" + token_file.write_text(token + "\n", encoding="utf-8") + token_file.chmod(0o600) + origin = f"http://127.0.0.1:{options.port}" + session.log(f"Web console: {origin}/?token={token}") + if project == REPO_ROOT: + session.log(f"Sample presentation: {origin}/presentations/{WEBCONSOLE_SAMPLE_PRESENTATION}?token={token}") + session.run( + "python", "-m", "devcapsule_webconsole", "--project", str(project), "--token-file", str(token_file), + "--decisions", str(state / "decisions"), "--configuration", str(state / "configuration"), + "--port", str(options.port), + ) + + @nox.session(name="docs-contract", python=False) def docs_contract(session: nox.Session) -> None: """Run only the website content-contract check against this checkout.""" 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/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/scripts/validate_unittests_follow_conventions.py b/devcapsule-src/scripts/validate_unittests_follow_conventions.py index 58ed1022..642ed8dd 100644 --- a/devcapsule-src/scripts/validate_unittests_follow_conventions.py +++ b/devcapsule-src/scripts/validate_unittests_follow_conventions.py @@ -16,11 +16,21 @@ 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 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 +44,8 @@ import os import subprocess import sys +import textwrap +from collections.abc import Iterable, Sequence from dataclasses import dataclass, field from pathlib import Path @@ -53,7 +65,26 @@ UNIT_MIRROR = Path("tests") / "unit" """The directory that mirrors ``devcapsule-src`` for unit tests.""" -_EXCLUDED_PARTS = frozenset({"resources"}) +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", "evidence"}) @dataclass(frozen=True) @@ -68,6 +99,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 +125,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 +218,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 +253,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 @@ -202,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}" @@ -218,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, @@ -242,19 +427,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 +480,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..755bcfdb --- /dev/null +++ b/devcapsule-src/tests/command_line_debt.txt @@ -0,0 +1,11 @@ +# 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 diff --git a/devcapsule-src/tests/conftest.py b/devcapsule-src/tests/conftest.py index 1350f921..a6e12632 100644 --- a/devcapsule-src/tests/conftest.py +++ b/devcapsule-src/tests/conftest.py @@ -1,38 +1,98 @@ 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 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 two guards, and give a macOS run a short temporary root. + + 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 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) + 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) _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 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: - """Remove the short temporary root this session created, once every test passed. + """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 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 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 + 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) @@ -78,21 +138,31 @@ def amd64_linux_host_by_default(request: pytest.FixtureRequest, monkeypatch: pyt monkeypatch.setattr("devcapsule.platforms.host_architecture", lambda: "amd64") for module in ("environment_realization", "images.build", "launch.pycharm._launcher"): monkeypatch.setattr(f"devcapsule.{module}.daemon_architecture", lambda: "amd64") + for module in ("commands.project", "recursive_successor"): + monkeypatch.setattr(f"devcapsule.{module}.daemon_is_rootless", lambda: False) DOCKER_MARKERS = ("e2e", "base_build_e2e", "recursive_e2e", "contributor_e2e", "ide_smoke", "docker") """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``.""" 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, @@ -101,16 +171,20 @@ 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): 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 @@ -128,6 +202,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 @@ -142,3 +222,262 @@ 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 + + +# 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/e2e/scenario_presentation.py b/devcapsule-src/tests/e2e/scenario_presentation.py new file mode 100644 index 00000000..254439a3 --- /dev/null +++ b/devcapsule-src/tests/e2e/scenario_presentation.py @@ -0,0 +1,382 @@ +"""The presentation of a recorded scenario: ``presentation.json`` beside its recording. + +The web console shows a folder that holds a ``presentation.json`` as slides +beside the recording: an overview, then one slide per step with the step's +text, its screenshot, and its part of the video with captions. The document's +contract is ``devcapsule-webconsole/PRESENTATIONS.md``. This module writes +that document from what a recorded scenario already has, so that a recording +needs no hand-made data to be presented: + +- the scenario's JSON: ``id``, ``title``, ``description``, ``script`` (the + path of its script below ``tests/e2e``) and ``actions``; +- the script, a Markdown file in the form + ``engineering-docs/development/running-e2e-scenario-recordings.md`` gives: + the goal, the stack, what the scenario illustrates, and the numbered steps + with the user's action and the expected observation; +- the count of frames the recorder had taken after each action. + +An action belongs to the step whose number starts its ``reason`` ("3. Save +the file"). A step's captions come from its actions: when none of them has a +``caption``, every action's reason, without the number, is its caption; when +some have, a caption starts at each action that has one and lasts until the +next, and the step's first action must have one. + +Public operations: ``parse_script``, ``plan_presentation``, +``PresentationPlan.timed``, ``plan_for_scenario`` and ``write_presentation``. +They raise ``PresentationError`` for a script or a scenario that cannot be +presented; the message names what to correct. +""" +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +import json +from pathlib import Path +import re +from typing import Any + +__all__ = [ + "E2E_ROOT", + "PRESENTATION_FILE", + "PresentationError", + "PresentationPlan", + "Script", + "ScriptStep", + "parse_script", + "plan_for_scenario", + "plan_presentation", + "write_presentation", +] + +E2E_ROOT = Path(__file__).resolve().parent +"""A scenario's ``script`` path is relative to this directory.""" +PRESENTATION_FILE = "presentation.json" +SCHEMA_VERSION = 1 + +_SECTIONS = ("Goal", "Stack And Capabilities", "What It Illustrates", "Steps") +_HEADING = re.compile(r"^## (?P.+?)\s*$") +_STEP = re.compile(r"^(?P\d+)\. \*\*(?P.+?)\*\*\s*$") +_FIELD = re.compile(r"^\s+- \*(?P<name>User action|Expected observation):\*\s+(?P<text>.+?)\s*$") +_STACK_ROW = re.compile(r"^- \*\*(?P<name>.+?):\*\*\s+(?P<detail>.+?)\s*$") +_BULLET = re.compile(r"^- (?P<text>.+?)\s*$") +_CONTINUATION = re.compile(r"^\s+(?P<text>\S.*?)\s*$") +_STEP_NUMBER = re.compile(r"^(?P<number>\d+)\.\s+(?P<text>\S.*)$", re.DOTALL) + + +class PresentationError(ValueError): + """A script or a scenario cannot be presented; the message names what to correct.""" + + +@dataclass(frozen=True) +class ScriptStep: + """One numbered step of a script.""" + + title: str + action: str + expected: str + + +@dataclass(frozen=True) +class Script: + """What a scenario's script says, section by section.""" + + goal: str + stack: tuple[tuple[str, str], ...] + illustrates: tuple[str, ...] + steps: tuple[ScriptStep, ...] + + +def parse_script(text: str) -> Script: + """The script a Markdown ``text`` in the script form states. + + The form: ``## Goal``, one paragraph; ``## Stack And Capabilities``, + optional, bullets ``- **Name:** detail``; ``## What It Illustrates``, + optional, bullets; ``## Steps``, items ``N. **Title.**`` numbered from 1, + each with the sub-bullets ``- *User action:* …`` and + ``- *Expected observation:* …``. A bullet may continue on indented lines. + Text before the first ``##`` heading is not read. Any other ``##`` + heading, a missing ``Goal`` or ``Steps``, a step out of order or without + both sub-bullets, and a line that fits nowhere are refused. + """ + sections: dict[str, list[tuple[int, str]]] = {} + current: list[tuple[int, str]] | None = None + for number, line in enumerate(text.splitlines(), start=1): + heading = _HEADING.match(line) + if heading is not None: + name = heading.group("name") + if name not in _SECTIONS: + raise PresentationError( + f"script line {number}: section {name!r} is not one of {', '.join(_SECTIONS)}" + ) + if name in sections: + raise PresentationError(f"script line {number}: section {name!r} appears twice") + current = sections[name] = [] + elif current is not None and line.strip(): + current.append((number, line)) + for required in ("Goal", "Steps"): + if not sections.get(required): + raise PresentationError(f"script: section {required!r} is missing or empty") + goal = " ".join(line.strip() for _, line in sections["Goal"]) + stack = tuple( + _stack_row(number, item) for number, item in _bullets(sections.get("Stack And Capabilities", []), "Stack And Capabilities") + ) + illustrates = tuple(item for _, item in _bullets(sections.get("What It Illustrates", []), "What It Illustrates")) + return Script(goal=goal, stack=stack, illustrates=illustrates, steps=_steps(sections["Steps"])) + + +def _bullets(lines: Sequence[tuple[int, str]], section: str) -> list[tuple[int, str]]: + """The bullets of a section, each with its first line's number, continuations joined.""" + items: list[tuple[int, str]] = [] + for number, line in lines: + bullet = _BULLET.match(line) + continuation = _CONTINUATION.match(line) + if bullet is not None: + items.append((number, bullet.group("text"))) + elif continuation is not None and items: + first, so_far = items[-1] + items[-1] = (first, f"{so_far} {continuation.group('text')}") + else: + raise PresentationError(f"script line {number}: {section!r} takes bullets, '- text'") + return items + + +def _stack_row(number: int, item: str) -> tuple[str, str]: + row = _STACK_ROW.match(f"- {item}") + if row is None: + raise PresentationError(f"script line {number}: a stack bullet is '- **Name:** detail'") + return row.group("name"), row.group("detail") + + +def _steps(lines: Sequence[tuple[int, str]]) -> tuple[ScriptStep, ...]: + steps: list[dict[str, str]] = [] + field: str | None = None + for number, line in lines: + step = _STEP.match(line) + named = _FIELD.match(line) + continuation = _CONTINUATION.match(line) + if step is not None: + if int(step.group("number")) != len(steps) + 1: + raise PresentationError(f"script line {number}: expected step {len(steps) + 1}, found {step.group('number')}") + steps.append({"title": step.group("title").rstrip(".").strip()}) + field = None + elif named is not None and steps: + field = named.group("name") + if field in steps[-1]: + raise PresentationError(f"script line {number}: step {len(steps)} states {field!r} twice") + steps[-1][field] = named.group("text") + elif continuation is not None and steps and field is not None: + steps[-1][field] = f"{steps[-1][field]} {continuation.group('text')}" + else: + raise PresentationError( + f"script line {number}: a step is 'N. **Title.**' with '- *User action:* …' and '- *Expected observation:* …'" + ) + for index, step_fields in enumerate(steps, start=1): + for required in ("User action", "Expected observation"): + if required not in step_fields: + raise PresentationError(f"script: step {index} has no {required!r}") + if not step_fields["title"]: + raise PresentationError(f"script: step {index} has no title") + return tuple( + ScriptStep(title=item["title"], action=item["User action"], expected=item["Expected observation"]) for item in steps + ) + + +@dataclass(frozen=True) +class _Caption: + """A caption and the actions it lasts for, as indexes into the scenario's actions.""" + + first_action: int + last_action: int + text: str + + +@dataclass(frozen=True) +class _PlannedStep: + step: ScriptStep + first_action: int + last_action: int + captions: tuple[_Caption, ...] + + +@dataclass(frozen=True) +class PresentationPlan: + """Everything of a presentation that is known before the scenario runs. + + ``plan_presentation`` makes it; ``timed`` adds what only a run knows. + """ + + scenario_id: str + title: str + summary: str + script: Script + action_count: int + steps: tuple[_PlannedStep, ...] + + def timed( + self, + frames_after_actions: Sequence[int], + total_frames: int, + frames_per_second: int, + *, + video: str, + poster: str, + screenshots: Sequence[str], + ) -> dict[str, Any]: + """The presentation document of one recorded run of the planned scenario. + + ``frames_after_actions[i]`` is the count of frames recorded when + action ``i`` had finished, ``total_frames`` the count in the video, + which plays ``frames_per_second`` of them, and ``screenshots[i]`` the + file taken after action ``i``. A step runs from the end of the step + before it, the first from the start of the video, to the end of its + last action, the last to the end of the video; its screenshot is its + last action's. Refuses counts that do not match the plan, that + decrease, that exceed the total, or that leave a step or a caption + without a frame. + """ + if len(frames_after_actions) != self.action_count or len(screenshots) != self.action_count: + raise PresentationError( + f"the run has {len(frames_after_actions)} frame counts and {len(screenshots)} screenshots " + f"for {self.action_count} actions" + ) + if frames_per_second <= 0: + raise PresentationError(f"frames per second must be positive, not {frames_per_second}") + counts = list(frames_after_actions) + if any(later < earlier for earlier, later in zip([0, *counts], [*counts, total_frames])): + raise PresentationError("the frame counts decrease or exceed the total number of frames") + last_action = self.action_count - 1 + + def seconds(frames: int) -> float: + return round(frames / frames_per_second, 3) + + def starts(action: int) -> int: + return 0 if action == 0 else counts[action - 1] + + def ends(action: int) -> int: + return total_frames if action == last_action else counts[action] + + steps = [] + for number, planned in enumerate(self.steps, start=1): + if any(starts(caption.first_action) >= ends(caption.last_action) for caption in planned.captions): + raise PresentationError(f"step {number} has a caption that lasts no frame") + captions = [ + {"start": seconds(starts(caption.first_action)), "end": seconds(ends(caption.last_action)), "text": caption.text} + for caption in planned.captions + ] + steps.append({ + "title": planned.step.title, + "action": planned.step.action, + "expected": planned.step.expected, + "screenshot": screenshots[planned.last_action], + "start": seconds(starts(planned.first_action)), + "end": seconds(ends(planned.last_action)), + "captions": captions, + }) + overview: dict[str, Any] = {"summary": self.summary, "intent": self.script.goal} + if self.script.illustrates: + overview["illustrates"] = list(self.script.illustrates) + if self.script.stack: + overview["stack"] = [{"name": name, "detail": detail} for name, detail in self.script.stack] + return { + "schema_version": SCHEMA_VERSION, + "scenario_id": self.scenario_id, + "title": self.title, + "overview": overview, + "video": {"file": video, "poster": poster, "duration": seconds(total_frames)}, + "steps": steps, + } + + +def plan_presentation(scenario: Mapping[str, Any], script: Script) -> PresentationPlan: + """Join a scenario's JSON document to its parsed script, or say why they do not join. + + The scenario needs a non-empty ``id``, ``title`` and ``description``. Each + action's ``reason`` starts with the number of its step and a period; the + numbers never decrease and every step of the script has at least one + action. ``caption``, where an action has it, is a non-empty string, and a + step with any caption has one on its first action. + """ + texts = {} + for key in ("id", "title", "description"): + value = scenario.get(key) + if not isinstance(value, str) or not value.strip(): + raise PresentationError(f"the scenario has no {key}") + texts[key] = value.strip() + actions = scenario.get("actions") + if not isinstance(actions, list) or not actions: + raise PresentationError("the scenario has no actions") + numbers: list[int] = [] + reasons: list[str] = [] + captions: list[str | None] = [] + for position, action in enumerate(actions, start=1): + if not isinstance(action, Mapping): + raise PresentationError(f"action {position} is not an object") + reason = action.get("reason") + numbered = _STEP_NUMBER.match(reason) if isinstance(reason, str) else None + if numbered is None: + raise PresentationError(f"action {position}: its reason must start with the number of its step, as in '3. Save the file'") + number = int(numbered.group("number")) + if not 1 <= number <= len(script.steps): + raise PresentationError(f"action {position} names step {number}; the script has steps 1 to {len(script.steps)}") + if numbers and number < numbers[-1]: + raise PresentationError(f"action {position} names step {number} after an action of step {numbers[-1]}") + caption = action.get("caption") + if caption is not None and (not isinstance(caption, str) or not caption.strip()): + raise PresentationError(f"action {position}: its caption must be a non-empty text") + numbers.append(number) + reasons.append(numbered.group("text").strip()) + captions.append(caption.strip() if isinstance(caption, str) else None) + planned: list[_PlannedStep] = [] + for number, step in enumerate(script.steps, start=1): + members = [index for index, owner in enumerate(numbers) if owner == number] + if not members: + raise PresentationError(f"step {number} of the script has no action") + planned.append(_PlannedStep( + step=step, first_action=members[0], last_action=members[-1], captions=_captions(number, members, reasons, captions), + )) + return PresentationPlan( + scenario_id=texts["id"], title=texts["title"], summary=texts["description"], script=script, + action_count=len(actions), steps=tuple(planned), + ) + + +def _captions(number: int, members: Sequence[int], reasons: Sequence[str], captions: Sequence[str | None]) -> tuple[_Caption, ...]: + """The captions of one step's actions, by the rule in the module's documentation.""" + written = [index for index in members if captions[index] is not None] + if not written: + return tuple(_Caption(first_action=index, last_action=index, text=reasons[index]) for index in members) + if written[0] != members[0]: + raise PresentationError( + f"step {number} has captions, so its first action, action {members[0] + 1}, needs one" + ) + ends = [*(index - 1 for index in written[1:]), members[-1]] + return tuple( + _Caption(first_action=first, last_action=last, text=str(captions[first])) for first, last in zip(written, ends) + ) + + +def plan_for_scenario(scenario: Mapping[str, Any], root: Path = E2E_ROOT) -> PresentationPlan | None: + """The plan of a scenario that names its ``script``, read below ``root``; None for one that names none. + + A scenario without a script is recorded without a presentation. A script + that is named and cannot be read, or that does not join the scenario, is + an error: call this before the scenario runs, so the recording is not + made in vain. + """ + named = scenario.get("script") + if named is None: + return None + if not isinstance(named, str) or not named.strip() or Path(named).is_absolute() or ".." in Path(named).parts: + raise PresentationError(f"the scenario's script {named!r} is not a path below {root}") + try: + text = (root / named).read_text(encoding="utf-8") + except OSError as error: + raise PresentationError(f"the scenario's script {named!r} cannot be read below {root}: {error}") from error + return plan_presentation(scenario, parse_script(text)) + + +def write_presentation(evidence: Path, document: Mapping[str, Any]) -> Path: + """Write ``document`` as ``presentation.json`` in the ``evidence`` folder and return its path.""" + path = evidence / PRESENTATION_FILE + path.write_text(json.dumps(document, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") + return path diff --git a/devcapsule-src/tests/e2e/scenario_recorder.py b/devcapsule-src/tests/e2e/scenario_recorder.py index a8dd8352..3a429405 100644 --- a/devcapsule-src/tests/e2e/scenario_recorder.py +++ b/devcapsule-src/tests/e2e/scenario_recorder.py @@ -14,13 +14,15 @@ seeds the scenario's project files into ``session.workspace``, executes its recorded ``ActionStep`` sequence, and produces ``scenario-video.webm``, ``agent-desktop-raw.webm``, ``step-NNN.png`` screenshots, and - ``scenario-result.json``. + ``scenario-result.json``. A scenario that names its ``script`` also gets + ``presentation.json``, which the web console shows as slides beside the + recording; ``scenario_presentation`` writes it. """ from __future__ import annotations import argparse import base64 -from dataclasses import asdict, dataclass +from dataclasses import asdict, dataclass, field from http.server import BaseHTTPRequestHandler, HTTPServer import json import os @@ -36,6 +38,7 @@ from tests.e2e.ai_driver import DriverError from tests.e2e.browser_session import smoke_browser +from tests.e2e.scenario_presentation import plan_for_scenario, write_presentation from tests.e2e.ide_session import ( SURFACES, IdeSurface, @@ -47,7 +50,10 @@ ) 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") +VIDEO_FRAMES_PER_SECOND = 12 +"""The rate ``scenario-video.webm`` plays the recorded frames at.""" MAX_WAIT_MS = 30_000 """Longest ``wait`` step; ``seconds`` is accepted up to the same bound.""" CONTROLLER_COMMAND_TIMEOUT = 120.0 @@ -179,7 +185,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) @@ -207,6 +213,8 @@ class ScenarioSpec: description: str seed_files: dict[str, str] actions: tuple[ActionStep, ...] + document: dict[str, Any] = field(default_factory=dict, compare=False) + """The scenario's JSON as loaded: ``scenario_presentation`` reads its ``script`` and the actions' captions.""" @classmethod def from_dict(cls, data: dict[str, Any]) -> ScenarioSpec: @@ -236,6 +244,7 @@ def from_dict(cls, data: dict[str, Any]) -> ScenarioSpec: description=description, seed_files=dict(raw_seeds), actions=actions, + document=dict(data), ) @@ -281,6 +290,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}" </dev/null >/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 +337,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 +371,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}") @@ -338,7 +384,7 @@ def encode_webm( page: Any, output_webm: Path, container: str | None = None, - fps: int = 12, + fps: int = VIDEO_FRAMES_PER_SECOND, timeout: float = 60.0, ) -> bool: """Encode the recorded PNG frames into a pause-free VP8 WebM through ``ffmpeg``. @@ -457,6 +503,8 @@ def run_scenario_replay( """Seed ``spec`` into ``session.workspace``, replay its actions, and record video.""" from playwright.sync_api import sync_playwright # type: ignore[import-not-found,unused-ignore] + # Before anything is recorded: a script that does not join the scenario fails here. + presentation = plan_for_scenario(spec.document) evidence.mkdir(parents=True, exist_ok=True) seed_scenario_workspace(session.workspace, spec) recorder = BurstFrameRecorder(evidence / "video-frames") @@ -467,6 +515,7 @@ def run_scenario_replay( executed: list[dict[str, Any]] = [] step_screenshots: list[str] = [] + frames_after_actions: list[int] = [] with sync_playwright() as playwright, smoke_browser(playwright, session, evidence) as browser: viewport = {"width": 1600, "height": 1000} @@ -486,7 +535,8 @@ 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) + frames_after_actions.append(recorder.frame_count) executed.append(asdict(step)) shot = evidence / f"step-{index:03d}.png" page.screenshot(path=str(shot)) @@ -506,6 +556,12 @@ def run_scenario_replay( video.save_as(str(evidence / "agent-desktop-raw.webm")) video.delete() + presented = encoded and presentation is not None + if encoded and presentation is not None: + write_presentation(evidence, presentation.timed( + frames_after_actions, recorder.frame_count, VIDEO_FRAMES_PER_SECOND, + video="scenario-video.webm", poster="poster.png", screenshots=step_screenshots, + )) result = { "scenario_id": spec.id, "surface": spec.surface, @@ -514,6 +570,7 @@ def run_scenario_replay( "steps_executed": len(executed), "frames_recorded": recorder.frame_count, "pause_free_webm": "scenario-video.webm" if encoded else None, + "presentation": "presentation.json" if presented else None, "raw_webm": "agent-desktop-raw.webm", "screenshots": step_screenshots, } @@ -680,7 +737,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 +819,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/<scenario-id>)", + ) 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 +833,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/<scenario-id>)", + ) replay_p.add_argument("--pex", type=Path, required=True, help="Path to devcapsule PEX executable") args = parser.parse_args(argv) @@ -781,7 +848,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 +864,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/scenarios/todo-fastapi-postgres-react.json b/devcapsule-src/tests/e2e/scenarios/todo-fastapi-postgres-react.json new file mode 100644 index 00000000..e78b5744 --- /dev/null +++ b/devcapsule-src/tests/e2e/scenarios/todo-fastapi-postgres-react.json @@ -0,0 +1,319 @@ +{ + "id": "todo-fastapi-postgres-react", + "surface": "codium", + "title": "Full-stack work in one capsule: FastAPI, PostgreSQL 17 and React", + "description": "A developer opens a todo application in VSCodium inside a DevCapsule, finishes its backend endpoint and its React handler, starts the stack from the editor's terminal, uses the application in Chromium on the same desktop, and checks with `psql` that the rows are in PostgreSQL.", + "script": "scripts/todo-fastapi-postgres-react.md", + "actions": [ + { + "action": "click", + "x": 1575, + "y": 86, + "reason": "1. Close empty secondary sidebar in VSCodium", + "caption": "VSCodium is open on the capsule's desktop, with the project in the explorer." + }, + { + "action": "click", + "x": 670, + "y": 50, + "reason": "1. Click Manage on Workspace Trust banner", + "caption": "Trust the workspace, so the editor's features are all enabled." + }, + { + "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", + "caption": "Quick Open (`Ctrl+P`) finds `backend/main.py`." + }, + { + "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", + "caption": "Go to Line (`Ctrl+G`) jumps to line 75, inside `create_todo`." + }, + { + "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", + "caption": "Type the handler: a parameterized `INSERT … RETURNING`, then the row as JSON." + }, + { + "action": "press", + "text": "Control+s", + "reason": "2. Save backend/main.py", + "caption": "Save (`Ctrl+S`). The endpoint that creates a task is complete." + }, + { + "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", + "caption": "Quick Open (`Ctrl+P`) finds `frontend/src/App.jsx`." + }, + { + "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", + "caption": "Go to Line (`Ctrl+G`) jumps to line 30, inside `handleCreate`." + }, + { + "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", + "caption": "Type the handler: `POST` the new task to `/api/todos`, then add the returned row to the list." + }, + { + "action": "press", + "text": "Control+s", + "reason": "3. Save frontend/src/App.jsx", + "caption": "Save (`Ctrl+S`). The form now talks to the backend." + }, + { + "action": "wait", + "ms": 900, + "reason": "3. Hold on completed React handleCreate implementation" + }, + { + "action": "press", + "text": "Control+Backquote", + "reason": "4. Open VSCodium integrated terminal", + "caption": "Open the integrated terminal (`` Ctrl+` ``)." + }, + { + "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", + "caption": "`./run-stack.sh` checks PostgreSQL 17 with `psql`, starts FastAPI and Vite, and ends on `STACK_READY`." + }, + { + "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", + "caption": "Chromium opens CapsuleTask inside the capsule: PostgreSQL is connected and two seeded tasks are listed." + }, + { + "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", + "caption": "Add a first task. It appears at once as `pg#3`, the identifier PostgreSQL returned." + }, + { + "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", + "caption": "Add a second task in the *Database* category: `pg#4`." + }, + { + "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", + "caption": "Tick `pg#1`. The Completed counter goes to 2." + }, + { + "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", + "caption": "**Refresh from DB** reloads the list from PostgreSQL: 4 rows." + }, + { + "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", + "caption": "In VSCodium's terminal, `./query-db.sh` asks PostgreSQL directly: the same four rows, two of them completed." + }, + { + "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", + "caption": "Back in CapsuleTask: what the browser shows is what the database holds." + }, + { + "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..e4105cba --- /dev/null +++ b/devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md @@ -0,0 +1,49 @@ +# E2E Scenario Script: Java 25 + Spring Boot + PostgreSQL 17 In IntelliJ IDEA + +Scenario `springboot-postgres-java`, on the DevCapsule surface `intellij`. +Its recording and its presentation are written to +`devcapsule-src/tests/e2e/evidence/springboot-postgres-java/`. + +## 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 + +- **Capabilities:** `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` (`<maven.compiler.release>21</maven.compiler.release>`) with fluent `JdbcClient` on `http://127.0.0.1:18085` + +## 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..36b7a549 --- /dev/null +++ b/devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md @@ -0,0 +1,56 @@ +# E2E Scenario Script: FastAPI + PostgreSQL 17 + React Todo Application + +Scenario `todo-fastapi-postgres-react`, on the DevCapsule surface `codium`. +Its recording and its presentation are written to +`devcapsule-src/tests/e2e/evidence/todo-fastapi-postgres-react/`. + +## Goal + +This end-to-end test shows that one isolated capsule is enough for full-stack +work. The editor, Python, Node, the PostgreSQL client and the browser all come +from what the project declares; the developer installs none of them. + +## Stack And Capabilities + +- **Editor:** VSCodium, the project's `frontend-ide` +- **Backend:** Python 3.12, FastAPI and `psycopg`, `backend/main.py` on `127.0.0.1:18080` +- **Frontend:** Node.js 22, React and Vite, `frontend/src/App.jsx` on `127.0.0.1:15173`, proxying `/api` to `:18080` +- **Database:** PostgreSQL 17 in a container the test starts beside the capsule, database `tododb`, table `todos`, on `127.0.0.1:15432` +- **Browser:** Chromium, from `browser-automation`, on the capsule's desktop + +## What It Illustrates + +- The project declares its needs (`python`, `node`, `postgresql-client`, `browser-automation` and a frontend IDE) and the capsule provides them. +- The editor, its terminal and the browser share one contained desktop, shown in your browser. The capsule uses no display of the host. +- Backend, frontend and database tools work together inside the capsule: FastAPI on `:18080`, Vite on `:15173`, `psql` against PostgreSQL 17. +- The result is checked from outside: after the recording, the test reads the same four rows from the API and from PostgreSQL. + +## Steps + +1. **Open the workspace in VSCodium inside the capsule.** + - *User action:* Launch the project's capsule, trust the workspace when VSCodium asks, and look at the project: `.devcapsule/`, `backend/` and `frontend/`. + - *Expected observation:* VSCodium fills the capsule's `1600×1000` desktop with the workspace loaded and trusted. + +2. **Implement `POST /api/todos` in the FastAPI backend.** + - *User action:* Quick-open `backend/main.py` (`Ctrl+P`), go to line 75 (`Ctrl+G`) inside `create_todo`, type the parameterized `INSERT INTO todos … RETURNING` query and the JSON response, and save (`Ctrl+S`). + - *Expected observation:* `backend/main.py` holds the finished insert handler, saved, with no unsaved mark on its tab. + +3. **Implement `handleCreate` in the React frontend.** + - *User action:* Quick-open `frontend/src/App.jsx` (`Ctrl+P`), go to line 30 (`Ctrl+G`) inside `handleCreate`, type the `fetch('/api/todos', { method: 'POST', … })` request and the `setTodos` update, and save (`Ctrl+S`). + - *Expected observation:* `frontend/src/App.jsx` holds the finished `fetch` call and state update, saved. + +4. **Check PostgreSQL 17 and start the stack from the editor's terminal.** + - *User action:* Open VSCodium's integrated terminal (`` Ctrl+` ``) and run `./run-stack.sh`: it checks PostgreSQL 17 with `psql`, starts Uvicorn on `:18080` and starts Vite on `:15173`. + - *Expected observation:* The terminal prints the PostgreSQL 17 version, the two seeded rows as `psql` reads them, and `STACK_READY`. + +5. **Open the application in Chromium on the capsule's desktop.** + - *User action:* Launch Chromium on the capsule's own display, beside VSCodium, at `http://127.0.0.1:15173`. + - *Expected observation:* **CapsuleTask** shows `PostgreSQL 17.11 · Connected`, its counters, and the two seeded tasks, `pg#1` and `pg#2`. + +6. **Create two tasks and complete one in the browser.** + - *User action:* Type *Record FastAPI + React customer pitch demo* and click **Add Task**; type *Verify PostgreSQL 17 persistence across reloads*, choose the *Database* category and click **Add Task**; then tick the checkbox of `pg#1`. + - *Expected observation:* Both tasks appear at once with the identifiers PostgreSQL gave them, `pg#3` and `pg#4`, and the counters read 4 tasks, 2 completed. + +7. **Reload from PostgreSQL and ask the database directly.** + - *User action:* Click **Refresh from DB**, switch to VSCodium's terminal and run `./query-db.sh`, then return to **CapsuleTask**. + - *Expected observation:* `psql` and the browser agree: four rows, `1` to `4`, with 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 +<maven.compiler.release>21</maven.compiler.release> 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 = """<?xml version="1.0" encoding="UTF-8"?> +<project xmlns="http://maven.apache.org/POM/4.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-starter-parent</artifactId> + <version>3.4.5</version> + <relativePath/> + </parent> + + <groupId>io.devcapsule.demo</groupId> + <artifactId>capsule-sprint</artifactId> + <version>0.1.0</version> + <name>CapsuleSprint</name> + <description>DevCapsule Spring Boot + PostgreSQL 17 Customer Pitch Demo</description> + + <properties> + <maven.compiler.release>21</maven.compiler.release> + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> + </properties> + + <dependencies> + <dependency> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-starter-web</artifactId> + </dependency> + <dependency> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-starter-jdbc</artifactId> + </dependency> + <dependency> + <groupId>org.postgresql</groupId> + <artifactId>postgresql</artifactId> + <scope>runtime</scope> + </dependency> + </dependencies> + + <build> + <plugins> + <plugin> + <groupId>org.springframework.boot</groupId> + <artifactId>spring-boot-maven-plugin</artifactId> + </plugin> + </plugins> + </build> +</project> +""" + +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<String, Object> 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<SprintItem> 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 = """<!doctype html> +<html lang="en"> +<head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>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/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/e2e/todo_demo_controller.py b/devcapsule-src/tests/e2e/todo_demo_controller.py new file mode 100644 index 00000000..449b2ae9 --- /dev/null +++ b/devcapsule-src/tests/e2e/todo_demo_controller.py @@ -0,0 +1,558 @@ +"""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, + VIDEO_FRAMES_PER_SECOND, + BurstFrameRecorder, + ControllerQueue, + send_controller_command, + start_controller_server, + write_json_atomically, +) +from tests.e2e.scenario_presentation import plan_for_scenario, write_presentation +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"]] + # Before anything is recorded: a script that does not join the scenario fails here. + presentation = plan_for_scenario(spec) + recorder = BurstFrameRecorder(evidence / "video-frames") + shots: list[str] = [] + frames_after_actions: list[int] = [] + + 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) + frames_after_actions.append(recorder.frame_count) + 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() + + presented = encoded and presentation is not None + if encoded and presentation is not None: + write_presentation(evidence, presentation.timed( + frames_after_actions, recorder.frame_count, VIDEO_FRAMES_PER_SECOND, + video="scenario-video.webm", poster="poster.png", screenshots=shots, + )) + 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, + "presentation": "presentation.json" if presented 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/integration/test_ci_workflow.py b/devcapsule-src/tests/integration/test_ci_workflow.py new file mode 100644 index 00000000..2bb3168b --- /dev/null +++ b/devcapsule-src/tests/integration/test_ci_workflow.py @@ -0,0 +1,323 @@ +"""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" +_WEBSITE_WORKFLOW = REPOSITORY_ROOT / ".github" / "workflows" / "website.yml" +_DOCS_FILTER = REPOSITORY_ROOT / ".github" / "ci-paths.yml" +_ANNOTATIONS = REPOSITORY_ROOT / "devcapsule-src" / "scripts" / "diff_coverage_annotations.py" + + +def _job_step(workflow_path: Path, job: str, identifier: str) -> dict[str, Any]: + """The step of ``job`` in ``workflow_path`` with the given ``id``.""" + workflow = yaml.safe_load(workflow_path.read_text(encoding="utf-8")) + return next(step for step in workflow["jobs"][job]["steps"] if step.get("id") == identifier) + + +def _step(identifier: str) -> dict[str, Any]: + """The step of the workflow's ``changes`` job with the given id.""" + return _job_step(_WORKFLOW, "changes", 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", 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), + ("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 + + +@pytest.mark.parametrize(("workflow_path", "job"), [ + (_WORKFLOW, "docs-build"), + (_WEBSITE_WORKFLOW, "build"), + (_WEBSITE_WORKFLOW, "candidate"), +]) +def test_website_workflows_instantiate_a_raw_website_gitlink_recursively( + tmp_path: Path, workflow_path: Path, job: str, +) -> None: + """Precondition: a parent checkout whose ``website`` entry is a raw gitlink with no + ``.gitmodules`` mapping, pointing at a non-tip commit of ``devcapsule-website`` that itself + declares a nested submodule over SSH. Action: run the job's ``fetch-website`` step under + bash. Postcondition: ``website`` is checked out at the exact gitlink commit, its nested + submodule is materialized recursively, and both checkouts report clean ``git status``.""" + gitconfig = tmp_path / "gitconfig" + env = { + "PATH": os.environ["PATH"], + "HOME": str(tmp_path), + "GIT_CONFIG_GLOBAL": str(gitconfig), + "GIT_CONFIG_NOSYSTEM": "1", + "GIT_TERMINAL_PROMPT": "0", + "GIT_AUTHOR_NAME": "Test", + "GIT_COMMITTER_NAME": "Test", + "GIT_AUTHOR_EMAIL": "test@example.invalid", + "GIT_COMMITTER_EMAIL": "test@example.invalid", + } + + def git(*arguments: str, cwd: Path = tmp_path) -> str: + return subprocess.run(arguments, cwd=cwd, env=env, text=True, capture_output=True, check=True).stdout.strip() + + nested_origin = tmp_path / "nested.git" + nested_origin.mkdir() + git("git", "init", "-q", "-b", "main", cwd=nested_origin) + (nested_origin / "nested.txt").write_text("nested\n", encoding="utf-8") + git("git", "add", "nested.txt", cwd=nested_origin) + git("git", "commit", "-q", "-m", "nested", cwd=nested_origin) + nested_sha = git("git", "rev-parse", "HEAD", cwd=nested_origin) + + website_origin = tmp_path / "website.git" + website_origin.mkdir() + git("git", "init", "-q", "-b", "main", cwd=website_origin) + git("git", "config", "uploadpack.allowReachableSHA1InWant", "true", cwd=website_origin) + (website_origin / "package.json").write_text('{"name":"devcapsule-website"}\n', encoding="utf-8") + (website_origin / ".gitmodules").write_text( + '[submodule "sub"]\n\tpath = sub\n\turl = git@github.com:mycodespace-ai/nested.git\n', + encoding="utf-8", + ) + git("git", "update-index", "--add", "--cacheinfo", f"160000,{nested_sha},sub", cwd=website_origin) + git("git", "add", "package.json", ".gitmodules", cwd=website_origin) + git("git", "commit", "-q", "-m", "pinned website", cwd=website_origin) + pinned_website_sha = git("git", "rev-parse", "HEAD", cwd=website_origin) + (website_origin / "package.json").write_text('{"name":"newer-unpinned"}\n', encoding="utf-8") + git("git", "add", "package.json", cwd=website_origin) + git("git", "commit", "-q", "-m", "advance main past pin", cwd=website_origin) + + parent_origin = tmp_path / "parent.git" + parent_origin.mkdir() + git("git", "init", "-q", "-b", "main", cwd=parent_origin) + (parent_origin / ".gitmodules").write_text("", encoding="utf-8") + (parent_origin / "README.md").write_text("# DevCapsule\n", encoding="utf-8") + git("git", "update-index", "--add", "--cacheinfo", f"160000,{pinned_website_sha},website", cwd=parent_origin) + git("git", "add", ".gitmodules", "README.md", cwd=parent_origin) + git("git", "commit", "-q", "-m", "raw website gitlink", cwd=parent_origin) + git("git", "branch", "docs-0.3.0", cwd=parent_origin) + + checkout = tmp_path / "checkout" + git("git", "clone", "-q", str(parent_origin), str(checkout)) + + git("git", "config", "--file", str(gitconfig), "protocol.file.allow", "always") + for prefix in ("https://github.com/mycodespace-ai/", "git@github.com:mycodespace-ai/"): + git("git", "config", "--file", str(gitconfig), "--add", f"url.{website_origin}.insteadOf", f"{prefix}devcapsule-website.git") + git("git", "config", "--file", str(gitconfig), "--add", f"url.{nested_origin}.insteadOf", f"{prefix}nested.git") + + step = _job_step(workflow_path, job, "fetch-website") + subprocess.run( + ["bash", "--noprofile", "--norc", "-eo", "pipefail", "-c", step["run"]], + cwd=checkout, + env=env, + text=True, + capture_output=True, + check=True, + ) + + assert git("git", "rev-parse", "HEAD", cwd=checkout / "website") == pinned_website_sha + assert (checkout / "website" / "sub" / "nested.txt").read_text(encoding="utf-8") == "nested\n" + assert git("git", "status", "--porcelain", "--untracked-files=normal", cwd=checkout) == "" + assert git("git", "status", "--porcelain", "--untracked-files=normal", cwd=checkout / "website") == "" 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..5863c8fe --- /dev/null +++ b/devcapsule-src/tests/integration/test_console_channel_cli.py @@ -0,0 +1,396 @@ +"""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, the commands it starts, and ``project run`` on a +pseudo-terminal where the launch asks about a kept request. + +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 + +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.""" + +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.""" + + 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() + 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": 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]: + """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 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, 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: + """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 + + +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_console_decisions_cli.py b/devcapsule-src/tests/integration/test_console_decisions_cli.py index 930800cd..0efe2465 100644 --- a/devcapsule-src/tests/integration/test_console_decisions_cli.py +++ b/devcapsule-src/tests/integration/test_console_decisions_cli.py @@ -1,91 +1,84 @@ -"""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. 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 +import os from pathlib import Path +import subprocess import sys import pytest -from devcapsule import cli -from devcapsule.commands.project import CheckoutDecisionsCommand -from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template -from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan +from devcapsule.container_runtime.console import ConsoleInstallation 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))) +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, "PYTHONDONTWRITEBYTECODE": "1", + "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("inside", [False, True]) +@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, + tmp_path: Path, container_name: str | None, flag: str, ) -> None: - """``devcapsule project checkout decisions -h/--help`` prints wrapper help without requiring a console interpreter.""" - monkeypatch.setenv("DEVCAPSULE_CONTAINER_NAME", "capsule-fixture" if inside else "") - 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], - arguments: list[str], - status: int, - expected: str, -) -> None: - """``CheckoutDecisionsCommand`` delegates 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") - - result = CheckoutDecisionsCommand.invoke( - "devcapsule project checkout decisions", - arguments, - environ={"DEVCAPSULE_CONTAINER_NAME": "capsule-fixture"}, - console_python=Path(sys.executable), - runtime_plan_path=plan, - ) + """``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) - 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) == "" + assert completed.returncode == 0 + assert "from-table, check or hand-off" in completed.stdout + assert completed.stderr == "" -@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_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") + + completed = checkout_decisions(tmp_path, "check", str(decision), container_name="capsule-fixture") + + 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_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_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/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/integration/test_print_command_cli.py b/devcapsule-src/tests/integration/test_print_command_cli.py new file mode 100644 index 00000000..d9594995 --- /dev/null +++ b/devcapsule-src/tests/integration/test_print_command_cli.py @@ -0,0 +1,101 @@ +"""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 == [] + + +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/integration/test_runtime_entrypoint_cli.py b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py new file mode 100644 index 00000000..7a090e14 --- /dev/null +++ b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py @@ -0,0 +1,275 @@ +"""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 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 + +from dataclasses import dataclass +import json +import os +from pathlib import Path +import stat +import signal +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.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", + "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 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, "PYTHONDONTWRITEBYTECODE": "1", "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.geteuid()}" + 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() + + +@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 new file mode 100644 index 00000000..d2f68845 --- /dev/null +++ b/devcapsule-src/tests/integration/test_version_cli.py @@ -0,0 +1,76 @@ +"""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 + +pytestmark = pytest.mark.integration + + +@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 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, + ) + + +@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") + + completed = version(distribution, *(("--json",) if as_json else ())) + + 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/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_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/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/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_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/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/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/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/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/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 new file mode 100644 index 00000000..a509a7e9 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/commands/test_launch_review.py @@ -0,0 +1,806 @@ +"""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 datetime import datetime, timezone +from pathlib import Path +import tomllib +from typing import Any + +import pytest + +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 +from devcapsule.configuration.capabilities import ( + 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 +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 + +ROOT = Path("/projects/order") +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 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 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 | None = "python-ide", host: Host | None = None, + manifest_tables: dict[str, Any] | None = None, offered: tuple[str, ...] = (), + 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 + further tables of the manifest, ``environment`` for instance. ``offered`` + 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: + the lock derived from the policy, the IDE pinned on the record, the base + 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, + "project": {"name": "order", "slug": "order", "creator": "mailto:owner@example.test", "mount": "/workspace/order"}, + "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], + 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, {}, {})), + ) + selection = Selection(LocalCapabilities.read(state.checkout), state.surfaces) + selection.ide = ide + record = CheckoutRecord.staged(RECORD, state.with_selection(selection)) + 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 + + +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 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, + 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, announce=never_announced) + + 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, announce=never_announced) + + 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, announce=never_announced) + + 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, 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, announce=never_announced) + + +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, announce=never_announced) + + 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 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), 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 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, announce=never_announced) + + 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, announce=never_announced, 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, announce=never_announced) + + +@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, 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, announce=never_announced) + + 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, announce=never_announced) + + 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, 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=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) + 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"] + + +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"} + + +@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 + + +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"] + + +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) + + + +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 + + +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 == {} + + +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 + + +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/commands/test_version.py b/devcapsule-src/tests/unit/devcapsule/commands/test_version.py deleted file mode 100644 index 145f6392..00000000 --- a/devcapsule-src/tests/unit/devcapsule/commands/test_version.py +++ /dev/null @@ -1,44 +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.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", -) - - -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) - - 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], -) -> None: - """``version`` without ``--json`` prints the mnemonic, package version, repository, revision, and URL.""" - status = VersionCommand.invoke("devcapsule version", [], build_info=SAMPLE_BUILD) - - 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/configuration/test_authorization.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py index 92f49bda..d5178e97 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,106 @@ 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) + + +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_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_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/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) 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/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..bc18b50f --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py @@ -0,0 +1,174 @@ +"""Unit tests of ``devcapsule/configuration/derivation.py``: reading a checkout into memory, and a checkout's selection. + +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 + +from pathlib import Path +from typing import Any + +import pytest + +from devcapsule.configuration.capabilities import CapabilityPolicy, LocalCapabilities +from devcapsule.configuration.capability_selection import generate_lock +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 + +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" + + +# 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/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() 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/container_runtime/components/__init__.py similarity index 100% rename from devcapsule-src/tests/unit/devcapsule/legacy_refactoring/__init__.py rename to devcapsule-src/tests/unit/devcapsule/container_runtime/components/__init__.py 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 6f8d3ff3..16630570 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_console.py @@ -1,10 +1,9 @@ -"""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 -from contextlib import contextmanager from pathlib import Path -from typing import Iterator +import socket import pytest @@ -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,11 +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. + + The interpreter is an empty file. ``child`` only checks that it exists; + no test here executes it. + """ + python = tmp_path / "base-python" + python.touch() + return ConsoleInstallation(python, tmp_path / "launcher-webconsole") + + +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: @@ -52,40 +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) -> 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.""" - python = tmp_path / "python" - python.touch() - bundled = launcher_bundle(tmp_path / "launcher-webconsole") + 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), - console_python=python, - launcher_source=bundled, - ) + child = installation.child(plan, lambda command: ("as-user", *command)) assert child is not None assert child.name == CONSOLE_CHILD @@ -93,8 +102,8 @@ def test_console_child_runs_the_launcher_package_on_the_base_interpreter(tmp_pat assert child.command == ( "as-user", "env", - f"PYTHONPATH={bundled}", - str(python), + f"PYTHONPATH={installation.launcher_source}", + str(installation.python), "-m", "devcapsule_webconsole", "--project", @@ -112,25 +121,19 @@ def test_console_child_runs_the_launcher_package_on_the_base_interpreter(tmp_pat assert child.ready_timeout_seconds == CONSOLE_READY_TIMEOUT_SECONDS -def test_console_child_runs_the_base_copy_without_a_launcher_package( +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.""" - python = tmp_path / "python" - python.touch() + 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), - console_python=python, - launcher_source=tmp_path / "absent-launcher-webconsole", - ) + child = installation.child(plan, lambda command: ("as-user", *command)) assert child is not None assert child.command == ( "as-user", - str(python), + str(installation.python), "-m", "devcapsule_webconsole", "--project", @@ -147,109 +150,94 @@ 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( +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.""" - python = tmp_path / "python" - python.touch() - bundled = launcher_bundle(tmp_path / "launcher-webconsole") + 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, console_python=python, launcher_source=bundled) + child = installation.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(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, 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`` 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]] = [] - - @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")) - - 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, - ) + """``probe_address`` maps each wildcard to the loopback of its family and leaves a named address as it is.""" + assert probe_address(listen) == expected - 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")] +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 -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() + ready = child.ready() - @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, - ) + assert ready is True - assert child is not None and child.ready is not None - assert child.ready() is False +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 -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) + ready = child.ready() - assert child is None - assert capsys.readouterr().err == "" + assert ready is False -def test_console_child_warns_and_returns_none_when_interpreter_is_absent( - tmp_path: Path, capsys: pytest.CaptureFixture[str], -) -> None: - """When the base image lacks ``CONSOLE_PYTHON``, ``console_child`` prints a degradation notice and returns ``None``.""" - 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", - ) +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 child is None - assert "this base has no web console (base recipe 10 adds it" in capsys.readouterr().err + 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 4e108fdc..d8531239 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_contract.py @@ -1,27 +1,68 @@ -"""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( - 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: @@ -99,3 +140,204 @@ 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 == "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: + """``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 a1db50de..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,186 +1,50 @@ -"""Unit tests of ``devcapsule/container_runtime/entrypoint.py``: console child placement across launch modes.""" +"""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 -import os from pathlib import Path -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.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 ConsoleBuilder, SupervisorFactory, run -from devcapsule.container_runtime.supervisor import SupervisedChild - - -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 - - def run(self) -> int: - return 42 - - -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 make_supervisor(children: tuple[SupervisedChild, ...], **kwargs: object) -> RecordingSupervisor: - instance = RecordingSupervisor(children, **kwargs) - recorded.append(instance) - return instance - - return make_supervisor, recorded - - -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 - - -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.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) - +import pytest -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``.""" - 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) +from devcapsule.container_runtime.entrypoint import USAGE, main -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_main_prints_the_usage_for_help(capsys: pytest.CaptureFixture[str]) -> None: + """``main(["--help"])`` prints the usage on stdout and returns 0.""" + status = main(["--help"]) + assert status == 0 + assert capsys.readouterr().out == USAGE + "\n" -def test_run_places_console_after_contained_display_and_before_foreground_surface(tmp_path: Path) -> 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, - ) - - assert status == 42 - children = recorded[0].children - 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: - """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, - ) - - assert status == 42 - children = recorded[0].children - 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: - """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, - ) - - assert status == 42 - children = recorded[0].children - assert [child.name for child in children] == [CONSOLE_CHILD, "job"] - assert children[0].foreground is False and children[1].foreground is True - - -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, - ) - - 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 (tmp_path / "jetbrains.properties").is_file() - assert dict(os.environ) == process_environment_before +@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: + """Without exactly one plan, or with ``--`` and no command after it, ``main`` prints the usage on stderr and returns 2.""" + status = main(arguments) + + assert status == 2 + output = capsys.readouterr() + assert output.err == USAGE + "\n" + assert output.out == "" + + +@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]) + + 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 3be60b0f..81ed6fd9 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py @@ -5,11 +5,17 @@ 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") def sandboxed_plan(tmp_path: Path) -> RuntimePlan: @@ -18,7 +24,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 +34,69 @@ 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 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`` 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) - 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 = "/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"), 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_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_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) + + create_directories(filesystem) - 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 + - prepare_filesystem( - plan, - Identity(1000, 1001, "developer"), - caller_uid=0, - chown=lambda path, uid, gid: chowned.append((path, uid, gid)), +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() + + created = create_directories(filesystem) + + assert created == ( + tmp_path / "home" / ".ssh", + tmp_path / "runtime", + tmp_path / "runtime" / "devcapsule-runtime-1000", ) - assert chowned == [ - (existing / ".ssh", 1000, 1001), - (tmp_path / "runtime", 1000, 1001), - (runtime_dir, 1000, 1001), - ] + +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 new file mode 100644 index 00000000..4ba2eaa5 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py @@ -0,0 +1,59 @@ +"""Unit tests of ``devcapsule/container_runtime/identity.py``: what the capsule user is given when root prepares the session.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule.container_runtime.contract import Identity +from devcapsule.container_runtime.identity import CapsuleUser + +DEVELOPER = Identity(1000, 1001, "developer") +ROOT = Identity(0, 0, "root") +PREPARED_BY_ROOT = CapsuleUser(DEVELOPER, caller_uid=0) +PREPARED_BY_THE_USER = CapsuleUser(DEVELOPER, caller_uid=1000) +ROOTLESS_ROOT = CapsuleUser(ROOT, caller_uid=0) + + +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") + + +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") + + +@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"): + 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"),)) == () + + +def test_command_does_not_wrap_root_identity_in_gosu() -> None: + """When both the caller and the target identity are ``0:0`` (rootless Docker), ``command`` omits ``gosu``.""" + assert ROOTLESS_ROOT.command(("ide", "--wait")) == ("ide", "--wait") + + +def test_owner_changes_are_none_when_the_target_identity_is_root() -> None: + """When the caller and target identity are both ``0:0``, ``owner_changes`` avoids redundant ``chown`` calls.""" + assert ROOTLESS_ROOT.owner_changes((Path("/home/devcapsule/.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..8dca04b0 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_session.py @@ -0,0 +1,446 @@ +"""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_session_paths_and_component_variables_before_the_launch( + tmp_path: Path, +) -> None: + """``environment`` sets session paths and component variables; launch variables wait until their files are written.""" + 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 "PYCHARM_PROPERTIES" not in environment + + +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, + ) + + +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"] == "" diff --git a/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py b/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py index b1581f3c..c8ec86a2 100644 --- a/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py +++ b/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py @@ -9,6 +9,7 @@ from dataclasses import replace from datetime import datetime, timedelta, timezone import json +import os from pathlib import Path import socket from threading import Event @@ -1883,3 +1884,87 @@ def test_build_run_config_omits_checkout_console_source_under_a_built_launcher_u assert opted_in_config.runtime_plan is not None and opted_in_config.runtime_plan.console is not None assert opted_in_config.runtime_plan.console.source_path == "/workspace/project/devcapsule-webconsole" + +def test_rootless_docker_runs_container_as_mapped_root_while_rootful_keeps_host_uid( + tmp_path: Path, +) -> None: + """Rootless Docker maps host mounts to ``0:0`` and drops ``--user``/``IDE_*`` to ``0:0``/``root``; non-rootless preserves host identity.""" + env = base_env(tmp_path) + env["XDG_RUNTIME_DIR"] = str(tmp_path / "runtime") + rootful_config = contained_config(tmp_path) + rootless_config = contained_config(tmp_path, rootless_docker=True) + assert rootful_config.rootless_docker is False + assert rootless_config.rootless_docker is True + + rootful_files = prepare_temp_runtime_files(rootful_config, env) + rootless_files = prepare_temp_runtime_files(rootless_config, env) + try: + rootful_args = build_docker_args(rootful_config, rootful_files, env) + rootless_args = build_docker_args(rootless_config, rootless_files, env) + + host_uid, host_gid = os.getuid(), os.getgid() + assert rootful_args[rootful_args.index("--user") + 1] == f"{host_uid}:{host_gid}" + assert f"IDE_UID={host_uid}" in rootful_args + assert f"IDE_GID={host_gid}" in rootful_args + + assert rootless_args[rootless_args.index("--user") + 1] == "0:0" + assert "IDE_UID=0" in rootless_args + assert "IDE_GID=0" in rootless_args + assert "IDE_USER=root" in rootless_args + assert rootless_files.passwd_file.read_text(encoding="utf-8") == ( + "root:x:0:0:PyCharm Docker User:/home/devcapsule:/bin/bash\n" + ) + assert rootless_files.group_file.read_text(encoding="utf-8") == "root:x:0:\n" + finally: + cleanup_temp_runtime_files(rootful_files) + cleanup_temp_runtime_files(rootless_files) + + +def test_rootless_host_docker_socket_owned_by_host_user_maps_to_container_root_group( + tmp_path: Path, +) -> None: + """In rootless ``host`` Docker mode, a daemon socket owned by the host user's GID maps to container GID ``0``; rootful keeps its host GID.""" + sock_path = tmp_path / "docker.sock" + listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + listener.bind(str(sock_path)) + try: + rootful_config = contained_config( + tmp_path, docker_mode=DockerMode.host, host_docker_socket=sock_path, rootless_docker=False + ) + rootless_config = contained_config( + tmp_path, docker_mode=DockerMode.host, host_docker_socket=sock_path, rootless_docker=True + ) + assert rootful_config.host_docker_gid == os.getgid() + assert rootless_config.host_docker_gid == 0 + + env = base_env(tmp_path) + env["XDG_RUNTIME_DIR"] = str(tmp_path / "runtime") + files = prepare_temp_runtime_files(rootless_config, env) + try: + args = build_docker_args(rootless_config, files, env) + assert args[args.index("--user") + 1] == "0:0" + assert args[args.index("--group-add") + 1] == "0" + assert files.group_file.read_text(encoding="utf-8") == "root:x:0:\n" + finally: + cleanup_temp_runtime_files(files) + finally: + listener.close() + + +def test_rootless_sudoers_policy_ownership_accepts_host_user_file_without_chown( + tmp_path: Path, +) -> None: + """Under rootless Docker, the host-owned sudoers policy is already container-root-owned so preparation skips ``chown``.""" + env = base_env(tmp_path) + env["XDG_RUNTIME_DIR"] = str(tmp_path / "runtime") + config = contained_config(tmp_path, enable_sudo=True, rootless_docker=True) + files = prepare_temp_runtime_files(config, env) + try: + ensure_sudoers_policy_ownership(config, files, env) + assert files.sudoers_volume is None + assert "ide-sudo:x:" in files.group_file.read_text(encoding="utf-8") + assert files.shadow_file is not None + assert files.shadow_file.read_text(encoding="utf-8").startswith("root:*:") + finally: + cleanup_temp_runtime_files(files) + 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 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"] 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)) == [] 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_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_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/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 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"] diff --git a/devcapsule-src/tests/unit/devcapsule/test_build_info.py b/devcapsule-src/tests/unit/devcapsule/test_build_info.py index b6ce9f29..6042f845 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_build_info.py +++ b/devcapsule-src/tests/unit/devcapsule/test_build_info.py @@ -12,11 +12,51 @@ 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_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) + + assert json.loads(text) == SAMPLE_BUILD.to_mapping() + assert BuildInfo.from_json(text) == SAMPLE_BUILD + + +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: """``has_public_revision`` is True only when ``source_url`` matches ``/commit/``.""" @@ -100,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)) + + 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 / "missing.json", record)) + 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( @@ -133,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" @@ -146,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 832206bd..102e9a11 100644 --- a/devcapsule-src/tests/unit/devcapsule/test_console_tools.py +++ b/devcapsule-src/tests/unit/devcapsule/test_console_tools.py @@ -11,8 +11,8 @@ 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.console import console_child +from devcapsule.console_tools import DECISIONS_MODULE, DecisionTools +from devcapsule.container_runtime.console import ConsoleInstallation from devcapsule.container_runtime.contract import ConsolePlan, Identity, RuntimePlan @@ -28,45 +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 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": @@ -76,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, @@ -114,26 +114,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) -> None: - """When ``console.source_path`` is set, ``console_decisions_command`` matches ``console_child`` and overrides ``launcher_console_source``.""" - 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") - - child = console_child(plan, lambda command: command, console_python=python, launcher_source=bundled) - 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") - assert child is not None - assert command[:2] == child.command[:2] == ( + command = tools.command(["check", "x.json"]) + + assert command[:2] == ( "env", "PYTHONPATH=/workspace/project with spaces/devcapsule-webconsole", ) @@ -141,26 +131,21 @@ 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( +def test_run_preserves_arguments_streams_and_exit_status( tmp_path: Path, 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`` 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}\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", "", "--"] - 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 = capsule_tools(tmp_path, fake).run(arguments) assert result == status output = capfd.readouterr() @@ -168,18 +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) -> None: - """When executing ``console_python`` raises ``OSError``, ``run_console_decisions`` wraps it in a ``CliError`` that names the interpreter.""" +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) 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", - ) + capsule_tools(tmp_path, python).run(["check", "x.json"]) assert str(python) in str(caught.value) 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/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/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..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 @@ -333,3 +333,213 @@ 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 + + +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. + +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" + + + +# 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/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_scenario_presentation.py b/devcapsule-src/tests/unit/tests/e2e/test_scenario_presentation.py new file mode 100644 index 00000000..f6f5c471 --- /dev/null +++ b/devcapsule-src/tests/unit/tests/e2e/test_scenario_presentation.py @@ -0,0 +1,250 @@ +"""Unit tests for ``tests.e2e.scenario_presentation``.""" +from __future__ import annotations + +import json +from pathlib import Path +import re +from typing import Any + +import pytest + +from tests.e2e.scenario_presentation import ( + PresentationError, + Script, + ScriptStep, + parse_script, + plan_for_scenario, + plan_presentation, + write_presentation, +) + +SCRIPT_TEXT = """\ +# E2E Scenario Script: A Sample + +Scenario `sample`. This line is not read. + +## Goal + +Show that the editor opens +and the stack runs. + +## Stack And Capabilities + +- **Editor:** VSCodium, the project's `frontend-ide` +- **Database:** PostgreSQL 17, + on `127.0.0.1:15432` + +## What It Illustrates + +- The capsule provides the editor. +- The stack runs + inside the capsule. + +## Steps + +1. **Open the editor.** + - *User action:* Launch the capsule + and wait. + - *Expected observation:* The editor is open. + +2. **Run the stack with `./run.sh`.** + - *User action:* Run `./run.sh`. + - *Expected observation:* It prints `READY`. +""" + +SCRIPT = Script( + goal="Show it.", + stack=(("Editor", "VSCodium"),), + illustrates=("One thing.",), + steps=( + ScriptStep(title="Open the editor", action="Launch it.", expected="It is open."), + ScriptStep(title="Run the stack", action="Run it.", expected="It prints READY."), + ), +) + + +def scenario(*actions: Any, **changes: Any) -> dict[str, Any]: + """A scenario document for ``SCRIPT`` with the given actions.""" + return {"id": "sample", "title": "A sample", "description": "What happens.", "actions": list(actions), **changes} + + +def action(reason: str, **fields: Any) -> dict[str, Any]: + return {"action": "wait", "ms": 150, "reason": reason, **fields} + + +def test_parse_script_reads_goal_stack_illustrations_and_steps() -> None: + """``parse_script`` returns the goal as one paragraph, the stack rows, the illustrations and the steps, joining wrapped lines and dropping a title's closing period.""" + parsed = parse_script(SCRIPT_TEXT) + + assert parsed == Script( + goal="Show that the editor opens and the stack runs.", + stack=(("Editor", "VSCodium, the project's `frontend-ide`"), ("Database", "PostgreSQL 17, on `127.0.0.1:15432`")), + illustrates=("The capsule provides the editor.", "The stack runs inside the capsule."), + steps=( + ScriptStep(title="Open the editor", action="Launch the capsule and wait.", expected="The editor is open."), + ScriptStep(title="Run the stack with `./run.sh`", action="Run `./run.sh`.", expected="It prints `READY`."), + ), + ) + + +def test_parse_script_accepts_a_script_without_the_optional_sections() -> None: + """A script with only ``Goal`` and ``Steps`` parses, with an empty stack and no illustrations.""" + text = "## Goal\n\nShow it.\n\n## Steps\n\n1. **Open.**\n - *User action:* Open it.\n - *Expected observation:* It is open.\n" + + parsed = parse_script(text) + + assert (parsed.stack, parsed.illustrates, len(parsed.steps)) == ((), (), 1) + + +@pytest.mark.parametrize( + ("change", "message"), + [ + (("## Goal", "## Purpose"), "section 'Purpose' is not one of"), + (("## Steps", "## Goal"), "section 'Goal' appears twice"), + (("Show that the editor opens\nand the stack runs.\n", ""), "section 'Goal' is missing or empty"), + (("- **Editor:** VSCodium", "- Editor: VSCodium"), "a stack bullet is '- **Name:** detail'"), + (("- The capsule provides the editor.", "The capsule provides the editor."), "'What It Illustrates' takes bullets"), + (("2. **Run the stack", "3. **Run the stack"), "expected step 2, found 3"), + ((" - *Expected observation:* The editor is open.\n", ""), "step 1 has no 'Expected observation'"), + ((" - *User action:* Run `./run.sh`.", " - *User action:* Run `./run.sh`.\n - *User action:* Again."), "step 2 states 'User action' twice"), + (("1. **Open the editor.**", "1. Open the editor."), "a step is 'N. **Title.**'"), + (("1. **Open the editor.**", "1. **.**"), "step 1 has no title"), + ], +) +def test_parse_script_refuses_a_text_outside_the_form(change: tuple[str, str], message: str) -> None: + """``parse_script`` raises ``PresentationError`` naming the fault for an unknown or repeated section, an empty goal, a malformed bullet, and a step out of order, incomplete, repeated, unmarked or untitled.""" + old, new = change + assert old in SCRIPT_TEXT + text = SCRIPT_TEXT.replace(old, new, 1) + + with pytest.raises(PresentationError, match=re.escape(message)): + parse_script(text) + + +def test_timed_places_steps_and_reason_captions_on_the_recording() -> None: + """Without captions, each action's reason minus its number is a caption, and steps run from the video's start through each step's last action to the video's end.""" + plan = plan_presentation(scenario(action("1. Close the sidebar"), action("1. Trust the folder"), action("2. Type the command")), SCRIPT) + + document = plan.timed([12, 30, 48], 60, 12, video="video.webm", poster="poster.png", screenshots=["a.png", "b.png", "c.png"]) + + assert document == { + "schema_version": 1, + "scenario_id": "sample", + "title": "A sample", + "overview": { + "summary": "What happens.", + "intent": "Show it.", + "illustrates": ["One thing."], + "stack": [{"name": "Editor", "detail": "VSCodium"}], + }, + "video": {"file": "video.webm", "poster": "poster.png", "duration": 5.0}, + "steps": [ + {"title": "Open the editor", "action": "Launch it.", "expected": "It is open.", "screenshot": "b.png", + "start": 0.0, "end": 2.5, + "captions": [{"start": 0.0, "end": 1.0, "text": "Close the sidebar"}, {"start": 1.0, "end": 2.5, "text": "Trust the folder"}]}, + {"title": "Run the stack", "action": "Run it.", "expected": "It prints READY.", "screenshot": "c.png", + "start": 2.5, "end": 5.0, + "captions": [{"start": 2.5, "end": 5.0, "text": "Type the command"}]}, + ], + } + + +def test_timed_makes_a_written_caption_last_until_the_next_one() -> None: + """In a step with captions, a caption starts at the action that has it and lasts through the actions after it that have none.""" + plan = plan_presentation(scenario( + action("1. Press the key", caption="Quick Open finds the file."), action("1. Wait"), action("1. Type the name"), + action("1. Press Enter", caption="The file opens."), action("2. Run"), + ), SCRIPT) + + document = plan.timed([6, 12, 18, 24, 30], 36, 12, video="v.webm", poster="p.png", screenshots=["1", "2", "3", "4", "5"]) + + assert document["steps"][0]["captions"] == [ + {"start": 0.0, "end": 1.5, "text": "Quick Open finds the file."}, + {"start": 1.5, "end": 2.0, "text": "The file opens."}, + ] + + +def test_timed_omits_the_overview_parts_the_script_does_not_state() -> None: + """A script without stack rows or illustrations gives an overview with the summary and the intent only.""" + bare = Script(goal="Show it.", stack=(), illustrates=(), steps=SCRIPT.steps[:1]) + plan = plan_presentation(scenario(action("1. Open")), bare) + + document = plan.timed([4], 8, 4, video="v.webm", poster="p.png", screenshots=["1.png"]) + + assert document["overview"] == {"summary": "What happens.", "intent": "Show it."} + + +@pytest.mark.parametrize( + ("frames", "total", "rate", "screenshots", "message"), + [ + ([12, 30], 60, 12, ["a", "b", "c"], "2 frame counts and 3 screenshots for 3 actions"), + ([12, 30, 48], 60, 12, ["a", "b"], "3 frame counts and 2 screenshots for 3 actions"), + ([30, 12, 48], 60, 12, ["a", "b", "c"], "decrease or exceed the total"), + ([12, 30, 72], 60, 12, ["a", "b", "c"], "decrease or exceed the total"), + ([12, 30, 48], 60, 0, ["a", "b", "c"], "frames per second must be positive"), + ([12, 12, 48], 60, 12, ["a", "b", "c"], "step 1 has a caption that lasts no frame"), + ], +) +def test_timed_refuses_a_run_that_does_not_match_the_plan( + frames: list[int], total: int, rate: int, screenshots: list[str], message: str, +) -> None: + """``timed`` raises ``PresentationError`` for counts or screenshots of another length, counts that decrease or pass the total, a rate that is not positive, and a caption without a frame.""" + plan = plan_presentation(scenario(action("1. One"), action("1. Two"), action("2. Three")), SCRIPT) + + with pytest.raises(PresentationError, match=re.escape(message)): + plan.timed(frames, total, rate, video="v.webm", poster="p.png", screenshots=screenshots) + + +@pytest.mark.parametrize( + ("document", "message"), + [ + (scenario(action("1. One"), action("2. Two"), id=" "), "the scenario has no id"), + (scenario(action("1. One"), action("2. Two"), description=""), "the scenario has no description"), + (scenario(), "the scenario has no actions"), + (scenario("press Enter"), "action 1 is not an object"), + (scenario(action("Close the sidebar"), action("2. Two")), "action 1: its reason must start with the number of its step"), + (scenario(action("1. One"), action("3. Three")), "action 2 names step 3; the script has steps 1 to 2"), + (scenario(action("2. Two"), action("1. One")), "action 2 names step 1 after an action of step 2"), + (scenario(action("1. One"), action("1. More")), "step 2 of the script has no action"), + (scenario(action("1. One", caption=" "), action("2. Two")), "action 1: its caption must be a non-empty text"), + (scenario(action("1. One"), action("1. More", caption="Late."), action("2. Two")), "step 1 has captions, so its first action, action 1, needs one"), + ], +) +def test_plan_presentation_refuses_a_scenario_that_does_not_join_its_script(document: dict[str, Any], message: str) -> None: + """``plan_presentation`` raises ``PresentationError`` naming a missing id or description, missing or malformed actions, an unnumbered, unknown, backward or absent step, an empty caption, and a captioned step whose first action has none.""" + with pytest.raises(PresentationError, match=re.escape(message)): + plan_presentation(document, SCRIPT) + + +def test_plan_for_scenario_reads_the_named_script_below_the_root(tmp_path: Path) -> None: + """A scenario that names its script is planned from the file at that path below the root.""" + (tmp_path / "scripts").mkdir() + (tmp_path / "scripts" / "sample.md").write_text(SCRIPT_TEXT, encoding="utf-8") + + plan = plan_for_scenario(scenario(action("1. One"), action("2. Two"), script="scripts/sample.md"), tmp_path) + + assert plan is not None + assert plan.script == parse_script(SCRIPT_TEXT) + + +def test_plan_for_scenario_plans_nothing_for_a_scenario_without_a_script(tmp_path: Path) -> None: + """A scenario that names no script has no presentation plan, whatever its actions say.""" + assert plan_for_scenario(scenario(action("Unnumbered")), tmp_path) is None + + +@pytest.mark.parametrize("named", ["scripts/absent.md", "../outside.md", "/etc/hostname", "", 7]) +def test_plan_for_scenario_refuses_a_script_it_cannot_read_below_the_root(tmp_path: Path, named: object) -> None: + """A named script that is absent, leaves the root, is absolute, or is not a path is a ``PresentationError``, not a missing presentation.""" + with pytest.raises(PresentationError, match="the scenario's script"): + plan_for_scenario(scenario(action("1. One"), action("2. Two"), script=named), tmp_path) + + +def test_write_presentation_writes_the_document_as_presentation_json(tmp_path: Path) -> None: + """``write_presentation`` writes the document as UTF-8 JSON named ``presentation.json`` in the evidence folder and returns that path.""" + document = {"schema_version": 1, "title": "Café · 1600×1000"} + + path = write_presentation(tmp_path, document) + + assert path == tmp_path / "presentation.json" + assert json.loads(path.read_text(encoding="utf-8")) == document + assert "Café · 1600×1000" in path.read_text(encoding="utf-8") 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/devcapsule-src/tests/unit/tests/test_conftest.py b/devcapsule-src/tests/unit/tests/test_conftest.py index 37740ce7..d62a8a1d 100644 --- a/devcapsule-src/tests/unit/tests/test_conftest.py +++ b/devcapsule-src/tests/unit/tests/test_conftest.py @@ -1,10 +1,28 @@ -"""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, 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 -from tests.conftest import DOCKER_MARKERS +import pytest + +from tests import conftest +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, +) _PYPROJECT = Path(__file__).resolve().parents[3] / "pyproject.toml" @@ -20,3 +38,307 @@ 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 + + +# 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 + + +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/devcapsule-webconsole/PRESENTATIONS.md b/devcapsule-webconsole/PRESENTATIONS.md new file mode 100644 index 00000000..d415c848 --- /dev/null +++ b/devcapsule-webconsole/PRESENTATIONS.md @@ -0,0 +1,141 @@ +# 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. + +## Where the document comes from + +Nobody writes it by hand. A replay of a recorded scenario writes it beside +the recording: `devcapsule-src/tests/e2e/scenario_presentation.py` takes the +overview and the steps from the scenario's script, the captions from the +scenario's actions, and the times from the count of frames the recorder had +taken after each action. What a scenario's author provides is described in +[running scenario recordings](../engineering-docs/development/running-e2e-scenario-recordings.md), +section 5. Any other producer may write the document; the contract above is +all the page knows. + +## 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 the `presentation.json` that +`scenario_presentation.py` makes from the scenario, its script and that +run's frame counts. 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..3fa018f7 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) @@ -289,7 +299,12 @@ def resources() -> JSONResponse: @app.get("/api/project/tree") def project_tree(path: str = "") -> Response: - """One directory of the mounted project: entries as lstat sees them, links unfollowed.""" + """One directory of the mounted project: entries as lstat sees them, links unfollowed. + + Each regular file's entry carries ``type``, the media type the raw route + serves it as, so the Files page asks here which files are video or + audio and keeps no table of its own; ``type`` is null for other entries. + """ try: listing = list_project_directory(settings.project, path) except PathRefused as error: @@ -300,8 +315,15 @@ def project_tree(path: str = "") -> Response: return PlainTextResponse(f"no directory at {path!r} in the project\n", status_code=404) except OSError: return PlainTextResponse(f"cannot read {path!r} in the project\n", status_code=403) + for entry in listing["entries"]: + entry["type"] = raw_content_type(entry["name"]) if entry["kind"] == "file" else None 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..135ee104 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; @@ -167,6 +168,9 @@ footer.console-foot { color: var(--muted); font-size: 0.85rem; max-width: var(-- table.data td.num, table.data th.num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; } table.data td.keep, table.data th.keep { white-space: nowrap; overflow-wrap: normal; } /* Rendered records. */ +/* A recording played by the Files page: never wider than the page nor taller than the window. */ +video.recording { display: block; max-width: 100%; max-height: max(12rem, calc(100vh - 24rem)); background: #000; } +audio.recording { display: block; width: 100%; max-width: 40rem; } .record { max-width: 56rem; } .record h1, .record h2, .record h3 { margin-top: 1.8rem; } .record h1 { font-size: 1.6rem; } .record h2 { font-size: 1.25rem; } .record h3 { font-size: 1.05rem; } diff --git a/devcapsule-webconsole/devcapsule_webconsole/static/console.js b/devcapsule-webconsole/devcapsule_webconsole/static/console.js index 445a5b61..ac43a5c2 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"; @@ -411,11 +413,13 @@ return "/api/project/raw?path=" + encodeURIComponent(resolved.path) + resolved.fragment; } + // Where a link in a record leads: a Markdown file to Records, anything else + // to its /files address, where the Files page plays a recording and sends + // every other file on to the raw route. function recordUrl(resolved) { if (resolved.path === null) return "#"; - return resolved.path.toLowerCase().endsWith(".md") - ? "/records/" + resolved.path.split("/").map(encodeURIComponent).join("/") + resolved.fragment - : rawRecordUrl(resolved); + const segments = resolved.path.split("/").map(encodeURIComponent).join("/"); + return (resolved.path.toLowerCase().endsWith(".md") ? "/records/" : "/files/") + segments + resolved.fragment; } function recordRenderer(from) { @@ -531,10 +535,68 @@ return path.split("/").map(encodeURIComponent).join("/"); } - function fileViewUrl(path) { - return path.toLowerCase().endsWith(".md") - ? "/records/" + encodeSegments(path) - : "/api/project/raw?path=" + encodeURIComponent(path); + function rawFileUrl(path) { + return "/api/project/raw?path=" + encodeURIComponent(path); + } + + // Whether a file is played by this page. `type` is the media type the tree + // route gives for a file entry; the server is the one place that decides + // what a file is served as. Chrome refuses to play a recording opened as a + // raw document, because the raw route's policy forbids that document every + // fetch, its own player's included; an element in a console page is not + // under that policy. + function played(type) { + return typeof type === "string" && (type.startsWith("video/") || type.startsWith("audio/")); + } + + // Where a file opens: a Markdown file in Records, a recording on its own + // /files address, anything else as the raw file. Without `type` the answer + // for a recording is the raw address. + function fileViewUrl(path, type) { + if (path.toLowerCase().endsWith(".md")) return "/records/" + encodeSegments(path); + return played(type) ? "/files/" + encodeSegments(path) : rawFileUrl(path); + } + + // The breadcrumbs of a project path: every directory links to its listing. + // `file`, when given, is the name that ends the path and is not a link. + function fileCrumbs(directory, file) { + const crumbs = el("p", { class: "crumbs" }, [el("a", { href: "/files", text: "project" })]); + const parts = directory ? directory.split("/") : []; + parts.forEach((part, index) => { + crumbs.appendChild(document.createTextNode(" › ")); + crumbs.appendChild(el("a", { href: "/files/" + encodeSegments(parts.slice(0, index + 1).join("/")), text: part })); + }); + if (file !== undefined) { + crumbs.appendChild(document.createTextNode(" › ")); + crumbs.appendChild(el("span", { text: file })); + } + return crumbs; + } + + // The media type of the regular file at `path`, read from the listing of + // the directory that holds it; null when that listing cannot be read or + // has no such file. + async function fileType(path) { + const cut = path.lastIndexOf("/"); + const directory = cut < 0 ? "" : path.slice(0, cut); + const name = path.slice(cut + 1); + const response = await fetch( + directory ? "/api/project/tree?path=" + encodeURIComponent(directory) : "/api/project/tree", + { credentials: "same-origin" }); + if (!response.ok) return null; + const entry = (await response.json()).entries.find((candidate) => candidate.kind === "file" && candidate.name === name); + return entry ? entry.type : null; + } + + // One recording in the page: its breadcrumbs, the player and the download link. + function showRecording(container, path, type) { + const cut = path.lastIndexOf("/"); + const player = el(type.startsWith("video/") ? "video" : "audio", + { class: "recording", controls: "", preload: "metadata", src: rawFileUrl(path) }); + container.replaceChildren( + fileCrumbs(cut < 0 ? "" : path.slice(0, cut), path.slice(cut + 1)), + player, + el("p", {}, [el("a", { class: "muted", href: rawFileUrl(path) + "&download=1", text: "download" })])); } pages.files = async function (container) { @@ -547,9 +609,12 @@ const response = await fetch(treeUrl, { credentials: "same-origin" }); const bodyText = await response.text(); if (!response.ok) { + // The address names a file: play a recording here, open anything else where it is viewed. if (response.status === 404 && requested && bodyText.includes("is not a directory in the project") && typeof window.location.replace === "function") { - window.location.replace(fileViewUrl(requested)); + const type = await fileType(requested); + if (played(type)) showRecording(container, requested, type); + else window.location.replace(fileViewUrl(requested) + (window.location.hash || "")); return; } throw new Error(treeUrl + ": " + (bodyText.trim() || "HTTP " + response.status)); @@ -559,21 +624,18 @@ const label = directory || "Files"; if (heading) heading.textContent = label; document.title = label + " · DevCapsule console"; - const crumbs = el("p", { class: "crumbs" }, [el("a", { href: "/files", text: "project" })]); - if (directory) { - const parts = directory.split("/"); - parts.forEach((part, index) => { - crumbs.appendChild(document.createTextNode(" › ")); - crumbs.appendChild(el("a", { - href: "/files/" + parts.slice(0, index + 1).map(encodeURIComponent).join("/"), - text: part, - })); - }); - } + const crumbs = fileCrumbs(directory); if (!listing.entries.length) { 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" }), @@ -581,13 +643,13 @@ ]); const rows = listing.entries.map((entry) => { const entryPath = directory ? directory + "/" + entry.name : entry.name; - const rawUrl = "/api/project/raw?path=" + encodeURIComponent(entryPath); + const rawUrl = rawFileUrl(entryPath); let nameNodes; if (entry.kind === "directory") { nameNodes = [el("a", { href: "/files/" + encodeSegments(entryPath), text: entry.name + "/" })]; } else if (entry.kind === "file") { nameNodes = [ - el("a", { href: fileViewUrl(entryPath), text: entry.name }), + el("a", { href: fileViewUrl(entryPath, entry.type), text: entry.name }), " · ", el("a", { class: "muted", href: rawUrl + "&download=1", text: "download" }), ]; @@ -602,7 +664,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