devlaunch 0.0.17__tar.gz → 0.0.19__tar.gz

{devlaunch-0.0.17 → devlaunch-0.0.19}/.gitignore

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

{devlaunch-0.0.17 → devlaunch-0.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.17
+Version: 0.0.19
 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`:
@@ -333,7 +340,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 |---------|-------------|
 | `dl --ls` | List all workspaces |
 | `dl --install` | Install shell completions |
-| `dl --purge [-y]` | Remove all devlaunch data |
+| `dl --purge [-y]` | Remove all devlaunch data — [the workspaces devlaunch created](#what-purge-deletes), and its caches |
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
 | `dl --refresh` | Refresh completion cache |
 | `dl --help, -h` | Show this help |
@@ -355,6 +362,40 @@ dl 0.0.9 (dev, editable from /path/to/your/devlaunch)
 from the installed package's own PEP 610 metadata; an install that records none
 just prints the bare version.
 
+### What purge deletes
+
+devpod's workspace list is shared. A workspace you made with `devpod up`, or that
+another tool made, sits in the same list as the ones `dl` made, and `dl --purge`
+has no business destroying it. So it deletes only the workspaces devlaunch
+created — the clones it made under its own cache directory (`$XDG_CACHE_HOME` or
+`~/.cache`, then `devlaunch/repos/<owner>/<repo>/<id>`), which is exactly the
+directory the purge is about to remove anyway. Everything else keeps working
+afterwards, because nothing a purge touches backs it.
+
+Anything it is leaving is named before it asks:
+
+```
+$ dl --purge
+This will remove all devlaunch data:
+  - 4 DevPod workspace(s)
+  - /home/you/.cache/devlaunch/ (workspace clones, repo caches, completions)
+
+Leaving 2 workspace(s) devlaunch did not create:
+  - pythontemplate
+  - my-hand-made-workspace
+
+Are you sure? [y/N]
+```
+
+Three things `dl` does create are in that second list rather than the first.
+`dl ./some/path` and `dl <git-url>` open a source `dl` did not clone, so it
+cannot tell them from a workspace you made by hand — and a `config.toml` that
+points `repos_dir` outside the cache puts the clones somewhere `--purge` does not
+remove either, so those are left too. Delete any of them with `dl <workspace> rm`.
+Erring this way is deliberate — a purge that skips one of your own workspaces
+costs you a command, and the other kind of mistake costs you work you cannot get
+back.
+
 ## Examples
 
 ```bash
@@ -432,9 +473,96 @@ 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, whatever branch that pull request targets. Stacked chains, where
+each link targets its predecessor rather than `main`, get the same CI as anything
+else.
+
+Alongside the matrix and e2e there is a `gate` job that does nothing but fail
+unless every other job in that workflow succeeded. It exists so that a branch
+ruleset has one stable name to require rather than a list: requiring the jobs one
+by one means literal strings in a repository setting, which nobody reviews and
+which goes stale the moment a job is added or renamed — and a required check that
+no longer exists does not turn a merge red, it stops gating it. Adding a job
+means adding it to `gate`'s `needs`, in the same pull request, where it can be
+seen. It reaches only as far as its own workflow file, so the `prek` lint job is
+not behind it and has to be required alongside 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, 5 workspaces created: e2e-test-create, e2e-test-lifecycle, e2e-test-git, e2e-purge-devlaunchs, e2e-purge-hand-made
+```
+
+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.17 → devlaunch-0.0.19}/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`:
@@ -311,7 +318,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 |---------|-------------|
 | `dl --ls` | List all workspaces |
 | `dl --install` | Install shell completions |
-| `dl --purge [-y]` | Remove all devlaunch data |
+| `dl --purge [-y]` | Remove all devlaunch data — [the workspaces devlaunch created](#what-purge-deletes), and its caches |
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
 | `dl --refresh` | Refresh completion cache |
 | `dl --help, -h` | Show this help |
@@ -333,6 +340,40 @@ dl 0.0.9 (dev, editable from /path/to/your/devlaunch)
 from the installed package's own PEP 610 metadata; an install that records none
 just prints the bare version.
 
+### What purge deletes
+
+devpod's workspace list is shared. A workspace you made with `devpod up`, or that
+another tool made, sits in the same list as the ones `dl` made, and `dl --purge`
+has no business destroying it. So it deletes only the workspaces devlaunch
+created — the clones it made under its own cache directory (`$XDG_CACHE_HOME` or
+`~/.cache`, then `devlaunch/repos/<owner>/<repo>/<id>`), which is exactly the
+directory the purge is about to remove anyway. Everything else keeps working
+afterwards, because nothing a purge touches backs it.
+
+Anything it is leaving is named before it asks:
+
+```
+$ dl --purge
+This will remove all devlaunch data:
+  - 4 DevPod workspace(s)
+  - /home/you/.cache/devlaunch/ (workspace clones, repo caches, completions)
+
+Leaving 2 workspace(s) devlaunch did not create:
+  - pythontemplate
+  - my-hand-made-workspace
+
+Are you sure? [y/N]
+```
+
+Three things `dl` does create are in that second list rather than the first.
+`dl ./some/path` and `dl <git-url>` open a source `dl` did not clone, so it
+cannot tell them from a workspace you made by hand — and a `config.toml` that
+points `repos_dir` outside the cache puts the clones somewhere `--purge` does not
+remove either, so those are left too. Delete any of them with `dl <workspace> rm`.
+Erring this way is deliberate — a purge that skips one of your own workspaces
+costs you a command, and the other kind of mistake costs you work you cannot get
+back.
+
 ## Examples
 
 ```bash
@@ -410,9 +451,96 @@ 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, whatever branch that pull request targets. Stacked chains, where
+each link targets its predecessor rather than `main`, get the same CI as anything
+else.
+
+Alongside the matrix and e2e there is a `gate` job that does nothing but fail
+unless every other job in that workflow succeeded. It exists so that a branch
+ruleset has one stable name to require rather than a list: requiring the jobs one
+by one means literal strings in a repository setting, which nobody reviews and
+which goes stale the moment a job is added or renamed — and a required check that
+no longer exists does not turn a merge red, it stops gating it. Adding a job
+means adding it to `gate`'s `needs`, in the same pull request, where it can be
+seen. It reaches only as far as its own workflow file, so the `prek` lint job is
+not behind it and has to be required alongside 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, 5 workspaces created: e2e-test-create, e2e-test-lifecycle, e2e-test-git, e2e-purge-devlaunchs, e2e-purge-hand-made
+```
+
+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.17 → devlaunch-0.0.19}/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.17 → devlaunch-0.0.19}/devlaunch/dl.py

@@ -22,13 +22,12 @@ import sys
 import subprocess
 import json
 import logging
-import os
 import pathlib
 import re
 import shlex
 import time
 from importlib.metadata import version as pkg_version, PackageNotFoundError, distribution
-from typing import List, Optional, Dict, Any
+from typing import Any, Dict, List, Mapping, NoReturn, Optional, Sequence, Tuple
 from dataclasses import dataclass
 from urllib.parse import urlparse
 from urllib.request import url2pathname
@@ -39,6 +38,7 @@ from .workspace_id import TARGET_LENGTH, WorkspaceId, slug, source_workspace_id,
 from .worktree.config import get_worktree_config
 from .worktree.migration import migrate_cache
 from .worktree.workspace_clone import WorkspaceCloneManager
+from .xdg import devlaunch_cache
 
 
 class MissingBinary(Exception):
@@ -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.
@@ -138,11 +162,15 @@ logging.basicConfig(level=logging.INFO, format="%(message)s")
 
 
 def _get_cache_dir() -> pathlib.Path:
-    """Get the cache directory, honoring XDG_CACHE_HOME."""
-    xdg_cache = os.environ.get("XDG_CACHE_HOME")
-    if xdg_cache:
-        return pathlib.Path(xdg_cache) / "devlaunch"
-    return pathlib.Path.home() / ".cache" / "devlaunch"
+    """Get the cache directory, honoring XDG_CACHE_HOME.
+
+    The answer comes from devlaunch.xdg so that this, the worktree config's
+    default `repos_dir` and metadata.json's default path cannot drift apart --
+    is_devlaunch_clone decides what `--purge` may delete by asking whether a
+    workspace's source is under this directory, and the clones it is asking
+    about were put there by the other two.
+    """
+    return devlaunch_cache()
 
 
 # Cache configuration (honors XDG_CACHE_HOME)
@@ -268,8 +296,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)
 
@@ -381,32 +432,39 @@ def update_cache_background(force: bool = False) -> None:
 
 
 def purge_all_data() -> int:
-    """Purge all devlaunch data including DevPod workspaces and caches.
+    """Purge devlaunch's data: the workspaces it created, and its caches.
 
     This:
-    1. Deletes all DevPod workspaces
+    1. Deletes the DevPod workspaces devlaunch created -- see
+       is_devlaunch_clone for what that means, and for what it leaves alone.
     2. Removes ~/.cache/devlaunch/ which contains:
        - completions.json, completions.bash (completion caches)
+
+    Workspaces devlaunch did not create are not deleted and not reported here;
+    the report belongs with the confirmation, before anything is destroyed, so
+    it lives in main() where the user still has a decision to make.
     """
     import shutil
 
     cache_dir = _get_cache_dir()
 
-    # First, delete all DevPod workspaces. The list is the same snapshot the
-    # caller printed the count from, so the confirmation the user answered and
-    # the set actually deleted cannot disagree.
-    workspaces = list_workspaces()
-    for ws in workspaces:
+    # First, delete the DevPod workspaces devlaunch made. The list is the same
+    # snapshot the caller printed the count from -- list_workspaces() is
+    # memoized per command and nothing between the two reads changes what devpod
+    # would say -- so the confirmation the user answered and the set actually
+    # deleted cannot disagree.
+    owned = workspace_ownership(list_workspaces(), cache_dir)
+    for ws in owned.mine:
         print(f"Deleting DevPod workspace: {ws.id}")
         result = run_devpod(["delete", ws.id, "--force"], capture=True)
         if result.returncode != 0:
             logging.warning(f"Failed to delete workspace {ws.id}: {result.stderr}")
-    if workspaces:
+    if owned.mine:
         invalidate_workspace_list_cache()
 
     # Then remove local cache
     if not cache_dir.exists():
-        if not workspaces:
+        if not owned.mine:
             print("No data to purge.")
         return 0
 
@@ -650,41 +708,235 @@ def validate_workspace_spec(spec: str, existing_ids: List[str]) -> Optional[str]
     return f"Unknown workspace '{spec}'. Use 'dl --ls' to list workspaces, or specify owner/repo or ./path"
 
 
+@dataclass(frozen=True)
+class LocalFolder:
+    """devpod is opening a directory on this machine."""
+
+    path: str
+
+
+@dataclass(frozen=True)
+class GitRepository:
+    """devpod is opening a repository it clones itself, named by URL.
+
+    Never a path on this machine, which is why the purge predicate can refuse
+    this arm outright instead of asking where it points.
+    """
+
+    url: str
+
+
+@dataclass(frozen=True)
+class UnrecognisedSource:
+    """A `devpod list` source devlaunch has no reading for, kept verbatim.
+
+    Reachable rather than defensive: devpod's workspace source also carries
+    `image` and `container`, so `devpod up ubuntu:24.04` lands here. Holding the
+    payload rather than a rendering of it is the whole point -- the field this
+    replaced was typed as a path and filled with `str(the dict)`, so the one
+    thing a caller could not do with it was read what devpod had said.
+
+    It deliberately has no path and no URL. There is nothing to make it say
+    where the source lives, because devlaunch does not know.
+    """
+
+    payload: Mapping[str, Any]
+
+
+WorkspaceSource = LocalFolder | GitRepository | UnrecognisedSource
+
+
+def _unhandled_source(source: NoReturn) -> NoReturn:
+    """Reject a source arm nobody handled -- at type-check time, not at runtime.
+
+    `ty` runs in CI, so passing anything but `Never` here is a build failure:
+    adding an arm to WorkspaceSource breaks every reader that has not grown a
+    case for it. That is the property this type exists for, and it is why this
+    body should be unreachable in a passing build.
+
+    Hand-rolled rather than `typing.assert_never`, which is 3.11+ while this
+    package supports 3.10. A parameter typed `NoReturn` gets the same treatment
+    from the checker.
+    """
+    raise AssertionError(f"Unhandled workspace source: {source!r}")
+
+
+def _readable_text(source: Mapping[str, Any], key: str) -> Optional[str]:
+    """*key* from *source* if devpod filled it with text, else None.
+
+    devpod's listing is JSON dl did not write, so `source[key]` is whatever the
+    JSON held. Returning None for anything else is what keeps the arms below
+    from being handed a value of a type their field does not describe.
+    """
+    value = source.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def parse_workspace_source(source: Mapping[str, Any]) -> WorkspaceSource:
+    """Read one `devpod list --output json` source object.
+
+    The keys are checked in devpod's own order of specificity: a source object
+    carrying both is a devpod that has changed under us, and taking the first
+    match keeps that from silently becoming the other one.
+
+    An arm is only as honest as the value put into it, so a key has to be
+    non-empty text before it counts. Both halves of that are load-bearing rather
+    than tidy. `git -C ""` is a no-op that succeeds, so a `LocalFolder("")`
+    reaching repo discovery would be credited with whatever repository the
+    person running `dl` happened to be standing in. And a `localFolder` that is
+    itself an object would put a dict in a field typed as a path -- the exact
+    thing this type exists to make unrepresentable -- which the two readers that
+    treat it as a path raise `TypeError` on.
+
+    Neither is an unreadable *listing*, unlike a `source` that is not an object
+    at all: the object is right here and can be kept whole. It is a source dl
+    cannot read, which is an arm.
+
+    Note this is the one link in the chain the type checker cannot stand in for
+    a test. A *reader* that misses an arm is a build failure, but this is a
+    producer, and a producer that quietly stops producing an arm type-checks
+    fine -- so the arms it picks are pinned by tests instead.
+    """
+    path = _readable_text(source, "localFolder")
+    if path is not None:
+        return LocalFolder(path)
+    url = _readable_text(source, "gitRepository")
+    if url is not None:
+        return GitRepository(url)
+    return UnrecognisedSource(dict(source))
+
+
+def describe_source(source: WorkspaceSource) -> Tuple[str, str]:
+    """How a source reads in `dl --ls` and in the fzf picker: (kind, detail).
+
+    One function for both columns, and one function for both callers, so the
+    kind shown and the detail shown cannot come from two different readings of
+    the same source -- which is what a tag beside a parallel field allowed.
+
+    An unreadable source shows the payload as JSON. That is a debug rendering
+    and is meant to be: the listing's job is to put the row on screen rather
+    than pass over it, and devlaunch has nothing truer to say about it.
+    """
+    if isinstance(source, LocalFolder):
+        return "local", source.path
+    if isinstance(source, GitRepository):
+        return "git", source.url
+    if isinstance(source, UnrecognisedSource):
+        return "unknown", json.dumps(source.payload)
+    _unhandled_source(source)
+
+
 @dataclass
 class Workspace:
     """Represents a devpod workspace."""
 
     id: str
-    source_type: str  # "local" or "git"
-    source: str
+    source: WorkspaceSource
     last_used: str
     provider: str
     ide: str
 
     @classmethod
-    def from_json(cls, data: Dict[str, Any]) -> "Workspace":
+    def from_json(cls, data: Mapping[str, Any]) -> "Workspace":
         """Parse workspace from devpod JSON output."""
-        source = data.get("source", {})
-        if "localFolder" in source:
-            source_type = "local"
-            source_path = source["localFolder"]
-        elif "gitRepository" in source:
-            source_type = "git"
-            source_path = source["gitRepository"]
-        else:
-            source_type = "unknown"
-            source_path = str(source)
-
         return cls(
             id=data.get("id", ""),
-            source_type=source_type,
-            source=source_path,
+            source=parse_workspace_source(data.get("source", {})),
             last_used=data.get("lastUsed", ""),
             provider=data.get("provider", {}).get("name", ""),
             ide=data.get("ide", {}).get("name", ""),
         )
 
 
+def is_devlaunch_clone(workspace: Workspace, cache_dir: pathlib.Path) -> bool:
+    """Whether *workspace* is one devlaunch made, rather than someone else's.
+
+    devpod's workspace namespace is shared: `devpod up` by hand, another tool
+    and an older devlaunch all land in the same list, and devlaunch has no
+    business destroying any of them. The question this answers is the narrow
+    one -- *did I make this* -- and it is answered from where the workspace's
+    source lives.
+
+    Every workspace `dl owner/repo[@branch]` creates is a clone devlaunch put
+    under its own cache directory (`<cache>/repos/<owner>/<repo>/<id>`, see
+    WorkspaceCloneManager.get_workspace_path) and then handed to `devpod up` as
+    a path, so devpod records that path as the source. That makes the predicate
+    say something true of `--purge` rather than merely correlated with it: the
+    cache directory is exactly what a purge removes, so the workspaces it
+    deletes are the ones whose source it is about to delete anyway. Anything
+    else keeps working afterwards, because nothing a purge touches backs it.
+
+    Chosen over reading metadata.json, which also records these ids, for two
+    reasons. metadata.json lives *inside* the cache directory a purge removes,
+    and `purge_all_data` only warns when `devpod delete` fails -- so one failed
+    delete plus one successful purge would leave a workspace no later purge
+    could ever recognise. And the record is append-mostly: nothing prunes it,
+    so it accumulates entries for workspaces that are long gone. A source path
+    is read back from devpod itself every time, and survives the cache it names.
+
+    Deliberately conservative in two places. A `git` or unrecognised source is
+    never ours: devlaunch always passes devpod a local path. And the comparison
+    is a path containment test, not a string prefix -- `<cache>-scratch` shares
+    six characters with `<cache>` and is not inside it.
+
+    That first refusal is now half structural. An unrecognised source has no
+    path on it at all, so there is nothing to test for containment and no way
+    to write the mistake; a git source does carry a string that could be one --
+    `devpod up <path-to-bare-repo>` records a `gitRepository`, and nothing
+    stops that repo living in the cache -- so refusing that arm is a decision
+    this function still has to make, and it is made by name.
+
+    Not every workspace dl creates is recognised. `dl ./path` and `dl <git-url>`
+    open a source dl did not clone and does not record anywhere, and a
+    `config.toml` that points `repos_dir` outside the cache puts the clones
+    somewhere `--purge` does not remove either -- so all three read as someone
+    else's. That is the safe direction to be wrong in, it keeps this predicate
+    and what a purge actually destroys answering to the same directory, and
+    `--purge` names what it leaves rather than passing over it in silence.
+    """
+    source = workspace.source
+    if isinstance(source, LocalFolder):
+        path = pathlib.PurePath(source.path)
+        # Purely lexical, so a clone whose directory has already been removed is
+        # still recognisable from the source devpod kept.
+        return path != pathlib.PurePath(cache_dir) and path.is_relative_to(cache_dir)
+    if isinstance(source, (GitRepository, UnrecognisedSource)):
+        return False
+    _unhandled_source(source)
+
+
+@dataclass(frozen=True)
+class WorkspaceOwnership:
+    """A `devpod list` answer split by whether devlaunch created each workspace.
+
+    A value rather than a filter applied at the point of deletion: `--purge`
+    prints a count and then deletes a set, and those two cannot disagree if they
+    read the same object. It also gives the workspaces devlaunch does *not* own
+    somewhere to be named from, which is the difference between a purge that
+    surprises a user with survivors and one that lists them.
+    """
+
+    mine: Tuple[Workspace, ...]
+    foreign: Tuple[Workspace, ...]
+
+
+def workspace_ownership(
+    workspaces: Sequence[Workspace], cache_dir: pathlib.Path
+) -> WorkspaceOwnership:
+    """Split *workspaces* into the ones devlaunch made and the ones it did not.
+
+    Total: every workspace lands in exactly one arm, and listing order is kept
+    within each, so what is printed reads in the order devpod gave.
+    """
+    mine: List[Workspace] = []
+    foreign: List[Workspace] = []
+    for ws in workspaces:
+        # One pass, so the predicate is asked once per workspace and the two
+        # arms cannot be built from two different answers to the same question.
+        (mine if is_devlaunch_clone(ws, cache_dir) else foreign).append(ws)
+    return WorkspaceOwnership(mine=tuple(mine), foreign=tuple(foreign))
+
+
 # Regex patterns for parsing git URLs
 GIT_URL_PATTERNS = [
     # git@github.com:owner/repo.git
@@ -753,22 +1005,39 @@ def discover_repos_from_workspaces(workspaces: List[Workspace]) -> Dict[str, Lis
     """Discover owner/repo from workspace git remotes.
 
     Returns dict mapping owner -> list of repos.
+
+    Every source is answered, including the ones devlaunch cannot read. There
+    is no owner/repo to be had from an image reference, so the answer for that
+    arm is still "nothing discovered" -- but it is said rather than reached by
+    falling off the end of the chain, which is what used to make it
+    indistinguishable from a source that was read fine and held no repo.
     """
     repos: Dict[str, List[str]] = {}
 
     for ws in workspaces:
         owner_repo = None
+        source = ws.source
 
         # For git workspaces, parse the source URL directly
-        if ws.source_type == "git":
-            owner_repo = parse_owner_repo_from_url(ws.source)
+        if isinstance(source, GitRepository):
+            owner_repo = parse_owner_repo_from_url(source.url)
 
         # For local workspaces, try to get git remote
-        elif ws.source_type == "local" and ws.source:
-            remote_url = get_git_remote_url(ws.source)
+        elif isinstance(source, LocalFolder):
+            remote_url = get_git_remote_url(source.path)
             if remote_url:
                 owner_repo = parse_owner_repo_from_url(remote_url)
 
+        elif isinstance(source, UnrecognisedSource):
+            logging.warning(
+                f"Not looking for a repo in workspace '{ws.id}': "
+                f"devpod describes its source as {json.dumps(source.payload)}, "
+                "which devlaunch cannot read."
+            )
+
+        else:
+            _unhandled_source(source)
+
         if owner_repo:
             owner, repo = owner_repo
             if owner not in repos:
@@ -903,6 +1172,50 @@ 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.
+
+    A `source` that is not an object is refused here for the same reason. The
+    source arms below are total over the object devpod documents, and the arm
+    for a source dl cannot read holds that object -- so something that is not
+    one is not an unreadable source, it is an unreadable *listing*, and that is
+    the answer this function already knows how to give.
+    """
+    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__}"
+            )
+        source = entry.get("source", {})
+        if not isinstance(source, dict):
+            raise UnreadableWorkspaceList(
+                f"expected workspace {entry.get('id', '')!r} to have an object for its "
+                f"source, got {type(source).__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 +1229,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 +1246,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)
 
@@ -952,10 +1270,14 @@ def print_workspaces():
         print("No workspaces found.")
         return
 
+    # Describe each source once, so the widths are measured on the same strings
+    # that get printed.
+    rows = [(ws, *describe_source(ws.source)) for ws in workspaces]
+
     # Calculate column widths
-    id_width = max(len(ws.id) for ws in workspaces)
-    type_width = max(len(ws.source_type) for ws in workspaces)
-    source_width = max(len(ws.source) for ws in workspaces)
+    id_width = max(len(ws.id) for ws, _kind, _detail in rows)
+    type_width = max(len(kind) for _ws, kind, _detail in rows)
+    source_width = max(len(detail) for _ws, _kind, detail in rows)
 
     # Print header
     print(
@@ -964,11 +1286,9 @@ def print_workspaces():
     print("-" * (id_width + type_width + source_width + 30))
 
     # Print rows
-    for ws in workspaces:
+    for ws, kind, detail in rows:
         last_used = ws.last_used[:19].replace("T", " ") if ws.last_used else "never"
-        print(
-            f"{ws.id:<{id_width}}  {ws.source_type:<{type_width}}  {ws.source:<{source_width}}  {last_used}"
-        )
+        print(f"{ws.id:<{id_width}}  {kind:<{type_width}}  {detail:<{source_width}}  {last_used}")
 
 
 def fuzzy_select_workspace() -> Optional[str]:
@@ -988,7 +1308,8 @@ def fuzzy_select_workspace() -> Optional[str]:
     options = []
     ws_map = {}
     for ws in workspaces:
-        label = f"{ws.id} | {ws.source_type} | {ws.source}"
+        kind, detail = describe_source(ws.source)
+        label = f"{ws.id} | {kind} | {detail}"
         options.append(label)
         ws_map[label] = ws.id
 
@@ -1299,7 +1620,7 @@ Global commands:
     dl --ls                          List all workspaces
     dl --install                     Install shell completions
     dl --refresh                     Refresh completion cache
-    dl --purge [-y]                  Remove all DevPod workspaces and caches
+    dl --purge [-y]                  Remove devlaunch's workspaces and caches
     dl --help, -h                    Show this help
     dl --version                     Show version (editable installs name their tree)
 
@@ -1372,9 +1693,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 +1712,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:
@@ -1485,10 +1810,18 @@ def _run_cli(argv: Optional[List[str]] = None) -> int:
         # Check for -y flag to skip confirmation
         skip_confirm = len(args) > 1 and args[1] in ("-y", "--yes")
         cache_dir = _get_cache_dir()
-        workspaces = list_workspaces()
+        owned = workspace_ownership(list_workspaces(), cache_dir)
         print("This will remove all devlaunch data:")
-        print(f"  - {len(workspaces)} DevPod workspace(s)")
+        print(f"  - {len(owned.mine)} DevPod workspace(s)")
         print(f"  - {cache_dir}/ (workspace clones, repo caches, completions)")
+        # Named, not merely excluded from the count: a user who asked for a
+        # clean slate and gets survivors should learn it here, while saying no
+        # is still an option, rather than from a later `dl --ls`.
+        if owned.foreign:
+            print()
+            print(f"Leaving {len(owned.foreign)} workspace(s) devlaunch did not create:")
+            for ws in owned.foreign:
+                print(f"  - {ws.id}")
         print()
         if skip_confirm:
             return purge_all_data()

{devlaunch-0.0.17 → devlaunch-0.0.19}/devlaunch/worktree/config.py

@@ -1,21 +1,12 @@
 """Configuration management for worktree backend."""
 
-import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Dict, Optional, Union
 
 import tomli
 
-from devlaunch.xdg import config_home
-
-
-def _get_cache_base() -> Path:
-    """Get the base cache directory, honoring XDG_CACHE_HOME."""
-    xdg_cache = os.environ.get("XDG_CACHE_HOME")
-    if xdg_cache:
-        return Path(xdg_cache) / "devlaunch"
-    return Path.home() / ".cache" / "devlaunch"
+from devlaunch.xdg import config_home, devlaunch_cache
 
 
 @dataclass
@@ -28,7 +19,7 @@ class WorktreeConfig:
     """
 
     enabled: bool = True  # Enabled by default
-    repos_dir: Union[Path, str] = field(default_factory=lambda: _get_cache_base() / "repos")
+    repos_dir: Union[Path, str] = field(default_factory=lambda: devlaunch_cache() / "repos")
     auto_fetch: bool = True
     fetch_interval: int = 3600  # Seconds between auto-fetches
     auto_prune: bool = True
@@ -77,7 +68,7 @@ class WorktreeConfig:
 
         return cls(
             enabled=worktree_data.get("enabled", True),
-            repos_dir=Path(worktree_data.get("repos_dir", _get_cache_base() / "repos")),
+            repos_dir=Path(worktree_data.get("repos_dir", devlaunch_cache() / "repos")),
             auto_fetch=worktree_data.get("auto_fetch", True),
             fetch_interval=worktree_data.get("fetch_interval", 3600),
             auto_prune=cleanup_data.get("auto_prune", True),

{devlaunch-0.0.17 → devlaunch-0.0.19}/devlaunch/worktree/storage.py

@@ -10,6 +10,8 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+from devlaunch.xdg import devlaunch_cache
+
 from .models import BaseRepository, WorktreeInfo, unknown_fields
 
 # Version of the on-disk metadata.json format.
@@ -40,10 +42,7 @@ _ENTRY_ERRORS = (KeyError, TypeError, ValueError)
 
 def _get_default_metadata_path() -> Path:
     """Get the default metadata path, honoring XDG_CACHE_HOME."""
-    xdg_cache = os.environ.get("XDG_CACHE_HOME")
-    if xdg_cache:
-        return Path(xdg_cache) / "devlaunch" / "metadata.json"
-    return Path.home() / ".cache" / "devlaunch" / "metadata.json"
+    return devlaunch_cache() / "metadata.json"
 
 
 def _warn(message: str) -> None:

devlaunch-0.0.19/devlaunch/xdg.py

@@ -0,0 +1,47 @@
+"""Where the XDG base directories point on this machine.
+
+Two unrelated places ask for the config home: the worktree loader, which reads
+`config.toml` under it, and the gh-token warning, which names it so a user whose
+shell scoped the variable can see why `gh auth token` refused. Those two have to
+agree -- a warning that names one directory while the loader reads another is
+worse than no warning -- so they share the answer rather than each spelling it.
+
+The cache home has the same problem and one more caller's worth of it. Three
+places used to spell it out identically: dl's own cache directory, the worktree
+config's default `repos_dir`, and the metadata file's default path. They have to
+agree because `dl --purge` reads the first to decide which workspaces are
+devlaunch's -- workspaces whose clones the other two put on disk -- so a copy
+that drifted would make a purge silently stop recognising its own work.
+"""
+
+import os
+from pathlib import Path
+
+
+def config_home() -> Path:
+    """`$XDG_CONFIG_HOME`, or the `~/.config` the spec falls back to.
+
+    An empty value counts as unset, which is what the XDG basedir spec says and
+    what a shell exporting the variable with no value means. Reading it any other
+    way resolves the config path relative to the working directory instead.
+    """
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+
+
+def cache_home() -> Path:
+    """`$XDG_CACHE_HOME`, or the `~/.cache` the spec falls back to.
+
+    Empty counts as unset, for the same reason as above.
+    """
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
+
+
+def devlaunch_cache() -> Path:
+    """Everything devlaunch stores on this machine, under one directory.
+
+    The bare repo clones, the workspace clones, the completion caches and
+    metadata.json all live here, and `dl --purge` removes exactly this. One
+    function rather than a copy per caller, because a purge decides what is its
+    own to delete by asking whether a workspace's source is inside it.
+    """
+    return cache_home() / "devlaunch"

{devlaunch-0.0.17 → devlaunch-0.0.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.17"
+version = "0.0.19"
 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]
@@ -139,6 +158,10 @@ exclude_also = [
   "if 0:",
   "raise AssertionError",
   "raise NotImplementedError",
+  # The exhaustiveness sentinel. `ty` runs in CI and rejects any call to it that
+  # is reachable, so in a build that type-checks these lines cannot be executed
+  # -- the same reason `raise AssertionError` is already on this list.
+  "_unhandled_source\\(",
   "if __name__ == .__main__.:",
   "pass",
   "(_):",

devlaunch-0.0.17/devlaunch/xdg.py

@@ -1,21 +0,0 @@
-"""Where the XDG base directories point on this machine.
-
-Two unrelated places ask for the config home: the worktree loader, which reads
-`config.toml` under it, and the gh-token warning, which names it so a user whose
-shell scoped the variable can see why `gh auth token` refused. Those two have to
-agree -- a warning that names one directory while the loader reads another is
-worse than no warning -- so they share the answer rather than each spelling it.
-"""
-
-import os
-from pathlib import Path
-
-
-def config_home() -> Path:
-    """`$XDG_CONFIG_HOME`, or the `~/.config` the spec falls back to.
-
-    An empty value counts as unset, which is what the XDG basedir spec says and
-    what a shell exporting the variable with no value means. Reading it any other
-    way resolves the config path relative to the working directory instead.
-    """
-    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")