devlaunch 0.0.10__tar.gz → 0.0.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.10
+Version: 0.0.11
 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.11}/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.10 → devlaunch-0.0.11}/devlaunch/dl.py

@@ -37,6 +37,7 @@ from . import 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
 
 
@@ -1188,9 +1189,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.11}/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.11/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.11}/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.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.10"
+version = "0.0.11"
 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]