devlaunch 0.0.10__tar.gz → 0.0.12__tar.gz

{devlaunch-0.0.10 → devlaunch-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.10
+Version: 0.0.12
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -8,7 +8,6 @@ Author-email: Austin Gregg-Smith <blooop@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Dist: iterfzf>=1.0.0
-Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: tomli>=2.0.0
 Provides-Extra: test
 Requires-Dist: coverage<=7.14.1,>=7.5.4; extra == 'test'
@@ -162,10 +161,43 @@ to leave room for tools that add their own prefixes.
 Branch names must be safe as both git refs and directory names — a name with a space or
 a leading dash is rejected rather than quietly rewritten.
 
-> **Upgrading:** this id format is new. Existing workspaces and clone directories were
-> named by the previous scheme and will get new ids, so `dl user/repo@branch` creates a
-> fresh workspace and leaves the old container behind. Remove stale ones with
-> `dl <old-id> rm`, which still finds and deletes the old clone directory.
+### Upgrading from an older devlaunch
+
+This id format is new, and the directories and containers on your machine were named by
+the previous scheme. The first `dl user/repo…` command after upgrading migrates the cache
+once and prints what it did. `dl --help`, `dl --version`, `dl --ls` and opening an existing
+workspace by name do not trigger it.
+
+**Your clone directories are renamed.** What was
+`~/.cache/devlaunch/repos/blooop/devlaunch/main` becomes
+`~/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-main-zovomobo`. A workspace is a git
+clone whose `origin` points at the `.bare` cache next to it, and `.bare` does not move, so
+this is a plain rename: branches, history and **uncommitted changes all survive** — only
+the folder name changes. `metadata.json` is updated in the same pass, so nothing is left
+pointing at the old name.
+
+**Your existing devpod containers keep their old ids and are orphaned.** The next
+`dl user/repo@branch` builds a fresh container under the new id. dl does not delete
+containers for you — deleting by id is how a running sidecar got destroyed the last time
+something tried ([kinisi_ros#9766](https://github.com/kinisi-robotics/kinisi_ros/pull/9766)) —
+so it prints a one-line notice with the count and writes the old ids to
+`~/.cache/devlaunch/orphaned-workspaces.txt`. Remove them when you are ready:
+
+```bash
+xargs -r -n1 devpod delete < ~/.cache/devlaunch/orphaned-workspaces.txt
+```
+
+**A clone directory with no metadata record is left alone.** Nothing records which branch
+it was cloned for, and the old directory name cannot be turned back into one — `feature/auth`
+and `feature-auth` both became `feature-auth` — so a guessed name would be worse than no
+rename. Those directories stay exactly where they are and are listed in
+`~/.cache/devlaunch/unmigrated-clones.txt`.
+
+Running dl again changes nothing: the migration is keyed on the `version` field in
+`metadata.json`, not on directory names, so a branch that happens to look like a new-scheme
+id is never mistaken for one. If a migration is interrupted, the next run finishes it — the
+version is written last, in the same atomic save as the new paths, so it never claims more
+than the filesystem has actually done.
 
 ## Workspace Commands
 

{devlaunch-0.0.10 → devlaunch-0.0.12}/README.md

@@ -139,10 +139,43 @@ to leave room for tools that add their own prefixes.
 Branch names must be safe as both git refs and directory names — a name with a space or
 a leading dash is rejected rather than quietly rewritten.
 
-> **Upgrading:** this id format is new. Existing workspaces and clone directories were
-> named by the previous scheme and will get new ids, so `dl user/repo@branch` creates a
-> fresh workspace and leaves the old container behind. Remove stale ones with
-> `dl <old-id> rm`, which still finds and deletes the old clone directory.
+### Upgrading from an older devlaunch
+
+This id format is new, and the directories and containers on your machine were named by
+the previous scheme. The first `dl user/repo…` command after upgrading migrates the cache
+once and prints what it did. `dl --help`, `dl --version`, `dl --ls` and opening an existing
+workspace by name do not trigger it.
+
+**Your clone directories are renamed.** What was
+`~/.cache/devlaunch/repos/blooop/devlaunch/main` becomes
+`~/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-main-zovomobo`. A workspace is a git
+clone whose `origin` points at the `.bare` cache next to it, and `.bare` does not move, so
+this is a plain rename: branches, history and **uncommitted changes all survive** — only
+the folder name changes. `metadata.json` is updated in the same pass, so nothing is left
+pointing at the old name.
+
+**Your existing devpod containers keep their old ids and are orphaned.** The next
+`dl user/repo@branch` builds a fresh container under the new id. dl does not delete
+containers for you — deleting by id is how a running sidecar got destroyed the last time
+something tried ([kinisi_ros#9766](https://github.com/kinisi-robotics/kinisi_ros/pull/9766)) —
+so it prints a one-line notice with the count and writes the old ids to
+`~/.cache/devlaunch/orphaned-workspaces.txt`. Remove them when you are ready:
+
+```bash
+xargs -r -n1 devpod delete < ~/.cache/devlaunch/orphaned-workspaces.txt
+```
+
+**A clone directory with no metadata record is left alone.** Nothing records which branch
+it was cloned for, and the old directory name cannot be turned back into one — `feature/auth`
+and `feature-auth` both became `feature-auth` — so a guessed name would be worse than no
+rename. Those directories stay exactly where they are and are listed in
+`~/.cache/devlaunch/unmigrated-clones.txt`.
+
+Running dl again changes nothing: the migration is keyed on the `version` field in
+`metadata.json`, not on directory names, so a branch that happens to look like a new-scheme
+id is never mistaken for one. If a migration is interrupted, the next run finishes it — the
+version is written last, in the same atomic save as the new paths, so it never claims more
+than the filesystem has actually done.
 
 ## Workspace Commands
 

devlaunch-0.0.12/devlaunch/devpod_ssh.py

@@ -0,0 +1,143 @@
+"""How a `devpod ssh` session ended, recovered from what devpod reports.
+
+devpod means to pass a remote process's exit status through. Its top-level error
+handler does:
+
+    if sshExitErr, ok := err.(*ssh.ExitError); ok {
+        os.Exit(sshExitErr.ExitStatus())
+    }
+
+But by the time the error reaches there it has been wrapped three times —
+`ssh session: %w` in cmd/machine/ssh.go, then "run in container", then "tunnel to
+container" — and a bare type assertion does not see through `%w`. So every
+nonzero remote exit misses that branch and lands on devpod's generic failure
+path instead, which prints
+
+    error Try using the --debug flag to see a more verbose output    root.go:106
+    fatal tunnel to container: run in container: ssh session: Process exited with status 130
+
+and exits 1.
+
+Nothing has gone wrong in that example. A login shell exits with the status of
+its last command, so a single Ctrl-C before typing `exit` is enough to make a
+perfectly ordinary session end 130. The session ran and it ended; devpod just has
+no way left to say so.
+
+Both of those lines are Error/Fatal level, which loft-sh/log sends to stderr
+(Info-level progress goes to stdout, so reading stderr does not hold back the
+"waiting for workspace" chatter). That makes the status recoverable: read
+devpod's stderr, take the status out of the message it buried it in, and hold
+back the two lines that only exist because devpod could not report it properly.
+
+The distinction the rest of devlaunch needs is which process the resulting number
+came from, so it is a type rather than a bare int — see SshOutcome.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Iterable, NoReturn, Optional, TextIO
+
+# devpod prints this immediately before the fatal it belongs to, so it has to be
+# held for one line to see which fatal that is.
+DEBUG_HINT = "Try using the --debug flag to see a more verbose output"
+
+# The status golang.org/x/crypto/ssh formatted into an *ssh.ExitError:
+# "Process exited with status 130", optionally " from signal SIGINT" and
+# ". Reason was: ...". Anchored on devpod's "fatal" tag as well so a remote
+# program printing the same sentence on its own stderr (which reaches us only
+# when there is no pty) cannot be mistaken for devpod's report.
+#
+# No \b before "fatal": devpod colours the tag, and the escape it emits ends in
+# "m", so there is no word boundary in front of it.
+REMOTE_EXIT_RE = re.compile(r"fatal\b.*\bssh session: Process exited with status (\d+)")
+
+
+@dataclass(frozen=True)
+class RemoteExit:
+    """devpod ran the remote program, and it exited with `status`.
+
+    Not a devlaunch failure, whatever `status` is: the shell or command the user
+    asked for ran to completion. `status` belongs to that program.
+    """
+
+    status: int
+
+
+@dataclass(frozen=True)
+class DevpodFailed:
+    """devpod never ran the remote program, or lost it partway.
+
+    `exit_code` is devpod's own. devpod has already written its diagnostics to
+    stderr by the time this is constructed, so it carries no message of its own —
+    there is nothing devlaunch knows that the user has not already been told.
+    """
+
+    exit_code: int
+
+
+SshOutcome = RemoteExit | DevpodFailed
+
+
+def assert_never(value: NoReturn) -> NoReturn:
+    """Fail loudly on an SshOutcome arm nobody handled.
+
+    A runtime backstop, not a compile-time one: `ty`, the checker this project
+    runs in CI, does not currently reject a `match` that drops an arm. It is
+    still worth having, because a `match` with no fallthrough returns None, and
+    `main` returning None makes `dl` exit 0 — a new outcome would otherwise go
+    out as success.
+
+    Stands in for typing.assert_never, which needs 3.11; this project is 3.10+.
+    """
+    raise AssertionError(f"unhandled outcome: {value!r}")
+
+
+def filter_devpod_stderr(lines: Iterable[str], out: TextIO) -> Optional[int]:
+    """Forward devpod's stderr, holding back its report of a remote exit status.
+
+    Returns that status if devpod reported one. Everything else is passed through
+    verbatim and unbuffered, so a genuine devpod failure still reads exactly as
+    it does today — including the --debug hint, which is released ahead of the
+    fatal it precedes rather than after it.
+    """
+    remote_status: Optional[int] = None
+    held_hint: Optional[str] = None
+
+    for line in lines:
+        match = REMOTE_EXIT_RE.search(line)
+        if match:
+            remote_status = int(match.group(1))
+            # The hint introduced this fatal, so it goes with it.
+            held_hint = None
+            continue
+        if DEBUG_HINT in line:
+            held_hint = line
+            continue
+        if held_hint is not None:
+            out.write(held_hint)
+            held_hint = None
+        out.write(line)
+        out.flush()
+
+    if held_hint is not None:
+        out.write(held_hint)
+        out.flush()
+
+    return remote_status
+
+
+def interpret(devpod_exit_code: int, remote_status: Optional[int]) -> SshOutcome:
+    """Decide what a finished `devpod ssh` actually reported.
+
+    A recovered remote status wins over devpod's own exit code, because devpod
+    reports 1 alongside it regardless of what the remote program returned.
+    """
+    if remote_status is not None:
+        return RemoteExit(remote_status)
+    if devpod_exit_code == 0:
+        return RemoteExit(0)
+    # No status to recover. Either devpod really did fail, or a future devpod
+    # unwraps the error properly and exits with the remote status itself — in
+    # which case this is still the right number to pass on, and devpod stayed
+    # quiet, so nothing spurious is printed either way.
+    return DevpodFailed(devpod_exit_code)

{devlaunch-0.0.10 → devlaunch-0.0.12}/devlaunch/dl.py

@@ -33,10 +33,11 @@ from dataclasses import dataclass
 from urllib.parse import urlparse
 from urllib.request import url2pathname
 
-from . import gh_auth
+from . import devpod_ssh, gh_auth
 from .completion import install_completions
 from .workspace_id import TARGET_LENGTH, WorkspaceId, slug, source_workspace_id, validate_ref_name
 from .worktree.config import get_worktree_config
+from .worktree.migration import migrate_cache
 from .worktree.workspace_clone import WorkspaceCloneManager
 
 
@@ -831,6 +832,38 @@ def run_devpod(
         raise DevpodNotInstalled(DEVPOD_MISSING_MESSAGE) from e
 
 
+def run_devpod_session(
+    args: List[str], env: Optional[Dict[str, str]] = None
+) -> devpod_ssh.SshOutcome:
+    """Run a devpod command that hands its stdin/stdout to a terminal session.
+
+    stdin and stdout are inherited untouched — devpod puts the real terminal into
+    raw mode through them, and requests a pty on that basis. Only stderr is read,
+    which under a pty carries devpod's own warnings and errors and nothing else,
+    so that devpod's report of how the session ended can be interpreted rather
+    than dumped on the user. See devpod_ssh for why that is necessary.
+    """
+    cmd = ["devpod"] + args
+    logging.debug("Running: %s", " ".join(cmd))
+    # nosec B603 - using list form, not shell=True; no command injection risk
+    with subprocess.Popen(
+        cmd,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=env,
+    ) as proc:
+        # proc.stderr is a pipe because PIPE was asked for, but Popen's type
+        # cannot express that, so the narrowing happens here rather than by
+        # widening filter_devpod_stderr to a None it would have no answer for.
+        pipe = proc.stderr
+        remote_status = (
+            devpod_ssh.filter_devpod_stderr(pipe, sys.stderr) if pipe is not None else None
+        )
+    return devpod_ssh.interpret(proc.returncode, remote_status)
+
+
 # The memoized `devpod list` snapshot. A dict rather than a module-level
 # Optional so the accessors below need no `global`, and so "nothing read yet"
 # (no key at all) stays distinguishable from "devpod has no workspaces" (an
@@ -1048,8 +1081,20 @@ def workspace_ssh(
     args.extend(token_args)
 
     logging.info(f"SSH command: devpod {' '.join(args)}")
-    result = run_devpod(args, env=env)
-    return result.returncode
+    outcome = run_devpod_session(args, env=env)
+
+    # The two arms carry the same kind of number from different processes, which
+    # is exactly the confusion this used to make: `dl` reported devpod's exit
+    # code (always 1) for a session that had ended perfectly normally with, say,
+    # 130. Whichever arm this is, the status returned is the session's.
+    match outcome:
+        case devpod_ssh.RemoteExit(status=status):
+            return status
+        case devpod_ssh.DevpodFailed(exit_code=exit_code):
+            logging.debug("devpod ssh failed with exit code %s", exit_code)
+            return exit_code
+        case _ as unhandled:
+            devpod_ssh.assert_never(unhandled)
 
 
 def attach_workspace(workspace_id: str, shell_command: Optional[str] = None) -> int:
@@ -1188,9 +1233,31 @@ _cache: dict[str, WorkspaceCloneManager] = {}
 
 
 def _get_clone_manager() -> WorkspaceCloneManager:
-    """Lazy factory for WorkspaceCloneManager."""
+    """Lazy factory for WorkspaceCloneManager, migrating the cache on first use.
+
+    This is where the one-shot id-scheme migration runs, for three reasons. It is
+    dl's single construction point for the object that owns every read of a
+    workspace path, so nothing can reach a stale path before the rename. It is
+    lazy, so the commands that touch no workspace -- `--help`, `--version`,
+    `--ls`, the completion commands, `--purge`, and opening an existing workspace
+    by name -- never reach it, which keeps #58's promise that help does no work.
+    And the memo makes it at most once per process.
+
+    On an already-migrated cache this costs one integer comparison, because the
+    trigger is the version header the storage load already parsed. Nothing here
+    spawns devpod: the orphaned container ids come from metadata.
+    """
     if "clone_manager" not in _cache:
-        _cache["clone_manager"] = WorkspaceCloneManager()
+        manager = WorkspaceCloneManager()
+        try:
+            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
+            # written by the final save, so an unwritten file means the next run
+            # migrates again and finds them already in place.
+            logging.warning(f"Could not migrate the workspace cache: {e}")
+        _cache["clone_manager"] = manager
     return _cache["clone_manager"]
 
 

{devlaunch-0.0.10 → devlaunch-0.0.12}/devlaunch/worktree/__init__.py

@@ -2,6 +2,7 @@
 
 from .branch_manager import BranchManager
 from .config import WorktreeConfig, get_worktree_config
+from .migration import MigrationReport, migrate_cache
 from .models import BaseRepository, WorktreeInfo
 from .repo_manager import RepositoryManager
 from .storage import MetadataStorage
@@ -14,6 +15,8 @@ __all__ = [
     "get_worktree_config",
     "BranchManager",
     "MetadataStorage",
+    "MigrationReport",
+    "migrate_cache",
     "RepositoryManager",
     "WorkspaceCloneManager",
 ]

devlaunch-0.0.12/devlaunch/worktree/migration.py

@@ -0,0 +1,264 @@
+"""Bring a cache written by an older devlaunch onto the current id scheme.
+
+Before blooop/devlaunch#64 a clone directory's leaf was the flattened branch name
+(``<cache>/repos/blooop/devlaunch/main``) and the devpod workspace id was a second,
+separately derived string. Now :class:`~devlaunch.workspace_id.WorkspaceId` derives
+one id that names both (``devlaunch-main-zovomobo``). Every clone directory written
+by an older build therefore sits under a name nothing looks for any more.
+
+**Renaming is the right answer, not orphaning.** A workspace is a ``git clone``
+whose ``origin`` points at the ``.bare`` path, and ``.bare`` does not move, so a
+plain ``rename`` is lossless: the clone keeps working and **uncommitted work
+survives**. That work is the one thing in the cache that is not cheaply
+recreatable, which is what decides the strategy (see #55).
+
+**The trigger is the version header, not the directory name.** ``metadata.json``
+carries a ``version`` (#56), so this migration runs exactly when
+``schema_version < SCHEMA_VERSION`` and then writes the new version. Sniffing the
+leaf for "a dash plus consonant-vowel pairs" was considered and rejected: a branch
+literally named ``foo-bexoza`` false-positives, and the header makes the trigger
+deterministic and idempotent by construction.
+
+**Write ordering.** All renames happen first; then a single
+:meth:`MetadataStorage.save` writes the new paths *and* the new version header in
+one atomic replace. Nothing writes the header early, so "header says 2" always
+means "every path in this file is current". A crash anywhere in the renames leaves
+the header at 1, so the next run migrates again and finds each already-renamed
+directory as "destination present, source gone" -- which it treats as a resumed
+rename and simply catches metadata up to. The reverse ordering has no safe
+resume: saving first would bump the header to 2 while directories were still
+under their old names, and the next run would skip them for good.
+"""
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from ..workspace_id import WorkspaceId
+from .storage import SCHEMA_VERSION, MetadataStorage
+
+#: The bare reference repo shares the parent of the clone directories and is never
+#: one of them. It is skipped by name because it is the layout's one fixed leaf.
+BARE_DIR_NAME = ".bare"
+
+#: Old devpod workspace ids, one per line, for the cleanup command in the notice.
+ORPHAN_LIST_NAME = "orphaned-workspaces.txt"
+
+#: Clone directories the migration deliberately did not rename, one path per line.
+UNMIGRATED_LIST_NAME = "unmigrated-clones.txt"
+
+
+def _notice(message: str) -> None:
+    """Emit one line on stderr (stdout is parsed by the completion machinery)."""
+    print(f"dl: {message}", file=sys.stderr)
+
+
+@dataclass
+class MigrationReport:
+    """What one migration run did, for the caller and for the notices."""
+
+    #: ``(source, destination)`` for each directory actually renamed.
+    renamed: List[Tuple[Path, Path]] = field(default_factory=list)
+    #: ``(source, destination, error)`` for each rename the filesystem refused.
+    failed: List[Tuple[Path, Path, OSError]] = field(default_factory=list)
+    #: Recorded paths that no longer exist, so there was nothing to rename.
+    missing: List[Path] = field(default_factory=list)
+    #: Directories left under their old name because no record names their ref.
+    unmigrated: List[Path] = field(default_factory=list)
+    #: ``(directory, branch)`` for records holding a ref no id can be derived from.
+    unusable: List[Tuple[Path, str]] = field(default_factory=list)
+    #: ``(source, destination)`` where the derived name is another record's clone.
+    blocked: List[Tuple[Path, Path]] = field(default_factory=list)
+    #: Old devpod workspace ids, now orphaned because the id derivation changed.
+    orphaned_ids: List[str] = field(default_factory=list)
+
+
+def _clone_dirs(repos_dir: Path) -> List[Path]:
+    """Every workspace clone directory under ``repos_dir/<owner>/<repo>/``.
+
+    The layout is exactly three levels deep, so this is a bounded walk rather than
+    an ``rglob``: descending into the clones themselves would traverse every
+    checked-out working tree in the cache.
+    """
+    found: List[Path] = []
+    if not repos_dir.is_dir():
+        return found
+    try:
+        owner_dirs = sorted(p for p in repos_dir.iterdir() if p.is_dir())
+        for owner_dir in owner_dirs:
+            for repo_dir in sorted(p for p in owner_dir.iterdir() if p.is_dir()):
+                found.extend(
+                    sorted(p for p in repo_dir.iterdir() if p.is_dir() and p.name != BARE_DIR_NAME)
+                )
+    except OSError as exc:
+        _notice(f"could not scan {repos_dir} for old workspace clones ({exc})")
+    return found
+
+
+def _rename(src: Path, dest: Path, report: MigrationReport) -> bool:
+    """Move *src* to *dest*, recording the outcome. False if it did not happen.
+
+    ``os.rename`` and not ``shutil.move``: a rename either happens or does not,
+    while a copying fallback could leave a half-written duplicate of a clone that
+    holds uncommitted work. A cross-filesystem cache is rare enough to report and
+    leave to the user.
+    """
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        os.rename(src, dest)
+    except OSError as exc:
+        report.failed.append((src, dest, exc))
+        return False
+    report.renamed.append((src, dest))
+    return True
+
+
+def _migrate_record(record, repos_dir: Path, claimed, report: MigrationReport) -> None:
+    """Put one record's directory under its derived name and update the record.
+
+    ``local_path`` as stored is the source, never a recomputed old path: the record
+    is the truth about where the clone is now, which is the same principle that made
+    removal work for old-scheme workspaces (#64).
+
+    ``claimed`` is every path some record pointed at before this run started.
+    """
+    try:
+        workspace = WorkspaceId(record.owner, record.repo, record.branch)
+    except ValueError:
+        # The old derivation coerced unsafe refs instead of rejecting them, so a
+        # stored branch is not necessarily a legal ref. No id can be derived, so
+        # there is no name to rename to; leave the record and the directory as
+        # they are and say so.
+        report.unusable.append((Path(record.local_path), record.branch))
+        return
+
+    src = Path(record.local_path)
+    dest = repos_dir / record.owner / record.repo / workspace.value
+
+    if dest != src and dest in claimed:
+        # The derived name is a directory some *other* record owns. Only possible
+        # when a branch was literally named after another branch's derived id --
+        # #55's `foo-bexoza` case, now needing an exact hash match. Rename nothing
+        # and, unlike every other outcome, do not repoint the record either:
+        # adopting a clone another record owns is how one workspace's `rm` deletes
+        # another's work, which is the class of bug #9766 was.
+        report.blocked.append((src, dest))
+        return
+
+    if dest.exists():
+        # Either an interrupted earlier run already renamed this clone, or a
+        # newer-scheme clone was created alongside the old one. Rename nothing.
+        # The record follows the canonically named directory, so that a later
+        # `dl ... rm` deletes the clone devpod is actually using; a leftover src is
+        # reported below, because it becomes a directory no record points at.
+        pass
+    elif src.exists():
+        if not _rename(src, dest, report):
+            return
+    else:
+        # Already stale before this run: the record outlived its directory. Not a
+        # failure -- repointing it at the derived path is what a fresh clone would
+        # use, and `workspace_exists` reads the filesystem, so nothing is misled.
+        report.missing.append(src)
+
+    old_id = record.workspace_id
+    if old_id != workspace.value:
+        report.orphaned_ids.append(old_id)
+    record.local_path = dest
+    # The record carries the derived id, because `remove_workspace_by_id` looks up
+    # records by exactly the id dl derives from the spec. `devpod_workspace_id` is
+    # left alone: #55 flagged holding two ids in one record as a modelling defect,
+    # and giving that field a second meaning ("the orphaned old container") would
+    # make the defect worse. The orphaned ids go in the notice instead.
+    record.workspace_id = workspace.value
+
+
+def _announce(report: MigrationReport, cache_dir: Path) -> None:
+    """Tell the user what changed, in one line per kind of outcome."""
+    if report.renamed:
+        src, dest = report.renamed[0]
+        _notice(
+            f"migrated {len(report.renamed)} workspace clone director"
+            f"{'y' if len(report.renamed) == 1 else 'ies'} to the new id scheme "
+            f"(e.g. {src.name} -> {dest.name})"
+        )
+    for src, dest, exc in report.failed:
+        _notice(f"could not rename {src} to {dest} ({exc}); it was left where it is")
+    if report.missing:
+        _notice(
+            f"{len(report.missing)} metadata record(s) pointed at a clone directory that is "
+            "no longer there; they now point at their new-scheme path"
+        )
+    for path, branch in report.unusable:
+        _notice(
+            f"left {path} as it is: its recorded branch {branch!r} is not a usable git ref, "
+            "so no id can be derived for it"
+        )
+    for src, dest in report.blocked:
+        _notice(
+            f"left {src} as it is: its new name {dest.name} is already another workspace's "
+            "clone directory; move or delete one of them by hand"
+        )
+    if report.unmigrated:
+        listing = _write_lines(
+            cache_dir / UNMIGRATED_LIST_NAME, [str(p) for p in report.unmigrated]
+        )
+        _notice(
+            f"{len(report.unmigrated)} clone director"
+            f"{'y' if len(report.unmigrated) == 1 else 'ies'} could not be renamed (no metadata "
+            f"record, so the branch they were cloned for is unknown) and were left as they are"
+            + (f"; listed in {listing}" if listing else "")
+        )
+    if report.orphaned_ids:
+        listing = _write_lines(cache_dir / ORPHAN_LIST_NAME, sorted(report.orphaned_ids))
+        cleanup = (
+            f"xargs -r -n1 devpod delete < {listing}"
+            if listing
+            else "devpod delete <old-id>, one per workspace"
+        )
+        _notice(
+            f"{len(report.orphaned_ids)} devpod container(s) still carry the old workspace ids "
+            f"and are now orphaned; dl does not delete containers for you -- remove them with: "
+            f"{cleanup}"
+        )
+
+
+def _write_lines(path: Path, lines: List[str]) -> Optional[Path]:
+    """Write one line per entry, returning the path, or None if it could not be."""
+    try:
+        path.write_text("".join(f"{line}\n" for line in lines), encoding="utf-8")
+    except OSError as exc:
+        _notice(f"could not write {path} ({exc})")
+        return None
+    return path
+
+
+def migrate_cache(storage: MetadataStorage, repos_dir: Path) -> Optional[MigrationReport]:
+    """Migrate *storage* and the clone directories under *repos_dir*, once.
+
+    Returns None when the cache is already current, which is the common case and
+    costs a single integer comparison -- no filesystem scan and no devpod call.
+    """
+    if storage.schema_version >= SCHEMA_VERSION:
+        return None
+
+    report = MigrationReport()
+    # Snapshotted before any record is touched: it has to describe the layout the
+    # run started from, not one the run is halfway through rewriting.
+    claimed = {Path(record.local_path) for record in storage.worktrees.values()}
+    for record in storage.worktrees.values():
+        _migrate_record(record, repos_dir, claimed, report)
+
+    # Anything still under an old-scheme name that no record claims. Computed after
+    # the renames so it picks up both never-recorded directories and the leftover
+    # side of a collision, and excludes everything just moved into place.
+    recorded = {Path(record.local_path) for record in storage.worktrees.values()}
+    report.unmigrated = [path for path in _clone_dirs(repos_dir) if path not in recorded]
+
+    # One atomic write, last: it carries the new paths and the new version header
+    # together, so the header can never claim more than the filesystem has done.
+    storage.save()
+    _announce(report, storage.metadata_path.parent)
+    return report

{devlaunch-0.0.10 → devlaunch-0.0.12}/devlaunch/worktree/storage.py

@@ -12,9 +12,22 @@ from typing import Any, Dict, List, Optional, Tuple
 
 from .models import BaseRepository, WorktreeInfo, unknown_fields
 
-# Version of the on-disk metadata.json format. A file without a "version" key
-# predates versioning and is treated as version 1.
-SCHEMA_VERSION = 1
+# Version of the on-disk metadata.json format.
+#
+# 1: the original shape. Clone-directory leaves are flattened branch names and
+#    workspace ids are derived separately from them.
+# 2: leaves and workspace ids are both WorkspaceId.value (#64). Reached from 1 by
+#    devlaunch.worktree.migration, which renames the directories on disk and then
+#    writes the new paths and this header in one atomic save.
+SCHEMA_VERSION = 2
+
+# What a file whose header cannot be read is assumed to be. A file without a
+# "version" key predates versioning, so it is the original shape, not the current
+# one -- reading it as current would skip the migration it needs. The same applies
+# to a header that is present but nonsense: the conservative reading is the oldest
+# shape, because a migration that runs against an already-migrated cache is a
+# no-op while one that never runs leaves directories nothing looks for.
+LEGACY_SCHEMA_VERSION = 1
 
 # Top-level keys this build writes, and therefore the only ones a rewrite keeps.
 _KNOWN_SECTIONS = frozenset({"version", "repositories", "worktrees"})
@@ -178,8 +191,8 @@ class MetadataStorage:
     def _load_version(self, data: Dict[str, Any]) -> Tuple[int, bool]:
         """Interpret the version header, returning the version and whether it is lossy."""
         if "version" not in data:
-            # An absent version means a legacy pre-versioning file: same shape as v1.
-            return SCHEMA_VERSION, False
+            # An absent version means a legacy pre-versioning file: the v1 shape.
+            return LEGACY_SCHEMA_VERSION, False
 
         raw = data["version"]
         # JSON has a single number type, so tools freely normalize 1 to 1.0; an
@@ -195,9 +208,9 @@ class MetadataStorage:
             # because the rewritten header will not match what is there now.
             _warn(
                 f'metadata file {self._file_path} has an invalid "version" header '
-                f"({raw!r}); reading it as schema version {SCHEMA_VERSION}"
+                f"({raw!r}); reading it as schema version {LEGACY_SCHEMA_VERSION}"
             )
-            return SCHEMA_VERSION, True
+            return LEGACY_SCHEMA_VERSION, True
 
         if version > SCHEMA_VERSION:
             _warn(

{devlaunch-0.0.10 → devlaunch-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.10"
+version = "0.0.12"
 authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
 description = "DevLaunch - A streamlined CLI for devpod workspaces"
 readme = "README.md"
@@ -9,7 +9,6 @@ license = "MIT"
 dependencies = [
   "iterfzf>=1.0.0",
   "tomli>=2.0.0",
-  "tomli_w>=1.0.0",
 ]
 
 [project.urls]