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+- \*(?PUser action|Expected observation):\*\s+(?P.+?)\s*$")
+_STACK_ROW = re.compile(r"^- \*\*(?P.+?):\*\*\s+(?P.+?)\s*$")
+_BULLET = re.compile(r"^- (?P.+?)\s*$")
+_CONTINUATION = re.compile(r"^\s+(?P\S.*?)\s*$")
+_STEP_NUMBER = re.compile(r"^(?P\d+)\.\s+(?P\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}" /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/)",
+ )
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/)",
+ )
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` (`21`) 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
+21 so it compiles and runs
+cleanly under OpenJDK 25 inside DevCapsule, using Spring's fluent JdbcClient
+against PostgreSQL 17 and serving an interactive single-page web UI.
+"""
+
+from __future__ import annotations
+
+import json
+import stat
+import sys
+from pathlib import Path
+
+__all__ = [
+ "POM_XML",
+ "SPRINT_CONTROLLER_JAVA",
+ "TYPED_JAVA_SNIPPET",
+ "materialize",
+]
+
+POM_XML = """
+
+ 4.0.0
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ 3.4.5
+
+
+
+ io.devcapsule.demo
+ capsule-sprint
+ 0.1.0
+ CapsuleSprint
+ DevCapsule Spring Boot + PostgreSQL 17 Customer Pitch Demo
+
+
+ 21
+ UTF-8
+
+
+
+
+ org.springframework.boot
+ spring-boot-starter-web
+
+
+ org.springframework.boot
+ spring-boot-starter-jdbc
+
+
+ org.postgresql
+ postgresql
+ runtime
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
+"""
+
+MAVEN_CONFIG = "-Dmaven.repo.local=.m2/repository\n"
+
+APPLICATION_PROPERTIES = """server.port=${APP_PORT:18085}
+spring.application.name=capsule-sprint
+spring.datasource.url=${SPRING_DATASOURCE_URL:jdbc:postgresql://127.0.0.1:15432/sprintdb}
+spring.datasource.username=${SPRING_DATASOURCE_USERNAME:postgres}
+spring.datasource.password=${SPRING_DATASOURCE_PASSWORD:postgres}
+spring.sql.init.mode=always
+logging.level.root=WARN
+logging.level.io.devcapsule.demo=INFO
+logging.level.org.springframework.boot.web.embedded.tomcat=INFO
+"""
+
+SCHEMA_SQL = """CREATE TABLE IF NOT EXISTS sprint_items (
+ id SERIAL PRIMARY KEY,
+ code VARCHAR(24) NOT NULL,
+ title TEXT NOT NULL,
+ service VARCHAR(48) NOT NULL DEFAULT 'Core API',
+ resolved BOOLEAN NOT NULL DEFAULT FALSE
+);
+"""
+
+APPLICATION_JAVA = """package io.devcapsule.demo;
+
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+import org.springframework.jdbc.core.simple.JdbcClient;
+
+@SpringBootApplication
+public class CapsuleSprintApplication {
+
+ public static void main(String[] args) {
+ SpringApplication.run(CapsuleSprintApplication.class, args);
+ }
+
+ @Bean
+ CommandLineRunner seedDatabase(JdbcClient jdbc) {
+ return args -> {
+ Long count = jdbc.sql("SELECT COUNT(*) FROM sprint_items")
+ .query(Long.class)
+ .single();
+ if (count == 0) {
+ jdbc.sql("INSERT INTO sprint_items (code, title, service, resolved) VALUES "
+ + "('CAP-101', 'Bootstrap isolated IntelliJ + Java 25 capsule', 'Platform', true), "
+ + "('CAP-102', 'Wire HikariCP pool to PostgreSQL 17', 'Database', true)")
+ .update();
+ }
+ };
+ }
+}
+"""
+
+SPRINT_ITEM_JAVA = """package io.devcapsule.demo;
+
+public record SprintItem(
+ Long id,
+ String code,
+ String title,
+ String service,
+ boolean resolved
+) {}
+"""
+
+CREATE_ITEM_REQUEST_JAVA = """package io.devcapsule.demo;
+
+public record CreateItemRequest(
+ String title,
+ String service
+) {}
+"""
+
+RESOLVE_REQUEST_JAVA = """package io.devcapsule.demo;
+
+public record ResolveRequest(
+ boolean resolved
+) {}
+"""
+
+# Note: createItem (@PostMapping("/api/items")) is intentionally left with a single
+# placeholder line at line 45 so IntelliJ IDEA live-types the JdbcClient INSERT ... RETURNING
+# implementation during the recorded demo!
+SPRINT_CONTROLLER_JAVA = """package io.devcapsule.demo;
+
+import java.util.List;
+import java.util.Map;
+import org.springframework.http.HttpStatus;
+import org.springframework.jdbc.core.simple.JdbcClient;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.server.ResponseStatusException;
+
+@RestController
+public class SprintController {
+
+ private final JdbcClient jdbc;
+
+ public SprintController(JdbcClient jdbc) {
+ this.jdbc = jdbc;
+ }
+
+ @GetMapping("/api/health")
+ public Map health() {
+ String pgVersion = jdbc.sql("SHOW server_version").query(String.class).single();
+ Long total = jdbc.sql("SELECT COUNT(*) FROM sprint_items").query(Long.class).single();
+ return Map.of("ok", true, "postgres", pgVersion, "java", Runtime.version().toString(), "items", total);
+ }
+
+ @GetMapping("/api/items")
+ public List listItems() {
+ return jdbc.sql("SELECT id, code, title, service, resolved FROM sprint_items ORDER BY id ASC")
+ .query(SprintItem.class)
+ .list();
+ }
+
+ @PostMapping("/api/items")
+ @ResponseStatus(HttpStatus.CREATED)
+ public SprintItem createItem(@RequestBody CreateItemRequest req) {
+ String nextCode = "CAP-" + (101 + jdbc.sql("SELECT COUNT(*) FROM sprint_items").query(Long.class).single());
+ // Live IDE demo: insert sprint item into PostgreSQL and return mapped record
+ throw new ResponseStatusException(HttpStatus.NOT_IMPLEMENTED, "Live demo placeholder");
+ }
+
+ @PatchMapping("/api/items/{id}")
+ public SprintItem toggleResolved(@PathVariable Long id, @RequestBody ResolveRequest patch) {
+ return jdbc.sql("UPDATE sprint_items SET resolved = :resolved WHERE id = :id "
+ + "RETURNING id, code, title, service, resolved")
+ .param("resolved", patch.resolved())
+ .param("id", id)
+ .query(SprintItem.class)
+ .optional()
+ .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Item not found"));
+ }
+}
+"""
+
+TYPED_JAVA_SNIPPET = """ return jdbc.sql("INSERT INTO sprint_items (code, title, service) VALUES (:code, :title, :svc) RETURNING id, code, title, service, resolved")
+ .param("code", nextCode)
+ .param("title", req.title().trim())
+ .param("svc", req.service())
+ .query(SprintItem.class)
+ .single();
+"""
+
+INDEX_HTML = """
+
+
+
+
+ CapsuleSprint — Spring Boot + PostgreSQL 17
+
+
+
+
+
+
+
+
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