devlaunch 0.0.6__tar.gz → 0.0.8__tar.gz

{devlaunch-0.0.6 → devlaunch-0.0.8}/.gitignore

@@ -50,6 +50,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+test/docker/results/
 
 # Translations
 *.mo
@@ -178,16 +179,8 @@ test_suite_analysis/metadata.json
 # Claude Code local settings (personal, not shared)
 .claude/settings.local.json
 
-# Ralph autonomous agent state files
-.call_count
-.circuit_breaker_history
-.circuit_breaker_state
-.exit_signals
-.last_reset
-.ralph_session
-.ralph_session_history
-.response_analysis
 .claude_session_id
-progress.json
-status.json
 logs/
+
+# uv is not this project's package manager (pixi.lock is authoritative)
+uv.lock

devlaunch-0.0.6/README.md → devlaunch-0.0.8/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.4
+Name: devlaunch
+Version: 0.0.8
+Summary: DevLaunch - A streamlined CLI for devpod workspaces
+Project-URL: Source, https://github.com/blooop/devlaunch
+Project-URL: Home, https://github.com/blooop/devlaunch
+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'
+Requires-Dist: hypothesis<=6.155.1,>=6.104.2; extra == 'test'
+Requires-Dist: prek<0.5.0,>=0.2.28; extra == 'test'
+Requires-Dist: pylint<=4.0.5,>=3.2.5; extra == 'test'
+Requires-Dist: pytest-cov<=7.1.0,>=4.1; extra == 'test'
+Requires-Dist: pytest<=9.0.3,>=7.4; extra == 'test'
+Requires-Dist: ruff<=0.15.15,>=0.5.0; extra == 'test'
+Requires-Dist: ty<=0.0.19,>=0.0.12; extra == 'test'
+Description-Content-Type: text/markdown
+
 # devlaunch
 
 A streamlined CLI for [devpod](https://devpod.sh) with intuitive autocomplete and fzf fuzzy selection.
@@ -10,7 +33,7 @@ A streamlined CLI for [devpod](https://devpod.sh) with intuitive autocomplete an
 [![GitHub pull-requests merged](https://badgen.net/github/merged-prs/blooop/devlaunch)](https://github.com/blooop/devlaunch/pulls?q=is%3Amerged)
 [![GitHub release](https://img.shields.io/github/release/blooop/devlaunch.svg)](https://GitHub.com/blooop/devlaunch/releases/)
 [![PyPI](https://img.shields.io/pypi/v/devlaunch)](https://pypi.org/project/devlaunch/)
-[![Conda](https://img.shields.io/badge/conda-v0.0.5-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
+[![Conda](https://img.shields.io/badge/conda-v0.0.8-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
 [![License](https://img.shields.io/github/license/blooop/devlaunch)](https://opensource.org/license/mit/)
 [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/downloads/)
 [![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
@@ -32,6 +55,8 @@ pip install devlaunch
 ```
 
 Note: When using pip, you must install [devpod](https://devpod.sh/docs/getting-started/install) separately.
+If `devpod` is not on `PATH`, every command that needs it prints a single install hint on stderr and exits `127`
+(the shell's "command not found" code). `dl --help` and `dl --version` keep working without it.
 
 ### Shell Completions
 
@@ -72,12 +97,69 @@ dl ./path                        # Create from local path
 | `dl <user/repo> reset` | Clean slate (remove all, recreate) |
 | `dl <user/repo> -- <command>` | Run shell command in workspace |
 
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--devcontainer <variant\|path>` | Use a non-default `devcontainer.json`. A bare name means `.devcontainer/<name>/devcontainer.json`. Stored with the workspace, so pass it once. |
+
+Projects with demanding devcontainers — several variants, compose sidecars, or a
+host-side `initializeCommand` that has to tell branch workspaces apart — are
+covered in [docs/devcontainer-projects.md](docs/devcontainer-projects.md).
+
+## GitHub Authentication
+
+Every workspace `dl` opens inherits the host's GitHub login, so `gh` is already
+authenticated inside the container and the devcontainer.json does not have to
+arrange anything for it. devpod forwards the ssh agent and git credentials on its
+own, but nothing else carries `gh`.
+
+devlaunch takes the token from `GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`,
+whichever answers first, and hands it to the container as `GH_TOKEN`. That reaches
+any image and any container user, unlike a bind-mount of `~/.config/gh`, and it
+works whether the host keeps its token in `hosts.yml` or in a keyring. The token
+is passed to devpod through a private file and through devpod's own environment,
+never on a command line, so it does not appear in `ps`. The container still needs
+`gh` installed for the login to be of any use. Check a workspace with:
+
+```bash
+dl <workspace> -- gh auth status
+```
+
+### Who gets the token
+
+Everything running in the container does — including a `postCreateCommand` from a
+repo you did not write. `dl someone/repo` builds and runs that project's
+devcontainer with your GitHub token in its environment, and a `gh auth login` token
+usually carries `repo`, `workflow`, `gist` and `read:org` scopes. devpod already
+forwards the ssh agent to every workspace, so this is not a new trust boundary, but
+it is a wider one. Skip it for a repo you have not read:
+
+```bash
+DEVLAUNCH_NO_GH_TOKEN=1 dl someone/repo
+```
+
+| Variable | Description |
+|----------|-------------|
+| `DEVLAUNCH_NO_GH_TOKEN=1` | Do not forward the host's GitHub login into workspaces |
+
+### When the token changes
+
+`dl` refreshes the token on every start, so rotating it on the host is enough for
+any workspace that gets started or restarted afterwards. Attaching to a workspace
+that is *already running* skips that step, and the token it was given at startup
+stays in place — including one it was given before you set
+`DEVLAUNCH_NO_GH_TOKEN`. Run `dl <workspace> restart` to replace it.
+
 ## Global Commands
 
 | Command | Description |
 |---------|-------------|
 | `dl --ls` | List all workspaces |
 | `dl --install` | Install shell completions |
+| `dl --purge [-y]` | Remove all devlaunch data |
+| `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 |
 
@@ -102,6 +184,31 @@ dl blooop/devlaunch stop         # Stop workspace
 - **Branch Support**: Specify branches with `owner/repo@branch` syntax
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
 
+## Worktree Backend
+
+For git repositories, devlaunch uses an efficient worktree backend by default:
+
+- **Efficient Storage**: Repos are cloned once to `~/.cache/devlaunch/repos/owner/repo/`, then git worktrees are created for each branch
+- **Shared Git Objects**: All branches share git objects, saving disk space
+- **Lazy Fetch**: Remote updates are only fetched if the configured interval has elapsed (default: 1 hour)
+
+### Container Sharing Mode
+
+Use `--shared` to share a single container across multiple branches of the same repo:
+
+```bash
+dl --shared owner/repo@branch1  # Creates container "owner-repo"
+dl --shared owner/repo@branch2  # Reuses "owner-repo" container
+```
+
+### Pre-warming
+
+Use `--warm` to prepare a workspace without attaching a shell:
+
+```bash
+dl --warm owner/repo@branch  # Creates container in background
+```
+
 ## Shell Completion
 
 After running `dl --install`, you get intelligent tab completion:

devlaunch-0.0.6/PKG-INFO → devlaunch-0.0.8/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: devlaunch
-Version: 0.0.6
-Summary: DevLaunch - A streamlined CLI for devpod workspaces
-Project-URL: Source, https://github.com/blooop/devlaunch
-Project-URL: Home, https://github.com/blooop/devlaunch
-Author-email: Austin Gregg-Smith <blooop@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Dist: iterfzf>=1.0.0
-Provides-Extra: test
-Requires-Dist: coverage<=7.13.1,>=7.5.4; extra == 'test'
-Requires-Dist: hypothesis<=6.150.2,>=6.104.2; extra == 'test'
-Requires-Dist: prek<0.3.0,>=0.2.28; extra == 'test'
-Requires-Dist: pylint<=4.0.4,>=3.2.5; extra == 'test'
-Requires-Dist: pytest-cov<=7.0.0,>=4.1; extra == 'test'
-Requires-Dist: pytest<=9.0.2,>=7.4; extra == 'test'
-Requires-Dist: ruff<=0.14.13,>=0.5.0; extra == 'test'
-Requires-Dist: ty<=0.0.12,>=0.0.12; extra == 'test'
-Description-Content-Type: text/markdown
-
 # devlaunch
 
 A streamlined CLI for [devpod](https://devpod.sh) with intuitive autocomplete and fzf fuzzy selection.
@@ -31,7 +10,7 @@ A streamlined CLI for [devpod](https://devpod.sh) with intuitive autocomplete an
 [![GitHub pull-requests merged](https://badgen.net/github/merged-prs/blooop/devlaunch)](https://github.com/blooop/devlaunch/pulls?q=is%3Amerged)
 [![GitHub release](https://img.shields.io/github/release/blooop/devlaunch.svg)](https://GitHub.com/blooop/devlaunch/releases/)
 [![PyPI](https://img.shields.io/pypi/v/devlaunch)](https://pypi.org/project/devlaunch/)
-[![Conda](https://img.shields.io/badge/conda-v0.0.5-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
+[![Conda](https://img.shields.io/badge/conda-v0.0.8-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
 [![License](https://img.shields.io/github/license/blooop/devlaunch)](https://opensource.org/license/mit/)
 [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/downloads/)
 [![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
@@ -53,6 +32,8 @@ pip install devlaunch
 ```
 
 Note: When using pip, you must install [devpod](https://devpod.sh/docs/getting-started/install) separately.
+If `devpod` is not on `PATH`, every command that needs it prints a single install hint on stderr and exits `127`
+(the shell's "command not found" code). `dl --help` and `dl --version` keep working without it.
 
 ### Shell Completions
 
@@ -93,12 +74,69 @@ dl ./path                        # Create from local path
 | `dl <user/repo> reset` | Clean slate (remove all, recreate) |
 | `dl <user/repo> -- <command>` | Run shell command in workspace |
 
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--devcontainer <variant\|path>` | Use a non-default `devcontainer.json`. A bare name means `.devcontainer/<name>/devcontainer.json`. Stored with the workspace, so pass it once. |
+
+Projects with demanding devcontainers — several variants, compose sidecars, or a
+host-side `initializeCommand` that has to tell branch workspaces apart — are
+covered in [docs/devcontainer-projects.md](docs/devcontainer-projects.md).
+
+## GitHub Authentication
+
+Every workspace `dl` opens inherits the host's GitHub login, so `gh` is already
+authenticated inside the container and the devcontainer.json does not have to
+arrange anything for it. devpod forwards the ssh agent and git credentials on its
+own, but nothing else carries `gh`.
+
+devlaunch takes the token from `GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`,
+whichever answers first, and hands it to the container as `GH_TOKEN`. That reaches
+any image and any container user, unlike a bind-mount of `~/.config/gh`, and it
+works whether the host keeps its token in `hosts.yml` or in a keyring. The token
+is passed to devpod through a private file and through devpod's own environment,
+never on a command line, so it does not appear in `ps`. The container still needs
+`gh` installed for the login to be of any use. Check a workspace with:
+
+```bash
+dl <workspace> -- gh auth status
+```
+
+### Who gets the token
+
+Everything running in the container does — including a `postCreateCommand` from a
+repo you did not write. `dl someone/repo` builds and runs that project's
+devcontainer with your GitHub token in its environment, and a `gh auth login` token
+usually carries `repo`, `workflow`, `gist` and `read:org` scopes. devpod already
+forwards the ssh agent to every workspace, so this is not a new trust boundary, but
+it is a wider one. Skip it for a repo you have not read:
+
+```bash
+DEVLAUNCH_NO_GH_TOKEN=1 dl someone/repo
+```
+
+| Variable | Description |
+|----------|-------------|
+| `DEVLAUNCH_NO_GH_TOKEN=1` | Do not forward the host's GitHub login into workspaces |
+
+### When the token changes
+
+`dl` refreshes the token on every start, so rotating it on the host is enough for
+any workspace that gets started or restarted afterwards. Attaching to a workspace
+that is *already running* skips that step, and the token it was given at startup
+stays in place — including one it was given before you set
+`DEVLAUNCH_NO_GH_TOKEN`. Run `dl <workspace> restart` to replace it.
+
 ## Global Commands
 
 | Command | Description |
 |---------|-------------|
 | `dl --ls` | List all workspaces |
 | `dl --install` | Install shell completions |
+| `dl --purge [-y]` | Remove all devlaunch data |
+| `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 |
 
@@ -123,6 +161,31 @@ dl blooop/devlaunch stop         # Stop workspace
 - **Branch Support**: Specify branches with `owner/repo@branch` syntax
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
 
+## Worktree Backend
+
+For git repositories, devlaunch uses an efficient worktree backend by default:
+
+- **Efficient Storage**: Repos are cloned once to `~/.cache/devlaunch/repos/owner/repo/`, then git worktrees are created for each branch
+- **Shared Git Objects**: All branches share git objects, saving disk space
+- **Lazy Fetch**: Remote updates are only fetched if the configured interval has elapsed (default: 1 hour)
+
+### Container Sharing Mode
+
+Use `--shared` to share a single container across multiple branches of the same repo:
+
+```bash
+dl --shared owner/repo@branch1  # Creates container "owner-repo"
+dl --shared owner/repo@branch2  # Reuses "owner-repo" container
+```
+
+### Pre-warming
+
+Use `--warm` to prepare a workspace without attaching a shell:
+
+```bash
+dl --warm owner/repo@branch  # Creates container in background
+```
+
 ## Shell Completion
 
 After running `dl --install`, you get intelligent tab completion:

{devlaunch-0.0.6 → devlaunch-0.0.8}/devlaunch/completions/dl.bash

@@ -45,13 +45,32 @@ _dl_completion() {
     fi
 
     # Global command options (only valid as first arg)
-    local global_opts="--ls --install --help -h --version"
+    local global_opts="--ls --install --help -h --version --devcontainer"
 
     # Workspace subcommands
     local ws_cmds="stop rm code restart recreate reset --"
 
+    # Options that take a value; a variant name or a path follows them.
+    local value_opts="--devcontainer"
+
+    # After --devcontainer, offer the repo's variant directories (and paths).
+    if [[ " ${value_opts} " == *" ${prev} "* ]]; then
+        local variants=""
+        if [[ -d .devcontainer ]]; then
+            local d
+            for d in .devcontainer/*/devcontainer.json; do
+                [[ -f "$d" ]] || continue
+                d="${d#.devcontainer/}"
+                variants+=" ${d%/devcontainer.json}"
+            done
+        fi
+        COMPREPLY=( $(compgen -W "${variants}" -- ${cur}) )
+        compopt -o default 2>/dev/null
+        return 0
+    fi
+
     # Cache file location (honors XDG_CACHE_HOME)
-    local cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/dl"
+    local cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/devlaunch"
     local cache_file="$cache_dir/completions.bash"
 
     # Initialize completion variables