Skip to content

Phase 1 Milestone C: the phone commands (P1-11 to P1-14, P1-16) - #9

Merged
Axoineo merged 9 commits into
mainfrom
p1/milestone-c-commands
Nov 15, 2026
Merged

Axoineo merged 9 commits into
mainfrom
p1/milestone-c-commands

Conversation

@Axoineo

@Axoineo Axoineo commented Nov 15, 2026

Copy link
Copy Markdown
Owner

What changed

Milestone C of docs/phases/phase-1.md: the commands that make Verone usable from a terminal, plus the end-to-end test.

This branch is built on Milestone B (pull request #8), which was still open when this was pushed. Until #8 is merged, this pull request also shows its five commits. Merging this one brings in both.

Commits that belong to Milestone C:

Commit What it adds
14a47ab Three operations on the Engine trait: supports_android, erase_data, details
f60dde4 The fake engine now behaves like the real one on start, stop and endpoint
e41be88 create, list, info, start, stop, restart, open, adb, install, reset, delete
6237f02 tests/e2e/phase-1.sh, the Phase 1 exit test

Why

With these commands a phone can be created, run, used and removed without touching Docker directly. This is the roadmap's Phase 1 outcome, short of packaging and user documentation.

Acceptance tests

Run on the reference laptop (Arch Linux, kernel 7.3.4, Docker 29.9.3, Rust 1.99.1).

$ cargo fmt --check                              (exit 0)
$ cargo clippy --all-targets -- -D warnings      Finished
$ RUSTDOCFLAGS="-D warnings" cargo doc --no-deps Finished
$ cargo test
  verone-cli unit tests        46 passed
  verone-cli binary tests       8 passed
  verone-core                  74 passed; 1 ignored
  verone-engine-container      81 passed

$ VERONE_TEST_DOCKER=1 cargo test -p verone-engine-container --test integration
test result: ok. 5 passed; finished in 198.43s

The exit test, on a real phone, twice in a row:

$ APK=…/fdroid.apk tests/e2e/phase-1.sh
== doctor            9 checks ok
== create            Created the phone 'e2e' with Android 14.
== start             The phone 'e2e' is running. It booted in 25.1 seconds using the GPU.
== open              scrcpy attached, "Time limit reached"
== adb               boot_completed = 1, Android release = 14
== install           Installed org.fdroid.fdroid on the phone 'e2e'.
== stop, start       the app survives
== restart           the app survives
== two commands at once   first exit 0, second exit 5
== reset             the app is gone
== delete            folder and container removed
Phase 1 exit test passed.          (run 1: exit 0; run 2: exit 0)

How each task's "Done when" is met:

  • P1-11: create, duplicate id (exit 1), bad id (exit 2), empty list and parseable JSON are unit-tested; also checked in the exit test.
  • P1-12: start prints the boot time; start on a running phone and stop on a stopped phone say so and exit 0; two simultaneous starts give exit 0 and exit 5.
  • P1-13: open … -- --no-window --time-limit=5 exits 0; adb … -- shell getprop sys.boot_completed prints 1; installing the F-Droid APK succeeds and names the package.
  • P1-14: after reset the app is gone and the phone boots; after delete the folder and container are gone; answering "no" changes nothing.
  • P1-16: the script exits 0 twice in a row.

Notes for the reviewer

  • The Engine trait grew by three operations. Reset and delete must remove root-owned data, which only the engine can do; info needs data size and uptime; create needs to reject an unsupported Android version without downloading. The architecture document's table of engine operations should gain these rows in P1-18.
  • install names the app by comparing the package list before and after. When the app replaces one already installed, it says so instead of naming a package.
  • Known limit, as planned: "Power off" chosen inside Android brings the phone back, because the restart policy cannot tell it from a restart. verone stop is the way to switch a phone off.
  • GPU boots are slower than software boots here (about 22 to 26 s against 11 to 14 s), though the screen draws faster once up. Worth revisiting when the desktop app measures real use.
  • One slow unit test: the busy-lock test waits the full 10-second lock time.
  • P1-16 is included early. It belongs to Milestone D, but it is the proof that Milestone C works. Milestone D still has packaging (P1-17) and documentation (P1-18).
  • No new crates in this milestone beyond tempfile as a dev-dependency of the command-line crate.

🤖 Generated with Claude Code

Axoineo and others added 9 commits November 15, 2026 12:24
Define the Engine trait in verone-core with the operations every
engine provides: check_host, prepare_image, create, destroy, start,
stop, status, control_endpoint and capabilities, plus the types they
exchange (host checks, phone status, boot report, control endpoint,
capabilities).

Add FakeEngine, an in-memory engine that records calls, simulates
phone states and can be told to fail the next call, so front ends can
be tested without a container runtime.

Change the plan's rule 1 at the owner's request: one branch and pull
request per milestone, with one commit per task.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add typed wrappers around the Docker command line in
verone-engine-container: version, info, image presence, pull, create,
start, update of the restart policy, kill, remove, inspect, exec,
one-off runs and published ports. All calls go through the core
process runner, and JSON output is parsed into the fields Verone uses.

Unit tests run against a stub script standing in for the runtime.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add HostProbe to verone-engine-container. It checks that the runtime
is installed and reachable, that the kernel offers binder, that the
running kernel's modules are installed, that there is disk space where
the runtime stores images and where phone data lives, and that memory
is sufficient. It also reports which graphics mode 'auto' would pick
and whether adb and scrcpy are installed.

The probe's root folder, search path and free-space lookup can be
replaced, so every check is tested against a fake system tree.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add the image table with the Android 14 image pinned by digest, and
the pinned helper image used for file operations on root-owned data.

Add ContainerEngine, which implements the Engine trait on Docker:
- builds the container options from the phone profile and stores them
  in a label, so a changed profile recreates the container while the
  data stays;
- resolves the graphics mode itself: GPU when a usable render node
  exists, otherwise software, never a node driven by the nvidia driver;
- waits for Android to report a finished boot, and in auto mode falls
  back to software once if GPU mode does not come up;
- stops a phone by switching the restart policy off and powering
  Android off from inside, because the runtime's stop only kills it;
- erases phone data through the helper image.

Add an adb helper that verifies the connection before each use and
drops a stale one, and a hint for the case where the runtime cannot
publish the optional adb port.

Integration tests boot real phones when VERONE_TEST_DOCKER=1 is set.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add 'verone doctor', which prints every host check with its fix and
exits with code 3 if any check failed, and 'verone image pull' and
'verone image list'. All three support --json.

The doctor command was planned as P1-15. It is added here because the
acceptance test of P1-07 needs it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add three operations to the Engine trait: supports_android (checks an
Android version without downloading), erase_data (deletes a phone's
root-owned Android data) and details (data size and uptime). Implement
them for the container engine and the fake engine.

The container engine measures data size from inside a container and
reads uptime from the container's start time. Erasing skips the helper
image when the data folder is already empty.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Starting a phone now creates what is missing, stopping a phone with
nothing running is not an error, and a phone that was never started is
reported as not running. These match the container engine, so command
tests written against the fake hold for the real engine.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add create, list and info (P1-11); start, stop and restart (P1-12);
open, adb and install (P1-13); reset and delete (P1-14).

Commands that change a phone take its lock, so a second command on the
same phone fails as busy. start runs the host checks first and refuses
with the host-check exit code if any fail. reset and delete stop the
phone cleanly, ask for confirmation unless --yes is given, and remove
Android's root-owned data through the engine.

All commands are generic over the Engine trait and are unit-tested with
the fake engine and stub adb and scrcpy scripts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
tests/e2e/phase-1.sh runs every command against a real phone in its own
data home: doctor, create, start, info, open, adb, install, stop and
start with the app surviving, restart, two simultaneous starts, reset
with the app gone, and delete.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@Axoineo
Axoineo merged commit 673227e into main Nov 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant