devlaunch 0.0.9__tar.gz → 0.0.11__tar.gz

{devlaunch-0.0.9 → devlaunch-0.0.11}/.gitignore

@@ -184,3 +184,6 @@ logs/
 
 # uv is not this project's package manager (pixi.lock is authoritative)
 uv.lock
+
+# Agent worktrees (local scratch; never committed)
+.claude/worktrees/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.9
+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'
@@ -123,6 +122,83 @@ dl user/repo@branch              # Create from specific branch
 dl ./path                        # Create from local path
 ```
 
+## Workspace IDs
+
+`dl user/repo@branch` derives one id that names both the devpod workspace (what you
+see in `dl --ls`) and the clone directory under `~/.cache/devlaunch/repos/`:
+
+```
+<repo-slug>-<branch-slug>-<syllables>      at most 38 characters
+
+blooop/devlaunch@main                             -> devlaunch-main-zovomobo
+blooop/devlaunch@feature/auth                     -> devlaunch-feature-auth-poliseno
+blooop/devlaunch@feature-auth                     -> devlaunch-feature-auth-nesatabe
+blooop/test_renv@nb4                              -> test-renv-nb4-polenita
+kinisi-robotics/kinisi_ros@ags-devcontainer-tooling-support
+                                                  -> kinisi-ros-ags-devcontainer-t-lenevere
+blooop/devlaunch@dependabot/github_actions/codecov/codecov-action-6
+                                                  -> devlaunch-dependabot-codecov-sifivasa
+```
+
+The eight-character syllable suffix is a hash of the full `(owner, repo, branch)` triple.
+It is what makes the id unique: the readable part is shortened to fit the length limit,
+and shortening it does not affect whether two branches share an id. Long branch names
+drop whole `/`-separated middle segments before losing characters, so the part that
+identifies the branch survives. Note the third and fourth lines above: `feature/auth` and
+`feature-auth` read the same once slugged but are different branches, and they get
+different ids.
+
+Owner and repo are matched case-insensitively, the way GitHub treats them, so
+`dl NVIDIA/cuda-samples@main` and `dl nvidia/cuda-samples@main` are the same workspace.
+Branch names are case-sensitive, because git refs are.
+
+URL specs (`dl github.com/owner/repo`) get an id in the same shape, with the suffix
+hashed over the URL.
+
+The id is also the container hostname, so it stays well inside the 38-character budget
+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 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
 
 | Command | Description |
@@ -199,7 +275,23 @@ stays in place — including one it was given before you set
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
 | `dl --refresh` | Refresh completion cache |
 | `dl --help, -h` | Show this help |
-| `dl --version` | Show version |
+| `dl --version` | Show version (an editable install also names the tree it runs from) |
+
+A released install prints the version and nothing else. An install made in
+editable mode says so and names the checkout it resolves to, so two builds of
+the same version are told apart at a glance:
+
+```bash
+$ dl --version
+dl 0.0.9
+
+$ dl-next --version          # editable install of a working tree
+dl 0.0.9 (dev, editable from /path/to/your/devlaunch)
+```
+
+`aid --version` reports the same thing under its own name. The provenance comes
+from the installed package's own PEP 610 metadata; an install that records none
+just prints the bare version.
 
 ## Examples
 
@@ -221,6 +313,7 @@ dl blooop/devlaunch stop         # Stop workspace
 - **GitHub Shorthand**: Use `owner/repo` instead of full URLs - automatically expands to `github.com/owner/repo`
 - **Branch Support**: Specify branches with `owner/repo@branch` syntax
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
+- **One Round-Trip Per Question**: every `devpod` call costs ~0.45s, far more than `dl` itself, so a command reads the workspace list at most once — and `dl <ws> -- <cmd>` skips the extra round-trip that names an interactive prompt, since a one-shot command has none
 
 ## Worktree Backend
 
@@ -256,6 +349,19 @@ After running `dl --install`, you get intelligent tab completion:
 - File/directory paths when starting with `./`, `/`, or `~`
 - All global flags (`--ls`, `--install`, etc.) and workspace commands
 
+### How the completion cache stays current
+
+The data behind completions lives in `~/.cache/devlaunch/completions.json`, and
+building it means a `git ls-remote` per known repo — seconds of work. So it is
+rebuilt in the background at most once an hour (the same interval the worktree
+backend uses for lazy fetches), and at most once per `dl` invocation. Commands
+that change your workspaces (starting, stopping or deleting one) rebuild it as
+soon as they finish, regardless of when it was last built. Commands with no use
+for it — `dl --help`, `dl --version` — do not touch it at all.
+
+A branch created on a remote in the last hour may therefore not be offered yet.
+`dl --refresh` rebuilds the cache immediately and ignores the interval.
+
 ## Development
 
 This project uses [pixi](https://pixi.sh) for environment management.

{devlaunch-0.0.9 → devlaunch-0.0.11}/README.md

@@ -100,6 +100,83 @@ dl user/repo@branch              # Create from specific branch
 dl ./path                        # Create from local path
 ```
 
+## Workspace IDs
+
+`dl user/repo@branch` derives one id that names both the devpod workspace (what you
+see in `dl --ls`) and the clone directory under `~/.cache/devlaunch/repos/`:
+
+```
+<repo-slug>-<branch-slug>-<syllables>      at most 38 characters
+
+blooop/devlaunch@main                             -> devlaunch-main-zovomobo
+blooop/devlaunch@feature/auth                     -> devlaunch-feature-auth-poliseno
+blooop/devlaunch@feature-auth                     -> devlaunch-feature-auth-nesatabe
+blooop/test_renv@nb4                              -> test-renv-nb4-polenita
+kinisi-robotics/kinisi_ros@ags-devcontainer-tooling-support
+                                                  -> kinisi-ros-ags-devcontainer-t-lenevere
+blooop/devlaunch@dependabot/github_actions/codecov/codecov-action-6
+                                                  -> devlaunch-dependabot-codecov-sifivasa
+```
+
+The eight-character syllable suffix is a hash of the full `(owner, repo, branch)` triple.
+It is what makes the id unique: the readable part is shortened to fit the length limit,
+and shortening it does not affect whether two branches share an id. Long branch names
+drop whole `/`-separated middle segments before losing characters, so the part that
+identifies the branch survives. Note the third and fourth lines above: `feature/auth` and
+`feature-auth` read the same once slugged but are different branches, and they get
+different ids.
+
+Owner and repo are matched case-insensitively, the way GitHub treats them, so
+`dl NVIDIA/cuda-samples@main` and `dl nvidia/cuda-samples@main` are the same workspace.
+Branch names are case-sensitive, because git refs are.
+
+URL specs (`dl github.com/owner/repo`) get an id in the same shape, with the suffix
+hashed over the URL.
+
+The id is also the container hostname, so it stays well inside the 38-character budget
+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 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
 
 | Command | Description |
@@ -176,7 +253,23 @@ stays in place — including one it was given before you set
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
 | `dl --refresh` | Refresh completion cache |
 | `dl --help, -h` | Show this help |
-| `dl --version` | Show version |
+| `dl --version` | Show version (an editable install also names the tree it runs from) |
+
+A released install prints the version and nothing else. An install made in
+editable mode says so and names the checkout it resolves to, so two builds of
+the same version are told apart at a glance:
+
+```bash
+$ dl --version
+dl 0.0.9
+
+$ dl-next --version          # editable install of a working tree
+dl 0.0.9 (dev, editable from /path/to/your/devlaunch)
+```
+
+`aid --version` reports the same thing under its own name. The provenance comes
+from the installed package's own PEP 610 metadata; an install that records none
+just prints the bare version.
 
 ## Examples
 
@@ -198,6 +291,7 @@ dl blooop/devlaunch stop         # Stop workspace
 - **GitHub Shorthand**: Use `owner/repo` instead of full URLs - automatically expands to `github.com/owner/repo`
 - **Branch Support**: Specify branches with `owner/repo@branch` syntax
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
+- **One Round-Trip Per Question**: every `devpod` call costs ~0.45s, far more than `dl` itself, so a command reads the workspace list at most once — and `dl <ws> -- <cmd>` skips the extra round-trip that names an interactive prompt, since a one-shot command has none
 
 ## Worktree Backend
 
@@ -233,6 +327,19 @@ After running `dl --install`, you get intelligent tab completion:
 - File/directory paths when starting with `./`, `/`, or `~`
 - All global flags (`--ls`, `--install`, etc.) and workspace commands
 
+### How the completion cache stays current
+
+The data behind completions lives in `~/.cache/devlaunch/completions.json`, and
+building it means a `git ls-remote` per known repo — seconds of work. So it is
+rebuilt in the background at most once an hour (the same interval the worktree
+backend uses for lazy fetches), and at most once per `dl` invocation. Commands
+that change your workspaces (starting, stopping or deleting one) rebuild it as
+soon as they finish, regardless of when it was last built. Commands with no use
+for it — `dl --help`, `dl --version` — do not touch it at all.
+
+A branch created on a remote in the last hour may therefore not be offered yet.
+`dl --refresh` rebuilds the cache immediately and ignores the interval.
+
 ## Development
 
 This project uses [pixi](https://pixi.sh) for environment management.