devlaunch 0.0.9__tar.gz → 0.0.10__tar.gz

{devlaunch-0.0.9 → devlaunch-0.0.10}/.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.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.9
+Version: 0.0.10
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -123,6 +123,50 @@ 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:** 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.
+
 ## Workspace Commands
 
 | Command | Description |
@@ -199,7 +243,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 +281,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 +317,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.10}/README.md

@@ -100,6 +100,50 @@ 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:** 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.
+
 ## Workspace Commands
 
 | Command | Description |
@@ -176,7 +220,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 +258,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 +294,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.