devlaunch 0.0.7__tar.gz → 0.0.9__tar.gz

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

@@ -179,20 +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/
-.ralph/
 
 # uv is not this project's package manager (pixi.lock is authoritative)
 uv.lock

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.7
+Version: 0.0.9
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -33,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.7-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
+[![Conda](https://img.shields.io/badge/conda-v0.0.9-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)
@@ -55,10 +55,12 @@ 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
 
-After installation, set up shell completions:
+After installation, set up shell completions for `dl` and `aid`:
 
 ```bash
 dl --install
@@ -74,6 +76,44 @@ dl <user/repo> <cmd>             # Run workspace command (stop, code, etc.)
 dl <user/repo> -- <command>      # Run shell command in workspace
 ```
 
+## aid: start a coding agent in a workspace
+
+`aid` is `dl` with a coding agent started for you:
+
+```bash
+aid <user/repo>[@branch] [prompt...]   # Open the workspace, start the agent
+```
+
+It is a shortcut, not a second launcher. `aid` rewrites its command line into a
+`dl` one and hands it to `dl` itself, so
+
+```bash
+aid blooop/devlaunch@fix/42 fix the flaky test
+```
+
+is exactly
+
+```bash
+dl blooop/devlaunch@fix/42 -- claude 'fix the flaky test'
+```
+
+That means an `aid` workspace *is* the `dl` workspace: same clone, same workspace
+id, same container — started if stopped, attached to if already running, and never
+rebuilt just because `aid` asked for it. Anything `dl` learns, `aid` gets.
+
+| Option | Description |
+|--------|-------------|
+| `--claude`, `--codex`, `--gemini` | Pick the agent (default: `claude`) |
+| `--devcontainer <variant\|path>` | Passed through to `dl` |
+| `DEVLAUNCH_AID_AGENT=<agent>` | Change the default agent |
+
+Everything after the workspace is the prompt, flags and all, so it never needs
+quoting to survive `aid`'s own parsing. Managing workspaces — listing, stopping,
+deleting, VS Code — stays with `dl`.
+
+The agent's CLI has to be installed in the container; `aid` runs it there, it does
+not install it.
+
 ## Workspace Sources
 
 ```bash
@@ -105,6 +145,50 @@ Projects with demanding devcontainers — several variants, compose sidecars, or
 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 |
@@ -163,13 +247,6 @@ Use `--warm` to prepare a workspace without attaching a shell:
 dl --warm owner/repo@branch  # Creates container in background
 ```
 
-### Backend Selection
-
-```bash
-dl --backend devpod owner/repo  # Force legacy DevPod backend
-DEVLAUNCH_BACKEND=devpod dl owner/repo  # Use environment variable
-```
-
 ## Shell Completion
 
 After running `dl --install`, you get intelligent tab completion:

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

@@ -10,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.7-brightgreen?logo=anaconda)](https://prefix.dev/channels/blooop/packages/devlaunch)
+[![Conda](https://img.shields.io/badge/conda-v0.0.9-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,10 +32,12 @@ 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
 
-After installation, set up shell completions:
+After installation, set up shell completions for `dl` and `aid`:
 
 ```bash
 dl --install
@@ -51,6 +53,44 @@ dl <user/repo> <cmd>             # Run workspace command (stop, code, etc.)
 dl <user/repo> -- <command>      # Run shell command in workspace
 ```
 
+## aid: start a coding agent in a workspace
+
+`aid` is `dl` with a coding agent started for you:
+
+```bash
+aid <user/repo>[@branch] [prompt...]   # Open the workspace, start the agent
+```
+
+It is a shortcut, not a second launcher. `aid` rewrites its command line into a
+`dl` one and hands it to `dl` itself, so
+
+```bash
+aid blooop/devlaunch@fix/42 fix the flaky test
+```
+
+is exactly
+
+```bash
+dl blooop/devlaunch@fix/42 -- claude 'fix the flaky test'
+```
+
+That means an `aid` workspace *is* the `dl` workspace: same clone, same workspace
+id, same container — started if stopped, attached to if already running, and never
+rebuilt just because `aid` asked for it. Anything `dl` learns, `aid` gets.
+
+| Option | Description |
+|--------|-------------|
+| `--claude`, `--codex`, `--gemini` | Pick the agent (default: `claude`) |
+| `--devcontainer <variant\|path>` | Passed through to `dl` |
+| `DEVLAUNCH_AID_AGENT=<agent>` | Change the default agent |
+
+Everything after the workspace is the prompt, flags and all, so it never needs
+quoting to survive `aid`'s own parsing. Managing workspaces — listing, stopping,
+deleting, VS Code — stays with `dl`.
+
+The agent's CLI has to be installed in the container; `aid` runs it there, it does
+not install it.
+
 ## Workspace Sources
 
 ```bash
@@ -82,6 +122,50 @@ Projects with demanding devcontainers — several variants, compose sidecars, or
 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 |
@@ -140,13 +224,6 @@ Use `--warm` to prepare a workspace without attaching a shell:
 dl --warm owner/repo@branch  # Creates container in background
 ```
 
-### Backend Selection
-
-```bash
-dl --backend devpod owner/repo  # Force legacy DevPod backend
-DEVLAUNCH_BACKEND=devpod dl owner/repo  # Use environment variable
-```
-
 ## Shell Completion
 
 After running `dl --install`, you get intelligent tab completion:

devlaunch-0.0.9/devlaunch/aid.py

@@ -0,0 +1,212 @@
+"""aid - AI Develop: `dl`, with a coding agent started for you.
+
+aid is a shortcut, not a second launcher. It rewrites its own command line into
+a `dl` one and hands that to :func:`devlaunch.dl.main`, so:
+
+    aid owner/repo@branch fix the flaky test
+
+is exactly
+
+    dl owner/repo@branch -- claude 'fix the flaky test'
+
+Everything that decides how a workspace is obtained — the bare repo cache, the
+worktree clone, the workspace id, the devpod container, the fast attach to one
+that is already running, the forwarded gh login — happens inside dl, once. There
+is no container machinery in this module, deliberately: an aid that built its own
+would drift from dl and start rebuilding containers dl would have reused.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import sys
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from . import dl
+
+# Base command per agent. The prompt, when there is one, is appended as a single
+# quoted argument; each of these CLIs takes an initial prompt that way and then
+# drops into its interactive session.
+AGENT_COMMANDS: Dict[str, List[str]] = {
+    "claude": ["claude"],
+    "codex": ["codex"],
+    "gemini": ["gemini", "--prompt-interactive"],
+}
+
+# Flags that pick the agent, e.g. `aid --gemini owner/repo ...`.
+AGENT_FLAGS: Dict[str, str] = {f"--{name}": name for name in AGENT_COMMANDS}
+
+DEFAULT_AGENT = "claude"
+
+# Overrides the default agent for people who do not want to type a flag every
+# time. A --flag on the command line still wins.
+AGENT_ENV_VAR = "DEVLAUNCH_AID_AGENT"
+
+
+class UsageError(Exception):
+    """The aid command line could not be understood."""
+
+
+@dataclass(frozen=True)
+class AidArgs:
+    """An aid command line, split into the pieces the dl one is built from.
+
+    Only ever built by parse_aid_args, which refuses a command line without a
+    workspace, so spec is a str here and every field is ready to use.
+    """
+
+    spec: str
+    agent: str = DEFAULT_AGENT
+    # dl options seen before the spec (`--devcontainer x`), passed through as-is.
+    dl_options: List[str] = field(default_factory=list)
+    prompt: str = ""
+
+
+def default_agent(env: Optional[Dict[str, str]] = None) -> str:
+    """Return the agent to use when no flag picks one."""
+    environ = os.environ if env is None else env
+    name = environ.get(AGENT_ENV_VAR, "").strip()
+    if not name:
+        return DEFAULT_AGENT
+    if name not in AGENT_COMMANDS:
+        raise UsageError(
+            f"{AGENT_ENV_VAR}={name!r} is not a known agent. "
+            f"Choose one of: {', '.join(sorted(AGENT_COMMANDS))}."
+        )
+    return name
+
+
+def parse_aid_args(argv: List[str], env: Optional[Dict[str, str]] = None) -> AidArgs:
+    """Split an aid command line into agent, dl options, workspace spec and prompt.
+
+    The first argument that is neither an agent flag nor a dl option is the
+    workspace spec; everything after it is the prompt, flags and all, so a
+    prompt never has to be quoted to protect it from aid's own parsing.
+    """
+    agent = default_agent(env)
+    dl_options: List[str] = []
+    spec: Optional[str] = None
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg in AGENT_FLAGS:
+            agent = AGENT_FLAGS[arg]
+            i += 1
+            continue
+        if arg in dl.DL_VALUE_OPTIONS:
+            # Take the value with it; dl reports a missing one.
+            dl_options.extend(argv[i : i + 2])
+            i += 2
+            continue
+        if arg.startswith("-"):
+            dl_options.append(arg)
+            i += 1
+            continue
+        spec = arg
+        i += 1
+        break
+
+    if spec is None:
+        raise UsageError("aid needs a workspace: aid <user/repo>[@branch] [prompt]")
+
+    return AidArgs(spec=spec, agent=agent, dl_options=dl_options, prompt=" ".join(argv[i:]))
+
+
+def build_agent_command(agent: str, prompt: str = "") -> str:
+    """Build the shell command that starts the agent inside the workspace.
+
+    Returned as one shell string because that is what dl's `-- <command>` form
+    takes. The prompt is quoted here rather than reassembled by the caller, so
+    the words the user typed reach the agent as the single argument they meant.
+    """
+    try:
+        command = list(AGENT_COMMANDS[agent])
+    except KeyError:
+        raise UsageError(
+            f"Unknown agent {agent!r}. Choose one of: {', '.join(sorted(AGENT_COMMANDS))}."
+        ) from None
+    if not prompt:
+        # No prompt to be interactive about: start the agent's plain session.
+        # gemini's --prompt-interactive would be a syntax error without one.
+        return shlex.quote(command[0])
+    command.append(prompt)
+    return shlex.join(command)
+
+
+def build_dl_args(parsed: AidArgs) -> List[str]:
+    """Turn a parsed aid command line into the dl one that does the work."""
+    return [
+        *parsed.dl_options,
+        parsed.spec,
+        "--",
+        build_agent_command(parsed.agent, parsed.prompt),
+    ]
+
+
+def print_help() -> None:
+    """Print usage help."""
+    agents = ", ".join(f"--{name}" for name in sorted(AGENT_COMMANDS))
+    print(
+        f"""aid - AI Develop: start a coding agent in a devlaunch workspace
+
+aid is a shortcut for `dl <workspace> -- <agent> '<prompt>'`. The workspace is
+opened by dl itself, so it is the same workspace, container and clone that
+`dl <workspace>` gives you — started if it is stopped, attached to if it is
+already running, and never rebuilt just because aid asked for it.
+
+Usage:
+    aid <user/repo>[@branch] [prompt...]   Open the workspace and start the agent
+    aid <workspace> [prompt...]            Same, for an existing workspace or ./path
+
+Options:
+    {agents}
+                                     Pick the agent (default: {DEFAULT_AGENT})
+    --devcontainer <variant|path>    Passed through to dl
+    --help, -h                       Show this help
+    --version                        Show version
+
+Environment:
+    {AGENT_ENV_VAR}=<agent>       Change the default agent
+
+Examples:
+    aid blooop/devlaunch                       # Start {DEFAULT_AGENT} in the workspace
+    aid blooop/devlaunch@fix/42 fix the bug    # Open the branch, hand over the prompt
+    aid --gemini ./my-project explain this     # Pick a different agent
+
+Everything else — listing, stopping, deleting, VS Code — is dl's job:
+    dl --help
+"""
+    )
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Entry point for the aid command."""
+    args = sys.argv[1:] if argv is None else list(argv)
+
+    if not args or args[0] in ("--help", "-h"):
+        print_help()
+        return 0 if args else 1
+
+    if args[0] == "--version":
+        print(f"aid {dl.get_version()}")
+        return 0
+
+    try:
+        parsed = parse_aid_args(args)
+        dl_args = build_dl_args(parsed)
+    except UsageError as e:
+        logging.error(str(e))
+        return 1
+
+    logging.info("aid -> dl %s", shlex.join(dl_args))
+    return dl.main(dl_args)
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        sys.exit(130)

{devlaunch-0.0.7 → devlaunch-0.0.9}/devlaunch/completion.py

@@ -34,7 +34,7 @@ def _completion_file_path() -> pathlib.Path:
 
 
 def install_completions(rc_path: Optional[pathlib.Path] = None) -> int:
-    """Install or refresh completion scripts for dl."""
+    """Install or refresh completion scripts for dl and aid."""
     completion_path = _completion_file_path().expanduser()
     rc_target = (rc_path if rc_path is not None else pathlib.Path.home() / ".bashrc").expanduser()
 

{devlaunch-0.0.7 → devlaunch-0.0.9}/devlaunch/completions/dl.bash

@@ -8,6 +8,10 @@
 # because temporary COMP_WORDBREAKS modification can have side effects with bash's
 # internal completion state and doesn't reliably prevent word splitting in all
 # bash versions. Direct parsing gives us full control over word boundaries.
+#
+# The same function serves `aid`, whose first argument is a dl workspace spec
+# too. Only the flag list and what follows the spec differ, so the two places
+# that care branch on $cmd rather than the script being copied for aid.
 _dl_completion() {
     local cur prev opts
     COMPREPLY=()
@@ -44,8 +48,17 @@ _dl_completion() {
         fi
     fi
 
+    # The command being completed: dl or aid.
+    local cmd=""
+    if (( ${#words[@]} > 0 )); then
+        cmd="${words[0]##*/}"
+    fi
+
     # Global command options (only valid as first arg)
     local global_opts="--ls --install --help -h --version --devcontainer"
+    if [[ "$cmd" == aid ]]; then
+        global_opts="--claude --codex --gemini --devcontainer --help -h --version"
+    fi
 
     # Workspace subcommands
     local ws_cmds="stop rm code restart recreate reset --"
@@ -133,8 +146,9 @@ _dl_completion() {
         return 0
     fi
 
-    # Second argument (after workspace): subcommands
-    if [[ ${word_count} -eq 3 ]]; then
+    # Second argument (after workspace): subcommands. Everything after an aid
+    # workspace is the prompt, so there is nothing to offer there.
+    if [[ ${word_count} -eq 3 && "$cmd" != aid ]]; then
         # Don't complete after global flags
         # Extract the first argument (word after "dl") from the words array
         local first=""
@@ -155,4 +169,5 @@ _dl_completion() {
 
 # Use -o default for better completion behavior
 complete -o default -F _dl_completion dl
+complete -o default -F _dl_completion aid
 # end dl completion