coding-agent-wrapper 0.1.0__tar.gz → 0.1.2__tar.gz

{coding_agent_wrapper-0.1.0 → coding_agent_wrapper-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-agent-wrapper
-Version: 0.1.0
+Version: 0.1.2
 Summary: Unified Python library and CLI for orchestrating coding agents (Claude Code, Codex, etc.) with MCP tool servers and credential management.
 Project-URL: Homepage, https://github.com/zzjas/caw
 Project-URL: Repository, https://github.com/zzjas/caw
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 # caw
 
-**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex, Gemini CLI, Cursor) with a unified interface, MCP tool servers, and credential management for Docker containers.
+**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex) with a unified interface, MCP tool servers, and credential management for Docker containers.
 
 ## Install
 
@@ -197,13 +197,13 @@ Sessions are persisted to JSONL in `caw_data/` by default.
 
 ## CLI: `caw auth` — Credential Management for Docker Containers
 
-Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code, Codex, Gemini CLI, and Cursor.
+Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code and Codex. Host credential files are never modified — they are bind-mounted into the container at run time.
 
 ```bash
-caw auth setup                        # collect + symlink credentials
-caw auth status                       # check symlink state and token expiry
+caw auth setup                        # snapshot configs, write mount manifest
+caw auth status                       # token expiry, last modified, mount flags
 docker run $(caw auth docker-flags) -v ./project:/work my-image
-caw auth teardown                     # restore original files
+caw auth teardown                     # rm -rf ~/.caw/auth/  (host files untouched)
 ```
 
 See [`caw/auth/README.md`](caw/auth/README.md) for details on how it works, container setup, and supported agents.

{coding_agent_wrapper-0.1.0 → coding_agent_wrapper-0.1.2}/README.md

@@ -1,6 +1,6 @@
 # caw
 
-**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex, Gemini CLI, Cursor) with a unified interface, MCP tool servers, and credential management for Docker containers.
+**Coding Agent Wrapper** — a Python library and CLI for orchestrating coding agents (Claude Code, Codex) with a unified interface, MCP tool servers, and credential management for Docker containers.
 
 ## Install
 
@@ -167,13 +167,13 @@ Sessions are persisted to JSONL in `caw_data/` by default.
 
 ## CLI: `caw auth` — Credential Management for Docker Containers
 
-Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code, Codex, Gemini CLI, and Cursor.
+Manages coding agent OAuth credentials so they stay in sync between your host and Docker containers. Supports Claude Code and Codex. Host credential files are never modified — they are bind-mounted into the container at run time.
 
 ```bash
-caw auth setup                        # collect + symlink credentials
-caw auth status                       # check symlink state and token expiry
+caw auth setup                        # snapshot configs, write mount manifest
+caw auth status                       # token expiry, last modified, mount flags
 docker run $(caw auth docker-flags) -v ./project:/work my-image
-caw auth teardown                     # restore original files
+caw auth teardown                     # rm -rf ~/.caw/auth/  (host files untouched)
 ```
 
 See [`caw/auth/README.md`](caw/auth/README.md) for details on how it works, container setup, and supported agents.

coding_agent_wrapper-0.1.2/caw/auth/README.md

@@ -0,0 +1,114 @@
+# caw auth — Credential Management for Docker Containers
+
+Coding agents store OAuth credentials in home directory files (e.g., `~/.claude/.credentials.json`). When running agents inside Docker containers, token refresh creates new tokens (OAuth rotation), invalidating the host's tokens.
+
+`caw auth` solves this **without modifying host files**: it bind-mounts the host credentials directly into the container, and runs an inotify-based guard that syncs the container user's home copy with the bind-mounted host file in both directions.
+
+## How it works
+
+```
+HOST:                                         CONTAINER:
+
+~/.claude/.credentials.json  ←—docker bind—→  /tmp/caw_auth/claude/credentials.json
+    (untouched, real file)                         ↓ copy + inotify sync
+                                               /home/playground/.claude/.credentials.json
+```
+
+`~/.caw/auth/` only holds things CAW legitimately owns: the manifest, the container setup script, and cleaned/stripped configs. Credentials stay at their original host paths.
+
+## Usage
+
+```bash
+caw auth setup                        # snapshot configs + write manifest/setup script
+caw auth setup --agents claude codex  # specific agents only
+
+caw auth status                       # token expiry, last modified, mount flags
+
+docker run $(caw auth docker-flags) -v ./project:/work my-image
+
+caw auth teardown                     # rm -rf ~/.caw/auth/  (host files never touched)
+```
+
+## Commands
+
+### `caw auth setup`
+
+Reads credentials and configs from the host, validates them, writes cleaned configs and a credential snapshot into `~/.caw/auth/`, and generates `manifest.json` + `setup-container.sh`. Host credential files are **read but never modified**.
+
+- Credential files (tokens, OAuth) — `strategy: bind`. Bind-mounted from the host into the container at run time; the container-side guard copies them to the user's home and keeps them in sync.
+- Config files (.claude.json, config.toml) — `strategy: copy`. Cleaned/stripped for containers and shipped in the staging directory.
+
+### `caw auth teardown`
+
+Removes `~/.caw/auth/`. Host credential files are never involved.
+
+### `caw auth status`
+
+Shows a table with each managed file, where its source of truth lives (host for bind, staged for copy), last modified time, and token expiry for credential files. Credential freshness is read from the host file directly.
+
+### `caw auth docker-flags`
+
+Emits one directory mount for the staging area plus one file mount per credential:
+
+```bash
+$ caw auth docker-flags
+-v /home/user/.caw/auth:/tmp/caw_auth:rw \
+-v /home/user/.claude/.credentials.json:/tmp/caw_auth/claude/credentials.json:rw \
+-v /home/user/.codex/auth.json:/tmp/caw_auth/codex/auth.json:rw
+```
+
+Command substitution (`$(caw auth docker-flags)`) expands these into separate `docker run` arguments.
+
+## Container setup
+
+The generated `setup-container.sh` runs inside the container (called from your entrypoint). It reads `manifest.json`, copies credentials and configs into the container user's home, and starts a bidirectional inotify guard for credential sync.
+
+```bash
+# In your entrypoint.sh:
+if [ -f /tmp/caw_auth/setup-container.sh ]; then
+    /tmp/caw_auth/setup-container.sh /tmp/caw_auth /home/playground playground
+fi
+```
+
+The guard runs as root and uses plain `cp` (no `--preserve`, no `chown` on the mount side), so writes back to the host file preserve the host user's uid/gid/mode on the real inode. Requires `jq` in the container image; `inotify-tools` is installed automatically if not present.
+
+## Directory structure
+
+```
+~/.caw/auth/
+├── manifest.json              # file map + metadata (records strategy per file)
+├── setup-container.sh         # POSIX script for container setup
+├── claude/
+│   ├── credentials.json       # snapshot (bind-mounted over at container run)
+│   └── config.json            # cleaned .claude.json (copied)
+└── codex/
+    ├── auth.json              # snapshot (bind-mounted over at container run)
+    └── config.toml            # cleaned config (copied)
+```
+
+The credential snapshots exist so Docker has a target path to overlay with the host file. The staged bytes are never read at container run time — the bind mount supersedes them.
+
+## Supported agents
+
+| Agent | Credential files | Config files |
+|-------|-----------------|--------------|
+| Claude Code | `.claude/.credentials.json` | `.claude.json` (stripped to essential keys) |
+| Codex | `.codex/auth.json` | `.codex/config.toml` (local trust removed) |
+
+## Programmatic API
+
+```python
+from caw.auth import setup, teardown, get_status, get_docker_flags
+
+setup(agents=["claude"])
+statuses = get_status()
+flags = get_docker_flags()
+teardown()
+```
+
+See [`examples/auth.py`](../../examples/auth.py) for a full example.
+
+## Known limitations
+
+- **OAuth token rotation**: a refresh returns a new refresh token, invalidating the old one. If two processes refresh simultaneously, one gets an invalid token. Don't run the same agent identity in two places at once.
+- **Atomic rewrites**: if an agent refreshes by writing a temp file and `rename(2)`-ing it over the credential, a single-file bind mount detaches from the new inode. If this becomes a real problem for a given agent, switch that agent's bind to a directory bind (mount the parent directory instead), which survives renames.

coding_agent_wrapper-0.1.2/caw/auth/__init__.py

@@ -0,0 +1,115 @@
+"""caw.auth — Credential management for Docker containers."""
+
+import shutil
+from pathlib import Path
+
+from .collector import default_auth_dir, setup
+from .manifest import Manifest, AgentManifest, ManifestFile
+from .providers import PROVIDERS, AgentAuthProvider, CollectedFile
+from .status import AuthFileStatus, get_docker_flags, get_status, status
+
+
+class TeardownWouldOrphanSymlinksError(RuntimeError):
+    """Raised when teardown would break host symlinks left by the old caw design."""
+
+
+def _find_old_design_symlinks(auth_dir: Path) -> list[tuple[Path, Path]]:
+    """Return (host_path, target_inside_auth_dir) pairs for any host files
+    that are symlinks pointing into ``auth_dir``.
+
+    The pre-bind-mount version of caw replaced host credential files with
+    symlinks into ~/.caw/auth/. Removing ``auth_dir`` in that state would
+    leave dangling symlinks with no backup. This helper lets teardown detect
+    the situation and refuse.
+    """
+    manifest_path = auth_dir / "manifest.json"
+    if not manifest_path.exists():
+        return []
+    manifest = Manifest.load(manifest_path)
+    host_home = Path(manifest.host_home)
+    resolved_auth = auth_dir.resolve()
+
+    dangerous: list[tuple[Path, Path]] = []
+    for agent in manifest.agents.values():
+        for mf in agent.files:
+            host = host_home / mf.host_original
+            if not host.is_symlink():
+                continue
+            try:
+                target = Path(str(host.resolve(strict=False)))
+            except OSError:
+                continue
+            try:
+                target.relative_to(resolved_auth)
+            except ValueError:
+                continue
+            dangerous.append((host, target))
+    return dangerous
+
+
+def teardown(auth_dir: str | Path | None = None, force: bool = False) -> None:
+    """Remove the auth directory. Host credential files are never touched.
+
+    Refuses to run if any host credential file is still a symlink into
+    ``auth_dir`` (legacy state from the old symlink-based design), since
+    removing the directory would leave dangling symlinks with no backup.
+    Pass ``force=True`` to override.
+
+    Args:
+        auth_dir: Custom auth directory. Defaults to ~/.caw/auth/.
+        force: Delete even if host symlinks point into ``auth_dir``.
+
+    Raises:
+        TeardownWouldOrphanSymlinksError: If host symlinks point into the
+            auth directory and ``force`` is False.
+    """
+    target = Path(auth_dir) if auth_dir else default_auth_dir()
+    if not target.exists():
+        return
+
+    if not force:
+        dangerous = _find_old_design_symlinks(target)
+        if dangerous:
+            lines = [f"  {host} -> {t}" for host, t in dangerous]
+            raise TeardownWouldOrphanSymlinksError(
+                "Refusing to remove "
+                f"{target}: host credential files still symlink into it "
+                "(leftover from the old symlink-based design). Removing the "
+                "directory would leave dangling symlinks and you would need "
+                "to re-authenticate every agent.\n\n"
+                "Do one of:\n"
+                "  1. Replace each symlink with its real file first:\n"
+                "     for f in <paths>; do cp --remove-destination "
+                '"$(readlink -f "$f")" "$f"; done\n'
+                "  2. Call teardown(force=True) if you accept re-auth.\n\n"
+                "Affected symlinks:\n" + "\n".join(lines)
+            )
+
+    shutil.rmtree(target)
+
+
+def __getattr__(name: str):
+    # Re-resolve AUTH_DIR at access time so users who set CAW_AUTH_DIR after
+    # `from caw.auth import AUTH_DIR` still see the override.
+    if name == "AUTH_DIR":
+        return default_auth_dir()
+    raise AttributeError(name)
+
+
+__all__ = [
+    "AUTH_DIR",
+    "AgentAuthProvider",
+    "default_auth_dir",
+    "AgentManifest",
+    "AuthFileStatus",
+    "CollectedFile",
+    "Manifest",
+    "ManifestFile",
+    "PROVIDERS",
+    "TeardownWouldOrphanSymlinksError",
+    "get_docker_flags",
+    "get_status",
+    "setup",
+    "status",
+    "teardown",
+]

coding_agent_wrapper-0.1.2/caw/auth/cli.py

@@ -0,0 +1,95 @@
+"""CLI subcommands for `caw auth`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+
+app = typer.Typer(help="Manage credentials for Docker containers.")
+
+
+@app.command()
+def setup(
+    agents: Annotated[
+        Optional[list[str]],
+        typer.Option("--agents", "-a", help="Agents to include (claude, codex, or all)"),
+    ] = None,
+    source_home: Annotated[
+        str,
+        typer.Option("--source-home", help="Source home directory to read credentials from"),
+    ] = str(Path.home()),
+):
+    """Snapshot credentials and write the container setup bundle into ~/.caw/auth/.
+
+    Host credential files are not modified; they are bind-mounted into the
+    container at run time via `caw auth docker-flags`.
+    """
+    from .collector import setup as do_setup
+
+    do_setup(agents=agents or ["all"], source_home=source_home)
+
+
+@app.command()
+def teardown(
+    dry_run: Annotated[bool, typer.Option("--dry-run", "-n", help="Show what would be done")] = False,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Delete even if host symlinks point into the auth dir"),
+    ] = False,
+):
+    """Remove ~/.caw/auth/. Host credential files are untouched.
+
+    Refuses to run if host credentials are still symlinks into the auth
+    directory (leftover from the old symlink-based design). Use `--force`
+    to override — but you will have to re-authenticate every agent.
+    """
+    from . import TeardownWouldOrphanSymlinksError, teardown as do_teardown
+    from .collector import default_auth_dir
+
+    auth_dir = default_auth_dir()
+
+    if dry_run:
+        if auth_dir.exists():
+            typer.echo(f"Would remove: {auth_dir}")
+        else:
+            typer.echo(f"Nothing to remove: {auth_dir} does not exist.")
+        return
+
+    if not auth_dir.exists():
+        typer.echo(f"Nothing to remove: {auth_dir} does not exist.")
+        return
+
+    try:
+        do_teardown(force=force)
+    except TeardownWouldOrphanSymlinksError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(1)
+    typer.echo(f"Removed {auth_dir}.")
+
+
+@app.command("status")
+def status_cmd(
+    agents: Annotated[
+        Optional[list[str]],
+        typer.Option("--agents", "-a", help="Agents to show"),
+    ] = None,
+):
+    """Show token expiry, last modified, and docker mount flags."""
+    from .status import status as do_status
+
+    do_status(agents=agents)
+
+
+@app.command("docker-flags")
+def docker_flags():
+    """Output the -v flags for docker (one per bind mount, space-separated)."""
+    from .status import get_docker_flags as do_get_docker_flags
+
+    try:
+        typer.echo(do_get_docker_flags())
+    except FileNotFoundError:
+        typer.echo("Error: manifest.json not found. Run `caw auth setup` first.", err=True)
+        raise typer.Exit(1)

{coding_agent_wrapper-0.1.0 → coding_agent_wrapper-0.1.2}/caw/auth/collector.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import textwrap
 from pathlib import Path
 
@@ -12,8 +13,27 @@ from .providers import PROVIDERS, AgentAuthProvider, CollectedFile
 
 console = Console()
 
-# Canonical auth directory
-AUTH_DIR = Path.home() / ".caw" / "auth"
+
+def default_auth_dir() -> Path:
+    """Return the default auth directory, honoring the ``CAW_AUTH_DIR`` env var.
+
+    Set ``CAW_AUTH_DIR`` (e.g. by an embedding tool that wants caw's state to
+    live inside its own home) to relocate the staging dir. Falls back to
+    ``~/.caw/auth/``. Resolved on every call so the override can be set after
+    import.
+    """
+    override = os.environ.get("CAW_AUTH_DIR")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".caw" / "auth"
+
+
+def __getattr__(name: str):
+    # Module-level dynamic AUTH_DIR so `from caw.auth.collector import AUTH_DIR`
+    # picks up the current env var at access time.
+    if name == "AUTH_DIR":
+        return default_auth_dir()
+    raise AttributeError(name)
 
 
 def _resolve_providers(agent_names: list[str]) -> list[AgentAuthProvider]:
@@ -84,11 +104,19 @@ def _generate_setup_container_sh(manifest: Manifest) -> str:
             target_dir=$(dirname "$target_path")
             mkdir -p "$target_dir"
 
-            if [ "$strategy" = "symlink" ]; then
-                # Credential files: copy (not symlink) so container user can read 0600 files.
-                # The bind-mounted source is owned by the host UID and is 0600, but the
-                # setup script runs as root so it can read it.  We copy into the container
-                # user's home and record the pair for the inotify guard.
+            if [ "$strategy" = "bind" ]; then
+                # Credential files are bind-mounted from the host directly into
+                # $MOUNT_POINT.  The setup script runs as root so it can read the
+                # host-owned 0600 file; we copy it into the container user's home
+                # (chowned to the container user) and start an inotify guard to
+                # keep the two in sync.  Writes from the guard use plain `cp`,
+                # which preserves the host inode's uid/gid/mode on the mount side.
+                if [ ! -s "$source_path" ]; then
+                    echo "[setup-container] ERROR: $source_path is empty or missing."
+                    echo "[setup-container] Did you forget the credential file mount for $src?"
+                    echo "[setup-container] Use \`caw auth docker-flags\` to get the full flag list."
+                    exit 1
+                fi
                 rm -f "$target_path"
                 cp "$source_path" "$target_path"
                 chmod "$mode" "$target_path"
@@ -204,22 +232,24 @@ def _generate_setup_container_sh(manifest: Manifest) -> str:
 def setup(
     agents: list[str] | None = None,
     source_home: str | None = None,
-    force: bool = False,
     dest_dir: str | Path | None = None,
 ) -> Path:
-    """Collect credentials from host into an auth directory and link them.
+    """Snapshot credentials and cleaned configs into an auth directory.
+
+    Host credential files are read but not modified. At container run time
+    they are bind-mounted into the same paths under the mount point — see
+    :func:`caw.auth.get_docker_flags`.
 
     Args:
         agents: List of agent names, or None / ["all"] for all agents.
         source_home: Home directory to read credentials from.
-        force: Overwrite existing auth dir without prompting.
         dest_dir: Custom destination directory. Defaults to ~/.caw/auth/.
 
     Returns:
         Path to the auth directory.
     """
     src_home = Path(source_home) if source_home else Path.home()
-    auth_dir = Path(dest_dir) if dest_dir else AUTH_DIR
+    auth_dir = Path(dest_dir) if dest_dir else default_auth_dir()
 
     console.print(f"[bold]Collecting credentials into {auth_dir}/[/bold]\n")
 
@@ -268,22 +298,8 @@ def setup(
     if auth_dir.exists():
         import shutil
 
-        # Preserve .backups directory across re-collections
-        backups = auth_dir / ".backups"
-        backup_tmp = None
-        if backups.exists():
-            backup_tmp = auth_dir.parent / ".backups_tmp"
-            if backup_tmp.exists():
-                shutil.rmtree(backup_tmp)
-            backups.rename(backup_tmp)
-
         shutil.rmtree(auth_dir)
-        auth_dir.mkdir(parents=True)
-
-        if backup_tmp and backup_tmp.exists():
-            backup_tmp.rename(auth_dir / ".backups")
-    else:
-        auth_dir.mkdir(parents=True)
+    auth_dir.mkdir(parents=True)
 
     # Write collected files
     for cf in all_files:
@@ -314,11 +330,10 @@ def setup(
         console.print(f"  [dim]{cf.manifest_file.src}[/dim]  ({ftype}, {strategy})")
     console.print("  [dim]manifest.json[/dim]")
     console.print("  [dim]setup-container.sh[/dim]")
-
-    # Link credential files
-    console.print()
-    from .linker import link as do_link
-
-    do_link(agents=agents, force=force, auth_dir=auth_dir)
+    console.print(
+        "\n[dim]Host credential files are untouched; they will be bind-mounted "
+        "into the container at run time. Use `caw auth docker-flags` to get the "
+        "full -v flag list.[/dim]"
+    )
 
     return auth_dir

{coding_agent_wrapper-0.1.0 → coding_agent_wrapper-0.1.2}/caw/auth/manifest.py

@@ -16,7 +16,7 @@ class ManifestFile:
     container_target: str  # relative to $HOME in container, e.g. ".claude/.credentials.json"
     host_original: str  # relative to $HOME on host, e.g. ".claude/.credentials.json"
     type: str  # "credential" or "config"
-    strategy: str  # "symlink" or "copy"
+    strategy: str  # "bind" (bind-mounted from host, copy+guard in container) or "copy"
     mode: str  # e.g. "0600"