devlaunch 0.0.16__tar.gz → 0.0.18__tar.gz

{devlaunch-0.0.16 → devlaunch-0.0.18}/.gitignore

@@ -50,7 +50,6 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
-test/docker/results/
 
 # Translations
 *.mo

{devlaunch-0.0.16 → devlaunch-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.16
+Version: 0.0.18
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -57,6 +57,13 @@ Note: When using pip, you must install [devpod](https://devpod.sh/docs/getting-s
 If `devpod` is not on `PATH`, every command that needs it prints a single install hint on stderr and exits `127`
 (the shell's "command not found" code). `dl --help` and `dl --version` keep working without it.
 
+A `devpod` that is installed but cannot answer is a different failure and gets a different exit code. If
+`devpod list` exits non-zero, or prints something that is not a `--output json` workspace listing, `dl` quotes
+what devpod said on stderr and exits `1` rather than reporting that you have no workspaces — so `dl --purge`
+stops instead of deleting caches it never checked. Shell completion is the deliberate exception: `dl --install`,
+`dl --refresh` and `dl --completion-data` log the failure and carry on with the repos and branches they can
+still discover on local disk, so an unreachable devpod costs you workspace-name completion and nothing more.
+
 ### Shell Completions
 
 After installation, set up shell completions for `dl` and `aid`:
@@ -432,9 +439,87 @@ This project uses [pixi](https://pixi.sh) for environment management.
 # Run tests
 pixi run test
 
+# Run the e2e suite: real devpod, real containers
+pixi run test-e2e
+
 # Run full CI suite
 pixi run ci
 
 # Format and lint
 pixi run style
 ```
+
+`pixi run test` skips the e2e tests, which need devpod and a Docker daemon and
+build real containers. CI runs `pixi run test-e2e` in a job of its own, outside
+the Python matrix, on a throwaway runner — on every push to `main` and on every
+pull request that targets `main`. A pull request onto any other base runs no CI
+at all, e2e included, because the whole workflow is triggered by
+`pull_request: branches: [main]`; that gap covers every job here rather than
+this one, and stacked PRs are what walk into it.
+
+Running it yourself is a different proposition. This repo's devcontainer carries
+a Docker daemon of its own, through the `docker-in-docker` feature, and pins the
+same devpod a host installs, so `pixi run test-e2e` from inside it builds its
+containers in there rather than on your Docker. You can also run it on a machine
+you do not mind it writing to — an ephemeral CI runner, say. It is skipped by
+default rather than gated on a container, because what it needs is a daemon, not
+nesting. Either way the suite exercises `dl --purge`, so it gives itself a
+private devpod namespace before collection begins — but the containers it builds
+are real ones, and it wants several minutes and a 1.25 GB image pull the first
+time.
+
+Its skips mean one thing only. A test that opts out does so through
+`fixtures.e2e_guard.opt_out`, and any other skip is reported as a failure,
+because a run that could not reach a registry used to be indistinguishable from
+a healthy one. Every run also prints what it actually built:
+
+```
+--------------------------------- e2e session ---------------------------------
+22 e2e tests attempted, 4 workspaces created: e2e-test-create, e2e-test-lifecycle, e2e-test-git, e2e-test-purge
+```
+
+A run whose workspace-building tests built nothing does not pass: the shortfall
+is counted into the last line of the run, so `4 passed, 18 skipped` becomes
+`1 failed, 4 passed, 18 skipped`. A run with no workspace-building tests in it —
+`pytest -m e2e test/e2e/test_interactive_session.py`, say — has nothing to
+answer for and says so instead.
+
+`DEVLAUNCH_E2E_WORKSPACE=<id>` opts in to the interactive-session tests, which
+attach to a workspace you already have running rather than building one.
+
+The nested daemon is also why the devcontainer does not join the host's network
+namespace: a nested daemon needs a namespace of its own, or it co-manages the
+host's `docker0` bridge and writes its NAT rules into the host's netfilter
+tables.
+
+### Disk cost of the dev container
+
+Opening a devcontainer for a branch costs about **2 GB on the host before you do
+anything in it**: ~600 MB of image layers unique to this image, a ~680 MB container
+writable layer, and a ~520 MB `<workspace>-pixi` volume.
+
+The container carries its own Docker daemon, and that daemon's `/var/lib/docker`
+lives on a second named volume. One `pixi run test-e2e` plus a couple of nested
+workspaces puts **~2.3 GB** in there, and nothing garbage-collects it — the inner
+daemon reports ~45% of its images reclaimable with no reclaimer. Nested daemons
+share no layers with the host or with each other, so this is paid once per branch.
+
+**Budget ~4 GB per branch you are actively developing and e2e-testing — about 12 GB
+for three concurrent branches.**
+
+The time cost is cold pulls in a fresh nested daemon: the first `devpod up` inside a
+new container takes ~25s, ~16s of which is pulling a base image the host already has.
+Workspaces after that reuse it and take ~8s.
+
+**These volumes are not reclaimed automatically.** `devpod delete` removes the
+container with `docker rm` and never touches volumes, and Docker never
+garbage-collects a *named* volume — so `<workspace>-pixi` and
+`dind-var-lib-docker-*` outlive the workspace that created them. To see what has
+piled up:
+
+```bash
+docker system df -v      # under Local Volumes, LINKS 0 means no container uses it
+```
+
+Cross-check a name against `devpod list` before removing it with `docker volume rm`:
+a volume belonging to a live workspace shows `LINKS 1`.

{devlaunch-0.0.16 → devlaunch-0.0.18}/README.md

@@ -35,6 +35,13 @@ Note: When using pip, you must install [devpod](https://devpod.sh/docs/getting-s
 If `devpod` is not on `PATH`, every command that needs it prints a single install hint on stderr and exits `127`
 (the shell's "command not found" code). `dl --help` and `dl --version` keep working without it.
 
+A `devpod` that is installed but cannot answer is a different failure and gets a different exit code. If
+`devpod list` exits non-zero, or prints something that is not a `--output json` workspace listing, `dl` quotes
+what devpod said on stderr and exits `1` rather than reporting that you have no workspaces — so `dl --purge`
+stops instead of deleting caches it never checked. Shell completion is the deliberate exception: `dl --install`,
+`dl --refresh` and `dl --completion-data` log the failure and carry on with the repos and branches they can
+still discover on local disk, so an unreachable devpod costs you workspace-name completion and nothing more.
+
 ### Shell Completions
 
 After installation, set up shell completions for `dl` and `aid`:
@@ -410,9 +417,87 @@ This project uses [pixi](https://pixi.sh) for environment management.
 # Run tests
 pixi run test
 
+# Run the e2e suite: real devpod, real containers
+pixi run test-e2e
+
 # Run full CI suite
 pixi run ci
 
 # Format and lint
 pixi run style
 ```
+
+`pixi run test` skips the e2e tests, which need devpod and a Docker daemon and
+build real containers. CI runs `pixi run test-e2e` in a job of its own, outside
+the Python matrix, on a throwaway runner — on every push to `main` and on every
+pull request that targets `main`. A pull request onto any other base runs no CI
+at all, e2e included, because the whole workflow is triggered by
+`pull_request: branches: [main]`; that gap covers every job here rather than
+this one, and stacked PRs are what walk into it.
+
+Running it yourself is a different proposition. This repo's devcontainer carries
+a Docker daemon of its own, through the `docker-in-docker` feature, and pins the
+same devpod a host installs, so `pixi run test-e2e` from inside it builds its
+containers in there rather than on your Docker. You can also run it on a machine
+you do not mind it writing to — an ephemeral CI runner, say. It is skipped by
+default rather than gated on a container, because what it needs is a daemon, not
+nesting. Either way the suite exercises `dl --purge`, so it gives itself a
+private devpod namespace before collection begins — but the containers it builds
+are real ones, and it wants several minutes and a 1.25 GB image pull the first
+time.
+
+Its skips mean one thing only. A test that opts out does so through
+`fixtures.e2e_guard.opt_out`, and any other skip is reported as a failure,
+because a run that could not reach a registry used to be indistinguishable from
+a healthy one. Every run also prints what it actually built:
+
+```
+--------------------------------- e2e session ---------------------------------
+22 e2e tests attempted, 4 workspaces created: e2e-test-create, e2e-test-lifecycle, e2e-test-git, e2e-test-purge
+```
+
+A run whose workspace-building tests built nothing does not pass: the shortfall
+is counted into the last line of the run, so `4 passed, 18 skipped` becomes
+`1 failed, 4 passed, 18 skipped`. A run with no workspace-building tests in it —
+`pytest -m e2e test/e2e/test_interactive_session.py`, say — has nothing to
+answer for and says so instead.
+
+`DEVLAUNCH_E2E_WORKSPACE=<id>` opts in to the interactive-session tests, which
+attach to a workspace you already have running rather than building one.
+
+The nested daemon is also why the devcontainer does not join the host's network
+namespace: a nested daemon needs a namespace of its own, or it co-manages the
+host's `docker0` bridge and writes its NAT rules into the host's netfilter
+tables.
+
+### Disk cost of the dev container
+
+Opening a devcontainer for a branch costs about **2 GB on the host before you do
+anything in it**: ~600 MB of image layers unique to this image, a ~680 MB container
+writable layer, and a ~520 MB `<workspace>-pixi` volume.
+
+The container carries its own Docker daemon, and that daemon's `/var/lib/docker`
+lives on a second named volume. One `pixi run test-e2e` plus a couple of nested
+workspaces puts **~2.3 GB** in there, and nothing garbage-collects it — the inner
+daemon reports ~45% of its images reclaimable with no reclaimer. Nested daemons
+share no layers with the host or with each other, so this is paid once per branch.
+
+**Budget ~4 GB per branch you are actively developing and e2e-testing — about 12 GB
+for three concurrent branches.**
+
+The time cost is cold pulls in a fresh nested daemon: the first `devpod up` inside a
+new container takes ~25s, ~16s of which is pulling a base image the host already has.
+Workspaces after that reuse it and take ~8s.
+
+**These volumes are not reclaimed automatically.** `devpod delete` removes the
+container with `docker rm` and never touches volumes, and Docker never
+garbage-collects a *named* volume — so `<workspace>-pixi` and
+`dind-var-lib-docker-*` outlive the workspace that created them. To see what has
+piled up:
+
+```bash
+docker system df -v      # under Local Volumes, LINKS 0 means no container uses it
+```
+
+Cross-check a name against `devpod list` before removing it with `docker volume rm`:
+a volume belonging to a live workspace shows `LINKS 1`.

{devlaunch-0.0.16 → devlaunch-0.0.18}/devlaunch/devpod_provider.py

@@ -27,11 +27,25 @@ import subprocess
 from typing import Callable, Optional, Sequence, Set
 
 
-class UnreadableProviderList(RuntimeError):
+class UnreadableProviderList(Exception):
     """devpod's provider listing could not be read.
 
     Distinct from "no providers are registered", which is a listing that reads
     fine and is empty.
+
+    Not a RuntimeError. It used to be, and the CLI below then had to name
+    RuntimeError as well to catch the add failure -- which made the handler
+    broad enough to report any RuntimeError in the process as a devpod problem.
+    The two failures devpod can hand this module now have a type each, and the
+    handler names both and nothing else.
+    """
+
+
+class ProviderAddFailed(Exception):
+    """`devpod provider add` ran and failed.
+
+    Distinct from a listing that could not be read: devpod answered the question
+    it was asked, and then refused to do the thing.
     """
 
 
@@ -62,7 +76,8 @@ def list_provider_names(
     )
     if result.returncode != 0:
         raise UnreadableProviderList(
-            f"`devpod provider list` exited {result.returncode}: {(result.stderr or '').strip()[:200]}"
+            f"`devpod provider list` exited {result.returncode}: "
+            f"{(result.stderr or '').strip()[:200]!r}"
         )
     return parse_provider_names(result.stdout or "")
 
@@ -74,13 +89,21 @@ def ensure_provider(
 
     Returns True if it had to be added, False if it was already there. Raises
     `UnreadableProviderList` rather than guessing when devpod's answer cannot
-    be read.
+    be read, and `ProviderAddFailed` when the add itself fails.
     """
     if name in list_provider_names(run=run):
         return False
-    result = run(["devpod", "provider", "add", name], check=False)
+    result = run(
+        ["devpod", "provider", "add", name],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
     if result.returncode != 0:
-        raise RuntimeError(f"`devpod provider add {name}` exited {result.returncode}")
+        raise ProviderAddFailed(
+            f"`devpod provider add {name}` exited {result.returncode}: "
+            f"{(result.stderr or '').strip()[:200]!r}"
+        )
     return True
 
 
@@ -105,7 +128,7 @@ def main(
 
     try:
         added = ensure_provider(args.name, run=run)
-    except (UnreadableProviderList, RuntimeError) as exc:
+    except (UnreadableProviderList, ProviderAddFailed) as exc:
         print(f"error: {exc}")
         return 1
     print(f"devpod provider {args.name}: {'added' if added else 'already registered'}")

{devlaunch-0.0.16 → devlaunch-0.0.18}/devlaunch/dl.py

@@ -65,6 +65,26 @@ class SshNotInstalled(MissingBinary):
     """
 
 
+class UnreadableWorkspaceList(Exception):
+    """devpod's workspace listing could not be read.
+
+    Distinct from "this machine has no workspaces", which is a listing that
+    reads fine and is empty. The two used to share one representation -- an
+    empty list -- so `dl --purge` could report that there was nothing to purge
+    when the truth was that it never found out, and a workspace spec could be
+    called unknown when nothing had been asked.
+
+    Deliberately not a RuntimeError, for the same reason MissingBinary is not:
+    dl catches RuntimeError broadly wherever a flaky command should degrade
+    rather than abort, and an answer dl could not read is precisely the thing
+    that must not degrade. It travels as a type nothing in between catches, and
+    main() is the only place that handles it.
+
+    The sibling shape in devpod_provider deliberately reads the same way. Two
+    listings devpod can fail to produce, two exceptions that say so, one rule.
+    """
+
+
 # One line, so a completion helper that trips over it cannot spew into the
 # user's shell. It names both install routes because devpod ships with the
 # pixi/conda package and does not ship with the pip one (see README).
@@ -86,6 +106,10 @@ SSH_MISSING_MESSAGE = (
 # cannot be confused with a devpod command that ran and failed.
 DEVPOD_MISSING_EXIT_CODE = 127
 
+# devpod is there and dl asked it, but what came back could not be read. A plain
+# failure rather than 127: nothing is missing and nothing needs installing.
+UNREADABLE_WORKSPACE_LIST_EXIT_CODE = 1
+
 
 def _install_provenance() -> Optional[str]:
     """Describe the install this dl was launched from, or None if unremarkable.
@@ -268,8 +292,31 @@ def get_local_branches(owner_repo: str) -> List[str]:
 
 
 def update_completion_cache() -> Dict[str, Any]:
-    """Update the completion cache with current data."""
-    workspaces = list_workspaces()
+    """Update the completion cache with current data.
+
+    The one reader of the workspace list that has something to do with a listing
+    it cannot read. Everywhere else, an unreadable listing means the question
+    being asked cannot be answered at all, and UnreadableWorkspaceList travels
+    up to main() to say so. Here the workspace names are one of four things
+    being collected, and the other three -- repos, owners, branches -- come off
+    the local disk without asking devpod anything. So this catches, logs, and
+    builds completions out of what it can still see, deliberately: refusing
+    would mean an unreachable devpod stops `dl --install` from installing
+    completions at all, when what it costs is the workspace names.
+
+    The failure is logged rather than swallowed, because `dl --refresh` prints
+    the workspace count it got and zero-because-we-could-not-ask must not read
+    as zero-because-there-are-none. The cache this then writes offers no
+    workspace names until a later refresh succeeds -- which is what it did
+    before the listing learned to refuse -- and list_workspaces() still declines
+    to remember a list it never got, so the next command asks devpod again
+    instead of being served this one.
+    """
+    try:
+        workspaces = list_workspaces()
+    except UnreadableWorkspaceList as exc:
+        logging.warning(f"Completing without workspace names: {exc}")
+        workspaces = []
     workspace_ids = [ws.id for ws in workspaces]
     repos = discover_repos_from_workspaces(workspaces)
 
@@ -903,6 +950,38 @@ def invalidate_workspace_list_cache() -> None:
     _workspace_list_cache.pop(_WORKSPACE_LIST_KEY, None)
 
 
+def parse_workspaces(listing: str) -> List[Workspace]:
+    """The workspaces in a `devpod list --output json` listing.
+
+    Anything that is not such a listing raises rather than parsing to nothing.
+    That includes the empty string: devpod prints `[]` for a machine with no
+    workspaces, so silence is devpod failing to answer, not devpod answering
+    that there is nothing to list. Silence gets a branch of its own rather than
+    falling into the JSON parser, whose report of it -- `not JSON: ''` -- reads
+    like a bug in dl rather than a devpod that never spoke.
+    """
+    if not listing.strip():
+        raise UnreadableWorkspaceList(
+            "devpod said nothing when asked to list workspaces; it prints `[]` when there are none"
+        )
+    try:
+        parsed = json.loads(listing)
+    except json.JSONDecodeError as exc:
+        raise UnreadableWorkspaceList(
+            f"devpod's workspace listing is not JSON: {listing[:120]!r}"
+        ) from exc
+    if not isinstance(parsed, list):
+        raise UnreadableWorkspaceList(
+            f"expected devpod to list workspaces, got {type(parsed).__name__}"
+        )
+    for entry in parsed:
+        if not isinstance(entry, dict):
+            raise UnreadableWorkspaceList(
+                f"expected each listed workspace to be an object, got {type(entry).__name__}"
+            )
+    return [Workspace.from_json(ws) for ws in parsed]
+
+
 def list_workspaces(refresh: bool = False) -> List[Workspace]:
     """List all devpod workspaces, reading devpod at most once per command.
 
@@ -916,10 +995,15 @@ def list_workspaces(refresh: bool = False) -> List[Workspace]:
     refresh=True bypasses the snapshot for a caller that must have the
     post-mutation truth even if nothing announced the mutation.
 
-    Only an answer devpod actually gave is remembered. A failed or unparsable
-    read returns an empty list without caching it, so a transient failure — and
-    a missing devpod, which raises out of here — can never be served again as
-    "this machine has no workspaces".
+    Only an answer devpod actually gave is remembered, and only an answer devpod
+    actually gave is returned: a read that failed or could not be parsed raises
+    UnreadableWorkspaceList rather than answering with an empty list, so neither
+    a transient failure nor a missing devpod can be served to a caller as "this
+    machine has no workspaces".
+
+    Which of the workspaces devpod lists belong to dl is a separate question,
+    and not one this function answers. It answers only whether the list can be
+    believed at all.
     """
     if not refresh:
         cached = _workspace_list_cache.get(_WORKSPACE_LIST_KEY)
@@ -928,14 +1012,14 @@ def list_workspaces(refresh: bool = False) -> List[Workspace]:
             # be rewriting what the next caller sees.
             return list(cached)
     result = run_devpod(["list", "--output", "json"], capture=True)
-    if result.returncode != 0 or not result.stdout.strip():
-        return []
-    try:
-        data = json.loads(result.stdout)
-    except json.JSONDecodeError:
-        logging.error("Failed to parse devpod output")
-        return []
-    workspaces = [Workspace.from_json(ws) for ws in data]
+    if result.returncode != 0:
+        # !r for the same reason the parse path uses it: devpod's stderr is
+        # routinely several lines, and DEVPOD_MISSING_MESSAGE's comment sets the
+        # rule that one of dl's failure messages is one line.
+        raise UnreadableWorkspaceList(
+            f"`devpod list` exited {result.returncode}: {(result.stderr or '').strip()[:200]!r}"
+        )
+    workspaces = parse_workspaces(result.stdout or "")
     _workspace_list_cache[_WORKSPACE_LIST_KEY] = workspaces
     return list(workspaces)
 
@@ -1372,9 +1456,10 @@ def wants_startup_cache_refresh(args: List[str]) -> bool:
 def main(argv: Optional[List[str]] = None) -> int:
     """Main entry point for dl CLI.
 
-    Thin wrapper so there is exactly one handler for a missing devpod, however
-    deep in the command it was noticed. The message goes to stderr because
-    stdout is parsed by the completion machinery (--repos, --completion-data).
+    Thin wrapper so there is exactly one handler for a missing devpod, and one
+    for a devpod that answered with something dl could not read, however deep in
+    the command either was noticed. Both messages go to stderr because stdout is
+    parsed by the completion machinery (--repos, --completion-data).
 
     argv is the argument list without the program name, defaulting to the real
     one. It is a parameter so that a sibling entry point can hand dl a command
@@ -1390,6 +1475,9 @@ def main(argv: Optional[List[str]] = None) -> int:
     except MissingBinary as e:
         print(e, file=sys.stderr)
         return DEVPOD_MISSING_EXIT_CODE
+    except UnreadableWorkspaceList as e:
+        print(f"error: {e}", file=sys.stderr)
+        return UNREADABLE_WORKSPACE_LIST_EXIT_CODE
 
 
 def _run_cli(argv: Optional[List[str]] = None) -> int:

{devlaunch-0.0.16 → devlaunch-0.0.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.16"
+version = "0.0.18"
 authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
 description = "DevLaunch - A streamlined CLI for devpod workspaces"
 readme = "README.md"
@@ -90,6 +90,22 @@ lint = { depends-on = ["ruff-lint", "ty", "pylint"] }
 style = { depends-on = ["format", "lint"] }
 commit-format = "git commit -a -m'autoformat code' || true"
 test = "pytest"
+# Needs a real Docker daemon and a real devpod. Inside this repo's devcontainer
+# that daemon is the container's own, via the docker-in-docker feature; on an
+# ephemeral CI runner or a machine you do not mind writing to, it is the host's.
+#
+# The default run excludes e2e (see addopts); this is the way back in. A
+# trailing `-m e2e` beats the one in addopts, and `-ra` puts every skip's reason
+# in the summary, which is the whole difference between a run that opted out of
+# something and a run that could not do it.
+#
+# Deliberately no `depends-on = ["dev-add-docker"]`. The suite repoints
+# DEVPOD_HOME at a fresh directory in pytest_configure, before collection, so a
+# provider registered in the ambient ~/.devpod is one this run never reads:
+# test/e2e/conftest.py installs it into the run's own home instead. An edge here
+# would buy the suite nothing and write to the developer's real devpod home as a
+# side effect of running tests.
+test-e2e = "pytest -m e2e -ra test/e2e/"
 coverage = "coverage run -m pytest && coverage xml -o coverage.xml"
 coverage-report = "coverage report -m"
 update-lock = "pixi update && git commit -a -m'update pixi.lock' || true"
@@ -123,10 +139,13 @@ enable = "no-else-return,consider-using-in"
 markers = [
     "unit: Pure logic tests with no external commands. Fast, runs everywhere.",
     "integration: Real git commands, mocked DevPod. Catches git errors and path issues.",
-    "e2e: Full E2E with Docker-in-Docker. Real DevPod creating real containers.",
+    "e2e: Real DevPod creating real containers. Needs a Docker daemon.",
+    "creates_workspace: This e2e test builds a real workspace. The session floor in test/e2e/conftest.py holds a run that attempted one of these and built nothing to be a failure, so the promise is declared by the test rather than inferred afterwards.",
 ]
 testpaths = ["test"]
-# Default: run unit and integration tests, skip e2e (requires Docker-in-Docker)
+# Default: run unit and integration tests, skip e2e (which needs a daemon, and
+# creates and deletes real containers -- in a devpod home the suite makes for
+# the run, never the developer's)
 addopts = "-m 'not e2e'"
 
 [tool.coverage.run]