devlaunch 0.0.18__tar.gz → 0.0.20__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.18
+Version: 0.0.20
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -340,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 |
@@ -362,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
@@ -452,10 +486,19 @@ 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.
+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
@@ -475,7 +518,7 @@ 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
+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

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

@@ -318,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 |
@@ -340,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
@@ -430,10 +464,19 @@ 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.
+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
@@ -453,7 +496,7 @@ 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
+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

{devlaunch-0.0.18 → devlaunch-0.0.20}/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):
@@ -162,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)
@@ -428,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
 
@@ -697,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
@@ -800,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:
@@ -959,6 +1181,12 @@ def parse_workspaces(listing: str) -> List[Workspace]:
     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(
@@ -979,6 +1207,12 @@ def parse_workspaces(listing: str) -> List[Workspace]:
             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]
 
 
@@ -1036,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(
@@ -1048,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]:
@@ -1072,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
 
@@ -1383,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)
 
@@ -1422,7 +1659,12 @@ def _get_clone_manager() -> WorkspaceCloneManager:
     if "clone_manager" not in _cache:
         manager = WorkspaceCloneManager()
         try:
-            migrate_cache(manager.storage, pathlib.Path(manager.config.repos_dir))
+            # Under the metadata lock so two dl processes cannot migrate at
+            # once: the renames are not idempotent mid-flight, and exclusive()
+            # reloads first so the version check sees the other side's result.
+            # migrate_cache calls save() directly, never a locked mutator.
+            with manager.storage.exclusive():
+                migrate_cache(manager.storage, pathlib.Path(manager.config.repos_dir))
         except OSError as e:
             # A failed migration must not take the command with it. The renames
             # that did happen are still resumable: the version header is only
@@ -1573,10 +1815,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.18 → devlaunch-0.0.20}/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.20/devlaunch/worktree/locks.py

@@ -0,0 +1,55 @@
+"""Inter-process locks for the shared cache.
+
+Several dl processes can run at once — two agents launched on their own
+branches, a completion refresh in the background — and they share one bare-clone
+cache and one metadata.json. These locks are what keeps simultaneous runs from
+racing each other over that state: without them, two first launches of a repo
+both ran ``git clone --bare`` into the same path (and the loser's cleanup
+deleted the winner's half-written clone), and metadata writers rewrote the file
+from stale in-memory copies, dropping each other's records.
+
+``flock`` rather than a pid file: the kernel releases it when the process dies,
+however it dies, so a crashed dl never leaves the cache wedged.
+
+Two deliberate limits, both load-bearing:
+
+- **Not reentrant.** Acquiring a path twice in one process deadlocks (the second
+  open file description blocks on the first). Call sites are structured so no
+  lock is ever taken while the same lock is held — see the acquisition comments
+  at each site.
+- **The lock file is never deleted.** Unlinking an flock'd file is the classic
+  self-defeating move: a process that opened the old inode still "holds" a lock
+  nobody else can see, while new arrivals lock a fresh file and walk straight
+  past it. A few empty ``.lock`` files in the cache are the price of the
+  guarantee; ``dl --purge`` sweeps them away with everything else.
+"""
+
+import contextlib
+import fcntl
+import os
+import sys
+from pathlib import Path
+from typing import Iterator, Optional
+
+
+@contextlib.contextmanager
+def hold_lock(lock_path: Path, waiting_note: Optional[str] = None) -> Iterator[None]:
+    """Hold an exclusive inter-process lock on *lock_path* for the block.
+
+    Blocks until the lock is free. When another process already holds it and
+    *waiting_note* is given, one line is printed to stderr first, so a dl run
+    that sits waiting on a sibling's long clone says why it is sitting.
+    """
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            if waiting_note:
+                print(f"dl: waiting for {waiting_note}", file=sys.stderr)
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        # Closing the descriptor releases the lock; nothing is unlinked.
+        os.close(fd)

{devlaunch-0.0.18 → devlaunch-0.0.20}/devlaunch/worktree/repo_manager.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import Optional, TYPE_CHECKING
 
+from .locks import hold_lock
 from .models import BaseRepository
 from .storage import MetadataStorage
 
@@ -41,6 +42,15 @@ class RepositoryManager:
         """Get the bare git directory for a repository."""
         return self.get_repo_path(owner, repo) / ".bare"
 
+    def lock_path(self, owner: str, repo: str) -> Path:
+        """The lock every process takes before mutating repos/<owner>/<repo>.
+
+        A file, not a directory, inside the repo dir: every walker of the cache
+        filters on ``is_dir()``, so it is invisible to discovery, migration and
+        completion scans.
+        """
+        return self.get_repo_path(owner, repo) / ".lock"
+
     def clone_repo(self, owner: str, repo: str, remote_url: str) -> BaseRepository:
         """Clone a new base repository as bare (no working directory).
 
@@ -58,7 +68,21 @@ class RepositoryManager:
             existing_repo = self.get_repo(owner, repo)
             if existing_repo:
                 return existing_repo
-            # Repository path exists but metadata doesn't - continue to create metadata
+            if (bare_path / "HEAD").exists():
+                # The bare clone is already on disk but this process has no
+                # record of it -- another process just made it (this process's
+                # metadata was loaded before that one saved), or an earlier run
+                # died between clone and save. Either way the clone on disk is
+                # the authority and the record is derived state: rebuild the
+                # record. Cloning over it instead is not an option -- git
+                # refuses the non-empty destination, and the failure cleanup
+                # below would then delete a cache another launch is using.
+                return self._register_existing_bare(owner, repo, remote_url, bare_path)
+            # No HEAD: a dead run's partial clone. Holding the repo lock (every
+            # caller comes through ensure_repo) means no live process owns it,
+            # so clear it and clone fresh.
+            logger.warning(f"Removing partial clone at {bare_path}")
+            shutil.rmtree(bare_path)
 
         # Create parent directory
         bare_path.parent.mkdir(parents=True, exist_ok=True)
@@ -97,11 +121,28 @@ class RepositoryManager:
 
         except subprocess.CalledProcessError as e:
             logger.debug(f"Failed to clone repository: {e.stderr}")
-            # Clean up partial clone
+            # Clean up the partial clone. Safe to delete: the exists-cases were
+            # all handled above, so this directory is one this call created.
             if bare_path.exists():
                 shutil.rmtree(bare_path)
             raise RuntimeError(f"Failed to clone repository: {e.stderr}") from e
 
+    def _register_existing_bare(
+        self, owner: str, repo: str, remote_url: str, bare_path: Path
+    ) -> BaseRepository:
+        """Rebuild the metadata record for a bare clone already on disk."""
+        base_repo = BaseRepository(
+            owner=owner,
+            repo=repo,
+            remote_url=remote_url,
+            local_path=bare_path,
+            default_branch=self._get_default_branch(bare_path),
+            last_fetched=datetime.now(),
+            worktrees=[],
+        )
+        self.storage.add_repository(base_repo)
+        return base_repo
+
     def fetch_repo(self, owner: str, repo: str) -> None:
         """Fetch latest changes from remote."""
         bare_path = self.get_bare_path(owner, repo)
@@ -166,20 +207,33 @@ class RepositoryManager:
         """Ensure repo exists locally, clone if needed.
 
         Uses lazy fetch: only fetches if fetch_interval has elapsed since last fetch.
-        """
-        if self.repo_exists(owner, repo):
-            existing_repo = self.get_repo(owner, repo)
-            if existing_repo:
-                # Only fetch if interval has elapsed (lazy fetch)
-                if auto_fetch and self._should_fetch(existing_repo):
-                    try:
-                        self.fetch_repo(owner, repo)
-                    except Exception as e:
-                        logger.warning(f"Failed to fetch updates: {e}")
-                return existing_repo
-            # Metadata doesn't exist but repo exists - fall through to clone (which will add metadata)
 
-        return self.clone_repo(owner, repo, remote_url)
+        The whole exists-check-then-clone sequence runs under the repo lock:
+        without it, two processes launching the same repo at once both saw no
+        clone and both ran ``git clone --bare`` into the same path — and the
+        loser's cleanup in clone_repo deleted the winner's half-written cache.
+        Serialized, the loser just waits and then reuses the winner's clone.
+        clone_repo and fetch_repo rely on this lock rather than taking it
+        themselves (hold_lock is not reentrant).
+        """
+        with hold_lock(
+            self.lock_path(owner, repo),
+            waiting_note=f"another dl run preparing {owner}/{repo}",
+        ):
+            if self.repo_exists(owner, repo):
+                existing_repo = self.get_repo(owner, repo)
+                if existing_repo:
+                    # Only fetch if interval has elapsed (lazy fetch)
+                    if auto_fetch and self._should_fetch(existing_repo):
+                        try:
+                            self.fetch_repo(owner, repo)
+                        except Exception as e:
+                            logger.warning(f"Failed to fetch updates: {e}")
+                    return existing_repo
+                # Metadata doesn't exist but repo exists - fall through to clone
+                # (which will add metadata)
+
+            return self.clone_repo(owner, repo, remote_url)
 
     def repo_exists(self, owner: str, repo: str) -> bool:
         """Check if repository exists locally."""

{devlaunch-0.0.18 → devlaunch-0.0.20}/devlaunch/worktree/storage.py

@@ -10,6 +10,9 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+from devlaunch.xdg import devlaunch_cache
+
+from .locks import hold_lock
 from .models import BaseRepository, WorktreeInfo, unknown_fields
 
 # Version of the on-disk metadata.json format.
@@ -40,10 +43,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:
@@ -84,8 +84,28 @@ class MetadataStorage:
         self.metadata_path.parent.mkdir(parents=True, exist_ok=True)
         # Every file operation targets the real file, not a symlink pointing at it.
         self._file_path = _resolve_link(self.metadata_path)
+        # A sidecar rather than the file itself: save() replaces metadata.json
+        # by rename, and a lock taken on a replaced inode guards nothing.
+        self._lock_path = self._file_path.with_name(self._file_path.name + ".lock")
         self._load()
 
+    @contextlib.contextmanager
+    def exclusive(self):
+        """Hold the metadata lock and reload before the block runs.
+
+        Every mutation goes through this: the in-memory copy was loaded whenever
+        this process started, and other dl processes may have written since.
+        Rewriting the file from that stale copy silently drops their records —
+        reloading under the lock is what makes read-modify-write safe. The
+        caller applies its change and calls save() before the block ends.
+
+        Not reentrant (see locks.py), so mutators must never be called from
+        inside an exclusive() block — they take this lock themselves.
+        """
+        with hold_lock(self._lock_path, waiting_note="another dl run updating the workspace list"):
+            self._load()
+            yield
+
     def _quarantine(self, reason: str) -> None:
         """Move an unusable metadata file aside so the data stays inspectable.
 
@@ -289,8 +309,9 @@ class MetadataStorage:
     def add_repository(self, repo: BaseRepository) -> None:
         """Add or update a repository."""
         key = f"{repo.owner}/{repo.repo}"
-        self.repositories[key] = repo
-        self.save()
+        with self.exclusive():
+            self.repositories[key] = repo
+            self.save()
 
     def get_repository(self, owner: str, repo: str) -> Optional[BaseRepository]:
         """Get a repository by owner and name."""
@@ -304,22 +325,24 @@ class MetadataStorage:
     def remove_repository(self, owner: str, repo: str) -> None:
         """Remove a repository."""
         key = f"{owner}/{repo}"
-        if key in self.repositories:
-            del self.repositories[key]
-            self.save()
+        with self.exclusive():
+            if key in self.repositories:
+                del self.repositories[key]
+                self.save()
 
     def add_worktree(self, worktree: WorktreeInfo) -> None:
         """Add or update a worktree."""
         key = f"{worktree.owner}/{worktree.repo}/{worktree.branch}"
-        self.worktrees[key] = worktree
+        with self.exclusive():
+            self.worktrees[key] = worktree
 
-        # Update repository's worktree list in memory, then write once.
-        repo = self.get_repository(worktree.owner, worktree.repo)
-        if repo and worktree.branch not in repo.worktrees:
-            repo.worktrees.append(worktree.branch)
-            self.repositories[f"{worktree.owner}/{worktree.repo}"] = repo
+            # Update repository's worktree list in memory, then write once.
+            repo = self.get_repository(worktree.owner, worktree.repo)
+            if repo and worktree.branch not in repo.worktrees:
+                repo.worktrees.append(worktree.branch)
+                self.repositories[f"{worktree.owner}/{worktree.repo}"] = repo
 
-        self.save()
+            self.save()
 
     def get_worktree(self, owner: str, repo: str, branch: str) -> Optional[WorktreeInfo]:
         """Get a worktree by repository and branch."""
@@ -349,13 +372,14 @@ class MetadataStorage:
     def remove_worktree(self, owner: str, repo: str, branch: str) -> None:
         """Remove a worktree."""
         key = f"{owner}/{repo}/{branch}"
-        if key in self.worktrees:
-            del self.worktrees[key]
+        with self.exclusive():
+            if key in self.worktrees:
+                del self.worktrees[key]
 
-            # Update repository's worktree list in memory, then write once.
-            repo_obj = self.get_repository(owner, repo)
-            if repo_obj and branch in repo_obj.worktrees:
-                repo_obj.worktrees.remove(branch)
-                self.repositories[f"{owner}/{repo}"] = repo_obj
+                # Update repository's worktree list in memory, then write once.
+                repo_obj = self.get_repository(owner, repo)
+                if repo_obj and branch in repo_obj.worktrees:
+                    repo_obj.worktrees.remove(branch)
+                    self.repositories[f"{owner}/{repo}"] = repo_obj
 
-            self.save()
+                self.save()

{devlaunch-0.0.18 → devlaunch-0.0.20}/devlaunch/worktree/workspace_clone.py

@@ -25,6 +25,7 @@ from typing import Optional
 from ..workspace_id import WorkspaceId, validate_ref_name
 from .branch_manager import BranchManager
 from .config import WorktreeConfig, get_worktree_config
+from .locks import hold_lock
 from .models import WorktreeInfo
 from .repo_manager import RepositoryManager
 from .storage import MetadataStorage
@@ -173,27 +174,36 @@ class WorkspaceCloneManager:
 
         Fetches latest refs, then uses BranchManager to create the branch
         locally if needed. Does not push to the remote.
+
+        Runs under the repo lock: the fetch and the branch creation both write
+        refs in the shared bare repo, and two processes doing so at once trip
+        over git's own ref locks. (hold_lock is not reentrant; no callee here
+        takes the repo lock.)
         """
         bare_path = self.repo_manager.get_bare_path(owner, repo)
-        # Lazy-fetch: only hits the network when the fetch interval has elapsed
-        try:
-            self.repo_manager.lazy_fetch(owner, repo)
-        except (RuntimeError, ValueError, OSError) as e:
-            logger.warning(f"Failed to fetch before branch ensure: {e}")
+        with hold_lock(
+            self.repo_manager.lock_path(owner, repo),
+            waiting_note=f"another dl run preparing {owner}/{repo}",
+        ):
+            # Lazy-fetch: only hits the network when the fetch interval has elapsed
+            try:
+                self.repo_manager.lazy_fetch(owner, repo)
+            except (RuntimeError, ValueError, OSError) as e:
+                logger.warning(f"Failed to fetch before branch ensure: {e}")
 
-        try:
-            default_branch = self.repo_manager.get_default_branch(owner, repo)
-        except (RuntimeError, subprocess.CalledProcessError, OSError) as e:
-            logger.warning(f"Failed to resolve default branch: {e}")
-            default_branch = None
-
-        self.branch_manager.ensure_branch_exists(
-            bare_path,
-            branch,
-            create_remote=False,
-            start_point=default_branch or "HEAD",
-            use_local_refs=True,
-        )
+            try:
+                default_branch = self.repo_manager.get_default_branch(owner, repo)
+            except (RuntimeError, subprocess.CalledProcessError, OSError) as e:
+                logger.warning(f"Failed to resolve default branch: {e}")
+                default_branch = None
+
+            self.branch_manager.ensure_branch_exists(
+                bare_path,
+                branch,
+                create_remote=False,
+                start_point=default_branch or "HEAD",
+                use_local_refs=True,
+            )
 
     def ensure_workspace(
         self,
@@ -223,6 +233,28 @@ class WorkspaceCloneManager:
         bare_repo_path = self.repo_manager.get_bare_path(owner, repo)
 
         ws_path = self.get_workspace_path(owner, repo, branch)
+
+        # Steps 2-6 mutate the workspace clone, so they run under the repo
+        # lock: fire the same workspace twice at once and, unserialized, each
+        # process saw no clone, both cloned into the same path, and the loser's
+        # cleanup deleted the winner's. The lock is taken only after
+        # ensure_repo (which takes the same lock) has returned -- hold_lock is
+        # not reentrant.
+        with hold_lock(
+            self.repo_manager.lock_path(owner, repo),
+            waiting_note=f"another dl run preparing {owner}/{repo}",
+        ):
+            return self._prepare_workspace(workspace, bare_repo_path, ws_path, remote_url)
+
+    def _prepare_workspace(
+        self,
+        workspace: WorkspaceId,
+        bare_repo_path: Path,
+        ws_path: Path,
+        remote_url: str,
+    ) -> Path:
+        """Steps 2-6 of ensure_workspace; the caller holds the repo lock."""
+        owner, repo, branch = workspace.owner, workspace.repo, workspace.ref
         is_new_workspace = False
         if not self.workspace_exists(owner, repo, branch):
             is_new_workspace = True

devlaunch-0.0.20/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.18 → devlaunch-0.0.20}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.18"
+version = "0.0.20"
 authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
 description = "DevLaunch - A streamlined CLI for devpod workspaces"
 readme = "README.md"
@@ -158,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.18/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")