devlaunch 0.0.8__tar.gz → 0.0.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.8
+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.8-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)
@@ -60,7 +60,7 @@ If `devpod` is not on `PATH`, every command that needs it prints a single instal
 
 ### Shell Completions
 
-After installation, set up shell completions:
+After installation, set up shell completions for `dl` and `aid`:
 
 ```bash
 dl --install
@@ -76,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

{devlaunch-0.0.8 → 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.8-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)
@@ -37,7 +37,7 @@ If `devpod` is not on `PATH`, every command that needs it prints a single instal
 
 ### Shell Completions
 
-After installation, set up shell completions:
+After installation, set up shell completions for `dl` and `aid`:
 
 ```bash
 dl --install
@@ -53,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

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.8 → 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.8 → 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

{devlaunch-0.0.8 → devlaunch-0.0.9}/devlaunch/dl.py

@@ -337,6 +337,12 @@ def _resolve_devcontainer_ref(ref: str) -> str:
     return f".devcontainer/{ref}/devcontainer.json"
 
 
+# dl options whose value is a separate argument. aid splits its own command line
+# before handing it to dl and has to tell such a value from the workspace spec,
+# so the list lives here, next to the parsing it describes.
+DL_VALUE_OPTIONS = frozenset({"--devcontainer"})
+
+
 def extract_devcontainer_flag(args: List[str]) -> tuple[List[str], Optional[str]]:
     """Pull `--devcontainer <name-or-path>` out of the argument list.
 
@@ -1003,24 +1009,31 @@ def _get_clone_manager() -> WorkspaceCloneManager:
     return _cache["clone_manager"]
 
 
-def main() -> int:
+def main(argv: Optional[List[str]] = None) -> int:
     """Main entry point for dl CLI.
 
     Thin wrapper so there is exactly one handler for a missing devpod, however
     deep in the command it was noticed. The message goes to stderr because
     stdout is parsed by the completion machinery (--repos, --completion-data).
+
+    argv is the argument list without the program name, defaulting to the real
+    one. It is a parameter so that a sibling entry point can hand dl a command
+    line it built and get dl's behaviour itself rather than a second copy of it
+    (see aid.py) — a copy is what left aid rebuilding containers dl reuses.
     """
     try:
-        return _run_cli()
+        return _run_cli(argv)
     except DevpodNotInstalled as e:
         print(e, file=sys.stderr)
         return DEVPOD_MISSING_EXIT_CODE
 
 
-def _run_cli() -> int:
+def _run_cli(argv: Optional[List[str]] = None) -> int:
     """Dispatch a dl command line. See main() for the error handling around it."""
+    if argv is None:
+        argv = sys.argv[1:]
     try:
-        args, devcontainer = extract_devcontainer_flag(sys.argv[1:])
+        args, devcontainer = extract_devcontainer_flag(argv)
     except ValueError as e:
         logging.error(str(e))
         return 1

{devlaunch-0.0.8 → devlaunch-0.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.8"
+version = "0.0.9"
 authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
 description = "DevLaunch - A streamlined CLI for devpod workspaces"
 readme = "README.md"
@@ -59,6 +59,7 @@ include = ["devlaunch"]
 
 [project.scripts]
 dl = "devlaunch.dl:main"
+aid = "devlaunch.aid:main"
 
 # Environments
 [tool.pixi.environments]