devctk 0.1.0__tar.gz → 0.2.0__tar.gz

devctk-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

devctk-0.2.0/DESIGN.md

@@ -0,0 +1,95 @@
+# devctk
+
+One-command rootless Podman dev containers, managed by systemd user services.
+
+```
+devctk init --image ubuntu:24.04
+devctk init --image ubuntu:24.04 --ssh --authorized-keys-file ~/.ssh/authorized_keys
+devctk init --image alpine:latest --nix --agent claude --mirror --workspace ~/projects/myapp
+```
+
+You get: a running container with your UID mapped in, workspace bind-mounted, passwordless sudo, auto-start via systemd, and optionally SSH + Nix tools + agent configs.
+
+## Distribution
+
+- PyPI package, runnable via `uvx devctk`
+- Pure Python, minimum 3.11
+
+## Host Requirements
+
+Podman (rootless), systemd, loginctl. Refuses to run as root.
+
+## Commands
+
+**`init`** (default) — create and start a dev container.
+
+- `--image` (required)
+- `--name` (default `<user>-dev`)
+- `--ssh` — enable SSH access (requires `--authorized-keys` or `--authorized-keys-file`)
+- `--port` (default 39000, requires `--ssh`)
+- `--nix` — mount Nix store + profiles, set PATH
+- `--agent claude|codex` (repeatable) — mount agent config dirs
+- `--mirror` — workspace at same absolute path as host
+- `--workspace PATH` (default `~/devctk/<name>`)
+- `--no-workspace` — skip workspace mount
+- `--mount`, `--device` (repeatable), extra podman flags after `--`
+
+**`ls`** — list managed containers with status.
+
+**`rm [NAME] [--all]`** — stop and remove container, units, and state.
+
+## What `init` Does
+
+1. Write a bootstrap script (container entrypoint) to the state dir
+2. Create rootless Podman container (`--userns keep-id`, `--init`, bootstrap as entrypoint)
+3. Bootstrap runs on every container start (idempotent):
+   - Detect package manager (apt/apk), install sudo + bash if missing
+   - Create user matching host UID/GID with passwordless sudo
+   - If `--nix`: write `/etc/profile.d/99-devctk-nix.sh`
+   - If `--ssh`: install sshd, configure key-only auth, write sshd config
+   - Signal readiness via `/run/devctk-ready`, then exec `sleep infinity`
+4. Install systemd user unit for the container
+5. If `--ssh`: install a second unit for sshd (waits for bootstrap readiness)
+6. Enable and start
+
+## Features
+
+### SSH (`--ssh`)
+
+SSH access via `ssh user@localhost -p PORT`. Requires authorized keys. Installs sshd inside the container, binds to 127.0.0.1 only. Managed by a separate systemd unit that depends on the container unit.
+
+Without `--ssh`, access the container via `podman exec -it NAME bash`.
+
+### Nix (`--nix`)
+
+Mounts `/nix/store`, `/etc/profiles/per-user/<user>`, and `/run/current-system` read-only. Uses unresolved symlink-tree paths (not `.resolve()`) so mounts survive `nixos-rebuild` + garbage collection. Writes PATH to `/etc/profile.d/` for SSH login shells.
+
+### Agent configs (`--agent claude|codex`)
+
+Mounts agent config directories into the container user's home (read-write):
+- `--agent claude`: `~/.claude/` + `~/.claude.json`
+- `--agent codex`: `~/.codex/`
+
+No preprocessing — mount as-is. Container detection for scripts: check `/run/.containerenv` (podman auto-creates this).
+
+### Mirror mode (`--mirror`)
+
+Mounts workspace at the same absolute path in host and container. Enables agent session continuity (e.g., Claude's project history is keyed by absolute path). Refuses to mount `$HOME` itself. Default workspace in mirror mode: current directory.
+
+## File Layout
+
+```
+~/.config/systemd/user/<name>.service[, <name>-sshd.service]
+~/.local/state/devctk/<name>.json, <name>-container.sh, <name>-bootstrap.sh[, <name>-sshd.sh]
+```
+
+## Supported Images
+
+Debian/Ubuntu (apt) and Alpine (apk). Other images work if sshd + sudo are pre-installed.
+
+## Constraints
+
+- Rootless only (no root)
+- SSH bound to 127.0.0.1 (when enabled)
+- Container user is always the host user (same name, UID, GID)
+- One-shot CLI; systemd handles lifecycle

{devctk-0.1.0 → devctk-0.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: devctk
-Version: 0.1.0
-Summary: One-command SSH-accessible rootless Podman dev containers
+Version: 0.2.0
+Summary: One-command rootless Podman dev containers with Nix and agent support
 Author: y
 License-Expression: MIT
 Classifier: Environment :: Console
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Topic :: Software Development
-Requires-Python: >=3.10
+Requires-Python: >=3.11

{devctk-0.1.0 → devctk-0.2.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devctk"
-version = "0.1.0"
-description = "One-command SSH-accessible rootless Podman dev containers"
-requires-python = ">=3.10"
+version = "0.2.0"
+description = "One-command rootless Podman dev containers with Nix and agent support"
+requires-python = ">=3.11"
 license = "MIT"
 authors = [{ name = "y" }]
 classifiers = [
@@ -16,10 +16,10 @@ classifiers = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/z_ctk"]
+packages = ["src/devctk"]
 
 [dependency-groups]
 dev = ["pytest"]
 
 [project.scripts]
-devctk = "z_ctk.cli:main"
+devctk = "devctk.cli:main"

devctk-0.2.0/src/devctk/__init__.py

@@ -0,0 +1,3 @@
+"""devctk: one-command rootless Podman dev containers."""
+
+__version__ = "0.2.0"

devctk-0.2.0/src/devctk/__main__.py

@@ -0,0 +1,3 @@
+from devctk.cli import main
+
+raise SystemExit(main())

devctk-0.2.0/src/devctk/agent.py

@@ -0,0 +1,38 @@
+"""Agent config dir mounting for Claude Code and Codex."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+HOME = Path.home()
+
+AGENTS: dict[str, dict] = {
+    "claude": {
+        "dirs": [HOME / ".claude"],
+        "files": [HOME / ".claude.json"],
+    },
+    "codex": {
+        "dirs": [HOME / ".codex"],
+        "files": [],
+    },
+}
+
+
+def agent_mounts(agents: list[str], container_home: str) -> list[tuple[str, str, str]]:
+    """Return (host_path, container_path, mode) tuples for agent config mounts.
+
+    Directories are created on the host if missing (so bind mounts work).
+    Files are skipped if they don't exist yet (agent creates them on first run).
+    """
+    mounts: list[tuple[str, str, str]] = []
+    for name in agents:
+        spec = AGENTS.get(name)
+        if not spec:
+            continue
+        for d in spec["dirs"]:
+            d.mkdir(parents=True, exist_ok=True)
+            mounts.append((str(d), f"{container_home}/{d.name}", "rw"))
+        for f in spec["files"]:
+            if f.is_file():
+                mounts.append((str(f), f"{container_home}/{f.name}", "rw"))
+    return mounts

{devctk-0.1.0/src/z_ctk → devctk-0.2.0/src/devctk}/cli.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import argparse
 import os
-import pathlib
 import re
 import sys
 
@@ -12,8 +11,8 @@ COMMANDS = {"init", "ls", "rm"}
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        prog="z-ctk",
-        description="One-command SSH-accessible rootless Podman dev containers.",
+        prog="devctk",
+        description="One-command rootless Podman dev containers.",
     )
     sub = parser.add_subparsers(dest="command")
     sub.required = True
@@ -21,14 +20,27 @@ def build_parser() -> argparse.ArgumentParser:
     # --- init ---
     p_init = sub.add_parser("init", help="Create and enable a dev container.")
     p_init.add_argument("--image", required=True)
+    p_init.add_argument("--name", dest="container_name")
+
+    # SSH (opt-in)
+    p_init.add_argument("--ssh", action="store_true", help="Enable SSH access")
     p_init.add_argument("--port", type=int, default=39000)
-    keys = p_init.add_mutually_exclusive_group(required=True)
+    keys = p_init.add_mutually_exclusive_group()
     keys.add_argument("--authorized-keys", dest="authorized_keys_text")
     keys.add_argument("--authorized-keys-file", dest="authorized_keys_file")
-    p_init.add_argument("--container-name")
-    p_init.add_argument("--container-user")
+
+    # Features
+    p_init.add_argument("--nix", action="store_true", help="Mount Nix store and set PATH")
+    p_init.add_argument("--agent", action="append", default=[], choices=["claude", "codex"],
+                        help="Mount agent config dirs (repeatable)")
+
+    # Workspace
     p_init.add_argument("--workspace")
     p_init.add_argument("--no-workspace", action="store_true")
+    p_init.add_argument("--mirror", action="store_true",
+                        help="Mount workspace at same absolute path as host")
+
+    # Extra podman flags
     p_init.add_argument("--mount", action="append", default=[])
     p_init.add_argument("--device", action="append", default=[])
 
@@ -44,7 +56,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def normalize_argv(argv: list[str]) -> list[str]:
-    """Treat bare args (no subcommand) as `init`."""
+    """Treat bare args (no subcommand) as ``init``."""
     if not argv:
         return argv
     if argv[0] in COMMANDS or argv[0] in {"-h", "--help"}:
@@ -75,7 +87,7 @@ def validate_passthrough(args: list[str]) -> None:
 
 
 def main() -> int:
-    from z_ctk.commands import cmd_init, cmd_ls, cmd_rm
+    from devctk.commands import cmd_init, cmd_ls, cmd_rm
 
     if os.geteuid() == 0:
         raise SystemExit("refuse to run as root")
@@ -87,9 +99,26 @@ def main() -> int:
 
     if args.command == "init":
         validate_passthrough(passthrough)
+
+        # SSH flag dependencies
+        if args.ssh:
+            if not args.authorized_keys_text and not args.authorized_keys_file:
+                raise SystemExit("--ssh requires --authorized-keys or --authorized-keys-file")
+        else:
+            if args.authorized_keys_text or args.authorized_keys_file:
+                raise SystemExit("--authorized-keys requires --ssh")
+
+        # Workspace conflicts
+        if args.no_workspace and args.workspace:
+            raise SystemExit("--workspace and --no-workspace conflict")
+        if args.no_workspace and args.mirror:
+            raise SystemExit("--mirror and --no-workspace conflict")
+
         return cmd_init(args, passthrough)
+
     if args.command == "ls":
         return cmd_ls()
+
     if args.command == "rm":
         return cmd_rm(args)
 

devctk-0.2.0/src/devctk/commands.py

@@ -0,0 +1,354 @@
+"""Command implementations: init, ls, rm."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import stat
+import sys
+
+from devctk.paths import ManagedPaths, managed_paths, state_root, STATE_DIR_NAME
+from devctk.helpers import render_bootstrap, render_container_helper, render_sshd_helper
+from devctk.systemd import render_unit
+from devctk.util import require_binary, run, write_text, unlink_if_exists
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+def resolve_authorized_keys(args: argparse.Namespace) -> tuple[pathlib.Path | None, str | None]:
+    """Return (file_path | None, text | None)."""
+    if args.authorized_keys_file is not None:
+        p = pathlib.Path(args.authorized_keys_file).expanduser().resolve()
+        if not p.is_file():
+            raise SystemExit(f"authorized_keys file not found: {p}")
+        if p.stat().st_size == 0:
+            raise SystemExit(f"authorized_keys file is empty: {p}")
+        return p, None
+    text = args.authorized_keys_text
+    if not text or not text.strip():
+        raise SystemExit("authorized_keys text is empty")
+    return None, text
+
+
+def build_workspace_mount(
+    workspace: str | None,
+    mirror: bool,
+    user: str,
+    container_name: str,
+    container_home: str,
+) -> str:
+    """Return a podman ``--mount`` spec string for the workspace."""
+    if mirror:
+        src = pathlib.Path(workspace).expanduser().resolve() if workspace else pathlib.Path.cwd().resolve()
+        if src == pathlib.Path.home():
+            raise SystemExit("--mirror: refusing to mount entire home directory")
+        src.mkdir(parents=True, exist_ok=True)
+        return f"type=bind,src={src},target={src},rw"
+
+    if workspace:
+        src = pathlib.Path(workspace).expanduser().resolve()
+    else:
+        src = pathlib.Path.home() / "devctk" / container_name
+    src.mkdir(parents=True, exist_ok=True)
+    return f"type=bind,src={src},target={container_home}/workspace,rw"
+
+
+def cmd_init(args: argparse.Namespace, passthrough: list[str]) -> int:
+    from devctk.cli import NAME_RE
+
+    user = os.environ.get("USER") or pathlib.Path.home().name
+    container_name = args.container_name or f"{user}-dev"
+    container_home = f"/home/{user}"
+    uid = os.getuid()
+    gid = os.getgid()
+
+    if not NAME_RE.match(container_name):
+        raise SystemExit(f"invalid container name: {container_name}")
+    if args.ssh and not 1 <= args.port <= 65535:
+        raise SystemExit(f"invalid port: {args.port}")
+
+    # Authorized keys
+    ak_file: pathlib.Path | None = None
+    ak_text: str | None = None
+    if args.ssh:
+        ak_file, ak_text = resolve_authorized_keys(args)
+
+    # Workspace
+    workspace_mount: str | None = None
+    if not args.no_workspace:
+        workspace_mount = build_workspace_mount(
+            args.workspace, args.mirror, user, container_name, container_home,
+        )
+
+    # --- Collect all container mounts ---
+    container_mounts: list[str] = []
+
+    # Workspace (first — it's the outermost bind under $HOME)
+    if workspace_mount:
+        container_mounts.append(workspace_mount)
+
+    # Nix
+    nix_profile_content = ""
+    if args.nix:
+        from devctk.nix import nix_mounts, nix_profile_script
+        for host, target, mode in nix_mounts(user):
+            container_mounts.append(f"type=bind,src={host},target={target},{mode}")
+        nix_profile_content = nix_profile_script(user)
+
+    # Agent config dirs
+    if args.agent:
+        from devctk.agent import agent_mounts
+        for host, target, mode in agent_mounts(args.agent, container_home):
+            container_mounts.append(f"type=bind,src={host},target={target},{mode}")
+
+    # User extra mounts
+    container_mounts.extend(args.mount)
+
+    # --- Binaries ---
+    podman = require_binary("podman")
+    systemctl = require_binary("systemctl")
+    loginctl = require_binary("loginctl")
+
+    # --- Conflict checks ---
+    if run([podman, "container", "exists", container_name], check=False).returncode == 0:
+        raise SystemExit(f"container already exists: {container_name}")
+
+    paths = managed_paths(container_name)
+    managed = [paths.container_unit, paths.container_helper, paths.bootstrap_helper, paths.metadata]
+    if args.ssh:
+        managed.extend([paths.sshd_unit, paths.sshd_helper])
+    for p in managed:
+        if p.exists():
+            raise SystemExit(f"managed files already exist for {container_name}")
+
+    # --- Write bootstrap script (container entrypoint) ---
+    write_text(
+        paths.bootstrap_helper,
+        render_bootstrap(
+            user=user,
+            uid=uid,
+            gid=gid,
+            home=container_home,
+            ssh=args.ssh,
+            nix_profile=nix_profile_content,
+            authorized_keys_file="/tmp/devctk-authorized-keys" if ak_file else None,
+            authorized_keys_text=ak_text,
+        ),
+        0o755,
+    )
+
+    # --- Internal mounts (bootstrap script + optional authorized-keys file) ---
+    internal_mounts = [
+        f"type=bind,src={paths.bootstrap_helper},target=/devctk-bootstrap.sh,ro",
+    ]
+    if ak_file:
+        internal_mounts.append(f"type=bind,src={ak_file},target=/tmp/devctk-authorized-keys,ro")
+
+    all_mounts = internal_mounts + container_mounts
+
+    # --- Write container helper ---
+    write_text(
+        paths.container_helper,
+        render_container_helper(
+            podman=podman,
+            name=container_name,
+            image=args.image,
+            mounts=all_mounts,
+            devices=args.device,
+            extra=passthrough,
+            ssh_port=args.port if args.ssh else None,
+        ),
+        stat.S_IRWXU,
+    )
+
+    # --- Write container unit ---
+    write_text(
+        paths.container_unit,
+        render_unit(
+            "container",
+            container_name=container_name,
+            container_helper=str(paths.container_helper),
+        ),
+    )
+
+    # --- SSH-specific files ---
+    if args.ssh:
+        write_text(
+            paths.sshd_helper,
+            render_sshd_helper(podman=podman, name=container_name),
+            stat.S_IRWXU,
+        )
+        write_text(
+            paths.sshd_unit,
+            render_unit(
+                "sshd",
+                container_name=container_name,
+                container_unit=paths.container_unit.name,
+                sshd_helper=str(paths.sshd_helper),
+            ),
+        )
+
+    # --- Metadata ---
+    write_text(paths.metadata, json.dumps({
+        "container_name": container_name,
+        "image": args.image,
+        "ssh": args.ssh,
+        "port": args.port if args.ssh else None,
+        "container_home": container_home,
+        "workspace_mount": workspace_mount or "",
+        "mirror": args.mirror,
+        "nix": args.nix,
+        "agents": args.agent,
+    }, indent=2, sort_keys=True) + "\n")
+
+    # --- Enable and start ---
+    try:
+        run([systemctl, "--user", "daemon-reload"])
+        run([systemctl, "--user", "enable", "--now", paths.container_unit.name])
+        if args.ssh:
+            run([systemctl, "--user", "enable", "--now", paths.sshd_unit.name])
+    except Exception:
+        print(f"startup failed, cleaning up {container_name}", file=sys.stderr)
+        _cleanup(podman, systemctl, paths, container_name)
+        raise
+
+    # --- Success ---
+    print(f"started {container_name}")
+    if args.ssh:
+        print(f"  ssh {user}@localhost -p {args.port}")
+    print(f"  podman exec -it {container_name} bash")
+
+    # Linger check
+    res = run([loginctl, "show-user", user, "-p", "Linger"], check=False, capture=True)
+    if res.returncode == 0 and res.stdout.strip().endswith("no"):
+        print(f"  hint: sudo loginctl enable-linger {user}", file=sys.stderr)
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# ls
+# ---------------------------------------------------------------------------
+
+def cmd_ls() -> int:
+    names = list_names()
+    if not names:
+        print("no devctk containers")
+        return 0
+
+    podman = require_binary("podman")
+
+    for name in names:
+        paths = managed_paths(name)
+        meta = _read_meta(paths.metadata)
+        parts = [
+            name,
+            f"podman={_container_status(podman, name)}",
+            f"image={meta.get('image', '-')}",
+        ]
+        if meta.get("ssh"):
+            parts.append(f"port={meta.get('port', '-')}")
+        if meta.get("nix"):
+            parts.append("nix")
+        agents = meta.get("agents", [])
+        if agents:
+            parts.append(f"agents={','.join(agents)}")
+        if meta.get("mirror"):
+            parts.append("mirror")
+        print("  ".join(parts))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# rm
+# ---------------------------------------------------------------------------
+
+def cmd_rm(args: argparse.Namespace) -> int:
+    user = os.environ.get("USER") or pathlib.Path.home().name
+
+    if args.all and args.container_name:
+        raise SystemExit("rm accepts either a name or --all, not both")
+
+    if args.all:
+        names = list_names()
+        if not names:
+            print("no devctk containers")
+            return 0
+    else:
+        names = [args.container_name or f"{user}-dev"]
+
+    podman = require_binary("podman")
+    systemctl = require_binary("systemctl")
+
+    for name in names:
+        paths = managed_paths(name)
+        all_paths = [
+            paths.metadata, paths.container_helper, paths.bootstrap_helper,
+            paths.sshd_helper, paths.container_unit, paths.sshd_unit,
+        ]
+        exists = any(p.exists() for p in all_paths)
+        exists = exists or run([podman, "container", "exists", name], check=False).returncode == 0
+
+        if not exists:
+            if args.all:
+                continue
+            raise SystemExit(f"not found: {name}")
+
+        _cleanup(podman, systemctl, paths, name)
+        print(f"removed {name}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+def _cleanup(podman: str, systemctl: str, paths: ManagedPaths, name: str) -> None:
+    """Stop services, remove container, delete managed files."""
+    run([systemctl, "--user", "disable", "--now", paths.sshd_unit.name], check=False, capture=True)
+    run([systemctl, "--user", "disable", "--now", paths.container_unit.name], check=False, capture=True)
+    res = run([podman, "rm", "-f", "--ignore", name], check=False, capture=True)
+    if res.returncode != 0:
+        print(f"warning: podman rm failed for {name}: {res.stderr.strip()}", file=sys.stderr)
+
+    for p in [paths.container_unit, paths.sshd_unit, paths.sshd_helper,
+              paths.container_helper, paths.bootstrap_helper, paths.metadata]:
+        unlink_if_exists(p)
+
+    if paths.helper_dir.exists() and not any(paths.helper_dir.iterdir()):
+        paths.helper_dir.rmdir()
+
+    run([systemctl, "--user", "daemon-reload"], check=False)
+
+
+def list_names() -> list[str]:
+    d = state_root() / STATE_DIR_NAME
+    if not d.exists():
+        return []
+    names: set[str] = set()
+    for p in d.glob("*.json"):
+        names.add(p.stem)
+    for p in d.glob("*-container.sh"):
+        names.add(p.name.removesuffix("-container.sh"))
+    for p in d.glob("*-bootstrap.sh"):
+        names.add(p.name.removesuffix("-bootstrap.sh"))
+    return sorted(names)
+
+
+def _read_meta(path: pathlib.Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return {}
+
+
+def _container_status(podman: str, name: str) -> str:
+    res = run([podman, "inspect", "-f", "{{.State.Status}}", name], check=False, capture=True)
+    return res.stdout.strip() if res.returncode == 0 else "missing"