agent-worktree-manager 0.2.0__py3-none-any.whl

agent_worktree_manager/__init__.py

@@ -0,0 +1,3 @@
+"""Portable, project-owned worktree environments."""
+
+__version__ = "0.2.0"

agent_worktree_manager/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agent_worktree_manager.cli import main
+
+sys.exit(main())

agent_worktree_manager/agent_skill.py

@@ -0,0 +1,49 @@
+"""Export the bundled, agent-independent worktree skill."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from importlib.resources import files
+from pathlib import Path
+
+from .errors import AWMError
+
+SKILL_FILES = ("SKILL.md", "agents/openai.yaml")
+
+
+def bundled_files() -> dict[str, bytes]:
+    root = files("agent_worktree_manager").joinpath("skills", "awm")
+    return {name: root.joinpath(*name.split("/")).read_bytes() for name in SKILL_FILES}
+
+
+def install_skill(destination: Path) -> Path:
+    destination = Path(os.path.abspath(destination.expanduser()))
+    content = bundled_files()
+    if destination.is_symlink():
+        raise AWMError(f"Skill destination must not be a symlink: {destination}")
+    if destination.exists():
+        if destination.is_dir() and all(
+            (destination / name).is_file()
+            and not (destination / name).is_symlink()
+            and (destination / name).read_bytes() == value
+            for name, value in content.items()
+        ):
+            return destination
+        raise AWMError(
+            f"Skill destination already exists with different contents: {destination}; "
+            "review or move the existing skill before installing"
+        )
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = Path(tempfile.mkdtemp(prefix=".awm-skill-", dir=destination.parent))
+    try:
+        for name, value in content.items():
+            path = temporary / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(value)
+        temporary.rename(destination)
+    finally:
+        if temporary.exists():
+            shutil.rmtree(temporary)
+    return destination

agent_worktree_manager/cli.py

@@ -0,0 +1,386 @@
+"""The installed awm entry point. Mutations belong to shared services."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import sys
+import threading
+from pathlib import Path
+
+from . import __version__, environments, lifecycle, migration, registry
+from .config import BACKENDS, initialize, load_project
+from .errors import AWMError
+from .git import check_repo, is_dirty
+
+
+def log(message: str) -> None:
+    print(f"[awm] {message}")
+
+
+def err(message: str) -> None:
+    print(f"[awm] ERROR: {message}", file=sys.stderr)
+
+
+def selected(opts):
+    return registry.select(root=getattr(opts, "root", None), project=getattr(opts, "project", None))
+
+
+def confirmation(message: str, yes: bool) -> bool:
+    if yes:
+        return True
+    if not sys.stdin.isatty():
+        raise AWMError("Non-interactive deletion/import requires --yes; use --dry-run to preview")
+    try:
+        return input(message + " [y/N] ").strip().lower() in ("y", "yes")
+    except (EOFError, KeyboardInterrupt):
+        return False
+
+
+def print_plan(project, record: dict) -> None:
+    log(f"{project.name}/{record['name']} ({record['status']})")
+    for worktree in record["worktrees"]:
+        print(
+            f"  worktree {worktree['alias']}[{worktree['branch'] or 'detached'}]  {worktree['path']}"
+        )
+    for env in record["environments"]:
+        print(f"  env {env['kind']}  {env['path']}")
+    for editable in record["editables"]:
+        print(
+            f"  editable {editable['name']} -> {editable['path']} ({'shared source' if editable['shared'] else 'isolated source'})"
+        )
+    if record.get("error"):
+        print(f"  error: {record['error']}")
+
+
+def project_overview() -> list[dict]:
+    output = []
+    for entry in registry.entries():
+        try:
+            project = load_project(Path(entry["root"]))
+            if project.id != entry["id"]:
+                raise AWMError("Project identity changed; re-register this location")
+            output.append(lifecycle.project_summary(project))
+        except (AWMError, OSError) as exc:
+            output.append({**entry, "unavailable": str(exc)})
+    return output
+
+
+def cmd_projects(opts) -> int:
+    if opts.action == "add":
+        project = load_project(Path(opts.path))
+        if not opts.dry_run:
+            registry.register(project)
+        log(f"{'Would register' if opts.dry_run else 'Registered'} {project.name}: {project.id}")
+    elif opts.action == "remove":
+        entry = registry.find(opts.selector)
+        if not opts.dry_run:
+            registry.unregister(opts.selector)
+        log(
+            f"{'Would unregister' if opts.dry_run else 'Unregistered'} {entry['name']}; project resources are preserved"
+        )
+    else:
+        items = project_overview()
+        if opts.json:
+            print(json.dumps({"schema_version": 1, "projects": items}, indent=2))
+        for item in [] if opts.json else items:
+            print(
+                f"{item['id']}  {item['name']}  {item.get('states', item.get('unavailable'))}  {item['root']}"
+            )
+    return 0
+
+
+def cmd_init(opts) -> int:
+    if getattr(opts, "project", None):
+        raise AWMError("init takes --root, not --project")
+    project = initialize(
+        Path(getattr(opts, "root", None) or "."),
+        Path(opts.base),
+        opts.backend,
+        opts.name,
+        opts.repo,
+        dry_run=opts.dry_run,
+    )
+    if project:
+        registry.register(project)
+        log(f"Initialized {project.name}: {project.id}")
+    else:
+        log("Initialization preflight passed; no files written")
+    return 0
+
+
+def cmd_create(opts) -> int:
+    project = selected(opts)
+    record = lifecycle.create(project, opts.name, opts.repo, opts.ref, dry_run=True)
+    print_plan(project, record)
+    if opts.dry_run:
+        log("Dry run; no resources created")
+    else:
+        log("Creating worktrees and reproducing the installed base…")
+        print_plan(project, lifecycle.create(project, opts.name, opts.repo, opts.ref))
+    return 0
+
+
+def cmd_import(opts) -> int:
+    project = selected(opts)
+    kwargs = dict(
+        legacy=opts.legacy,
+        venv_home=opts.venv_home,
+        base_env=opts.base_env,
+        conda_base_env=opts.conda_base_env,
+    )
+    record = migration.import_sandbox(
+        project, opts.name, opts.worktree, opts.env, dry_run=True, **kwargs
+    )
+    print_plan(project, record)
+    if opts.dry_run:
+        log("Dry run; ownership records unchanged")
+    elif confirmation("Adopt these resources for management by awm?", opts.yes):
+        migration.import_sandbox(project, opts.name, opts.worktree, opts.env, **kwargs)
+        log("Import complete")
+    else:
+        return 1
+    return 0
+
+
+def cmd_delete(opts) -> int:
+    project = selected(opts)
+    kwargs = dict(
+        force=opts.force,
+        keep_env=opts.keep_env,
+        keep_worktrees=opts.keep_worktrees,
+        delete_branch=opts.delete_branch,
+    )
+    records = lifecycle.delete(project, opts.names, dry_run=True, **kwargs)
+    for record in records:
+        print_plan(project, record)
+    log(
+        f"Delete worktrees: {not opts.keep_worktrees}; delete environments: {not opts.keep_env}; delete branches: {opts.delete_branch}; force: {opts.force}"
+    )
+    if opts.dry_run:
+        log("Dry run; nothing deleted")
+    elif confirmation(f"Delete selected resources in {project.name}?", opts.yes):
+        lifecycle.delete(project, opts.names, **kwargs)
+        log("Deletion complete")
+    else:
+        return 1
+    return 0
+
+
+def list_payload(project) -> dict:
+    records = []
+    for record in lifecycle.read_state(project)["sandboxes"].values():
+        summary = {
+            k: record[k]
+            for k in ("name", "status", "error", "worktrees", "environments", "editables")
+        }
+        summary["worktrees"] = []
+        for resource in record["worktrees"]:
+            path = Path(resource["path"])
+            try:
+                dirty = is_dirty(path) if path.exists() else None
+            except AWMError:
+                dirty = None
+            summary["worktrees"].append({**resource, "missing": not path.exists(), "dirty": dirty})
+        summary["environments"] = [
+            {**e, "missing": not Path(e["path"]).exists()} for e in record["environments"]
+        ]
+        records.append(summary)
+    return {"id": project.id, "name": project.name, "root": str(project.root), "sandboxes": records}
+
+
+def cmd_list(opts) -> int:
+    projects = []
+    if opts.all:
+        if getattr(opts, "root", None) or getattr(opts, "project", None):
+            raise AWMError("--all cannot be combined with a project selector")
+        for entry in registry.entries():
+            try:
+                projects.append(list_payload(registry.select(project=entry["id"])))
+            except (AWMError, OSError) as exc:
+                projects.append({**entry, "unavailable": str(exc)})
+    else:
+        projects = [list_payload(selected(opts))]
+    if opts.json:
+        print(json.dumps({"schema_version": 1, "projects": projects}, indent=2))
+    else:
+        for project in projects:
+            print(f"{project['name']} ({project['id']})  {project['root']}")
+            if "unavailable" in project:
+                print(f"  unavailable: {project['unavailable']}")
+            for record in project.get("sandboxes", []):
+                kinds = ", ".join(e["kind"] for e in record["environments"]) or "-"
+                worktrees = (
+                    ", ".join(
+                        f"{w['alias']}[{w['branch'] or 'detached'}]{'*' if w['dirty'] else ''}{' (missing)' if w['missing'] else ''}"
+                        for w in record["worktrees"]
+                    )
+                    or "-"
+                )
+                print(f"  {record['name']}  {record['status']}  {kinds}  {worktrees}")
+                if record["error"]:
+                    print(f"    {record['error']}")
+    return 0
+
+
+def cmd_doctor(opts) -> int:
+    project = selected(opts)
+    for repo in project.repos.values():
+        check_repo(repo.path)
+    base = environments.validate_base(project.base, project.backend)
+    lifecycle.read_state(project)
+    for package in base["packages"]:
+        path = environments.editable_path(package)
+        if path and not path.exists():
+            raise AWMError(f"Missing editable source: {path}")
+    log(
+        f"{project.name}: Git checkouts and {project.backend} base are valid; Python {base['python']}, {len(base['packages'])} packages"
+    )
+    for name, recorded, declared, source in environments.stale_editables(base):
+        log(
+            f"Stale editable metadata: {name} records {recorded}, {source} declares {declared}; "
+            f"reinstall it into the base to reproduce that version in new sandboxes"
+        )
+    return 0
+
+
+def cmd_run(opts) -> int:
+    command = opts.args[1:] if opts.args[:1] == ["--"] else opts.args
+    return lifecycle.run_command(selected(opts), opts.name, command, opts.repo, opts.env)
+
+
+def cmd_skill(opts) -> int:
+    from .agent_skill import bundled_files, install_skill
+
+    if opts.install:
+        log(f"Skill installed at {install_skill(Path(opts.install))}")
+    else:
+        print(bundled_files()["SKILL.md"].decode("utf-8"), end="")
+    return 0
+
+
+def cmd_shell_init(opts) -> int:
+    from .shell import shell_init
+
+    print(shell_init(opts.shell), end="")
+    return 0
+
+
+def cmd_ui(opts) -> int:
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        raise AWMError("Interactive mode requires a TTY; use 'awm projects list' or 'awm list'")
+    from .tui import run_ui
+
+    return run_ui(opts)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    selectors = argparse.ArgumentParser(add_help=False)
+    group = selectors.add_mutually_exclusive_group()
+    group.add_argument("--root", default=argparse.SUPPRESS, help="project root containing awm.toml")
+    group.add_argument("--project", default=argparse.SUPPRESS, help="registered project name or ID")
+    parser = argparse.ArgumentParser(
+        prog="awm",
+        description="Manage project worktrees and isolated Python environments",
+        parents=[selectors],
+    )
+    parser.add_argument("--version", action="version", version=f"awm {__version__}")
+    parser.set_defaults(func=cmd_ui, envs=False)
+    commands = parser.add_subparsers(dest="command")
+    shell = commands.add_parser("shell-init", help="print current-shell integration for eval")
+    shell.add_argument("shell", choices=("bash", "zsh"))
+    shell.set_defaults(func=cmd_shell_init)
+    skill = commands.add_parser("skill", help="print or install the bundled coding-agent skill")
+    skill.add_argument("--install", metavar="PATH", help="copy the skill into this skill directory")
+    skill.set_defaults(func=cmd_skill)
+    init = commands.add_parser("init", parents=[selectors], help="configure and register a project")
+    init.add_argument("--base", required=True, help="existing base environment directory")
+    init.add_argument("--backend", choices=BACKENDS, default="venv")
+    init.add_argument("--name")
+    init.add_argument("--repo", action="append", default=[], metavar="ALIAS=PATH")
+    init.add_argument("--dry-run", action="store_true")
+    init.set_defaults(func=cmd_init)
+    create = commands.add_parser(
+        "create", parents=[selectors], help="create a sandbox from the installed base"
+    )
+    create.add_argument("name")
+    create.add_argument("--repo", action="append", default=[])
+    create.add_argument("--ref", default="HEAD")
+    create.add_argument("-n", "--dry-run", action="store_true")
+    create.set_defaults(func=cmd_create)
+    imp = commands.add_parser(
+        "import", parents=[selectors], help="explicitly adopt existing worktrees/environments"
+    )
+    imp.add_argument("name")
+    imp.add_argument("--worktree", action="append", default=[], metavar="ALIAS=PATH")
+    imp.add_argument("--env", action="append", default=[], metavar="BACKEND=PATH")
+    imp.add_argument("--legacy", action="store_true")
+    for flag in ("venv-home", "base-env", "conda-base-env"):
+        imp.add_argument(f"--{flag}")
+    imp.add_argument("-n", "--dry-run", action="store_true")
+    imp.add_argument("-y", "--yes", action="store_true")
+    imp.set_defaults(func=cmd_import)
+    delete = commands.add_parser(
+        "delete", parents=[selectors], help="delete owned sandbox resources"
+    )
+    delete.add_argument("names", nargs="+")
+    for short, long in (("-n", "--dry-run"), ("-y", "--yes"), ("-f", "--force")):
+        delete.add_argument(short, long, action="store_true")
+    for flag in ("keep-env", "keep-worktrees", "delete-branch"):
+        delete.add_argument(f"--{flag}", action="store_true")
+    delete.set_defaults(func=cmd_delete)
+    ls = commands.add_parser("list", parents=[selectors], help="list owned sandboxes")
+    ls.add_argument("--json", action="store_true")
+    ls.add_argument("--all", action="store_true")
+    ls.set_defaults(func=cmd_list)
+    doctor = commands.add_parser(
+        "doctor", parents=[selectors], help="check project prerequisites without changing them"
+    )
+    doctor.set_defaults(func=cmd_doctor)
+    run = commands.add_parser(
+        "run", parents=[selectors], help="run a command in a sandbox; options precede NAME"
+    )
+    run.add_argument("--repo")
+    run.add_argument("--env")
+    run.add_argument("name")
+    run.add_argument("args", nargs=argparse.REMAINDER)
+    run.set_defaults(func=cmd_run)
+    for command in ("ui", "envs"):
+        ui = commands.add_parser(command, parents=[selectors])
+        ui.add_argument("--envs", action="store_true", default=command == "envs")
+        ui.set_defaults(func=cmd_ui)
+    projects = commands.add_parser("projects", help="register or browse projects")
+    actions = projects.add_subparsers(dest="action", required=True)
+    for action in ("add", "remove", "list"):
+        p = actions.add_parser(action)
+        if action != "list":
+            p.add_argument("path" if action == "add" else "selector")
+            p.add_argument("--dry-run", action="store_true")
+        else:
+            p.add_argument("--json", action="store_true")
+        p.set_defaults(func=cmd_projects)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    previous = {}
+
+    def interrupted(signum, frame):
+        raise KeyboardInterrupt
+
+    if threading.current_thread() is threading.main_thread():
+        for signum in (signal.SIGTERM, signal.SIGHUP):
+            previous[signum] = signal.signal(signum, interrupted)
+    try:
+        opts = build_parser().parse_args(argv)
+        return opts.func(opts)
+    except (AWMError, OSError, ValueError) as exc:
+        err(str(exc))
+        return 1
+    except KeyboardInterrupt:
+        err("Interrupted")
+        return 130
+    finally:
+        for signum, handler in previous.items():
+            signal.signal(signum, handler)

agent_worktree_manager/config.py

@@ -0,0 +1,196 @@
+"""Portable workspace configuration and per-machine settings."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tomllib
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+
+from .errors import AWMError
+from .git import check_repo
+from .storage import atomic_text, lock
+
+CONFIG_NAME = "awm.toml"
+BACKENDS = ("venv", "uv", "conda")
+
+
+def slug(value: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,79}", value):
+        raise AWMError(
+            "Names must be 1–80 letters, digits, dots, underscores or dashes, starting with a letter or digit"
+        )
+    return value
+
+
+def read_toml(path: Path) -> dict:
+    try:
+        value = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise AWMError(f"Cannot read {path}: {exc}") from exc
+    if value.get("schema_version") != 1:
+        raise AWMError(f"Unsupported configuration version: {path}")
+    return value
+
+
+def editable_target(target: str) -> tuple[str, tuple[str, ...]]:
+    subdir, separator, suffix = target.partition("[")
+    if not subdir or Path(subdir).is_absolute() or ".." in Path(subdir).parts:
+        raise ValueError(f"editable target must stay inside its repository: {target}")
+    if not separator:
+        return subdir, ()
+    requirement = Requirement("editable-target[" + suffix)
+    if not target.endswith("]") or requirement.marker or requirement.specifier or requirement.url:
+        raise ValueError(f"invalid editable target extras: {target}")
+    return subdir, tuple(sorted(canonicalize_name(extra) for extra in requirement.extras))
+
+
+@dataclass(frozen=True)
+class Repository:
+    alias: str
+    path: Path
+    targets: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Project:
+    root: Path
+    id: str
+    name: str
+    backend: str
+    base: Path
+    repos: dict[str, Repository]
+
+    @property
+    def local(self) -> Path:
+        path = self.root / ".awm"
+        if path.is_symlink():
+            raise AWMError(f"Project state directory must not be a symlink: {path}")
+        return path
+
+
+def load_project(root: Path) -> Project:
+    root = root.expanduser().resolve()
+    if root.name == CONFIG_NAME and root.is_file():
+        root = root.parent
+    shared = read_toml(root / CONFIG_NAME)
+    if (root / ".awm").is_symlink():
+        raise AWMError("Project state directory must not be a symlink")
+    local = read_toml(root / ".awm" / "local.toml")
+    return parse_project(root, shared, local)
+
+
+def parse_project(root: Path, shared: dict, local: dict) -> Project:
+    try:
+        project_id = str(uuid.UUID(local["project_id"]))
+        name = shared["name"]
+        environment = local["environment"]
+        backend, base = environment["backend"], environment["base"]
+        if (
+            not isinstance(name, str)
+            or not name.strip()
+            or backend not in BACKENDS
+            or not isinstance(base, str)
+        ):
+            raise ValueError("invalid project name or environment")
+        repos = {}
+        overrides = local.get("repositories", {})
+        if not isinstance(overrides, dict) or overrides.keys() - shared["repositories"].keys():
+            raise ValueError("local repository overrides must use configured aliases")
+        for alias, spec in shared["repositories"].items():
+            slug(alias)
+            spec = {**spec, **overrides.get(alias, {})}
+            targets = spec.get("targets", [])
+            if not isinstance(targets, list) or not all(isinstance(t, str) and t for t in targets):
+                raise ValueError(f"invalid editable targets for {alias}")
+            for target in targets:
+                editable_target(target)
+            repos[alias] = Repository(
+                alias, (root / Path(spec["path"]).expanduser()).resolve(), tuple(targets)
+            )
+        if not repos or len({r.path for r in repos.values()}) != len(repos):
+            raise ValueError("configure at least one repository, with distinct checkout paths")
+        return Project(
+            root, project_id, name, backend, (root / Path(base).expanduser()).resolve(), repos
+        )
+    except (KeyError, TypeError, ValueError, AttributeError) as exc:
+        raise AWMError(f"Invalid project configuration at {root}: {exc}") from exc
+
+
+def discover_root(cwd: Path | None = None) -> Path:
+    path = (cwd or Path.cwd()).resolve()
+    for candidate in (path, *path.parents):
+        if (candidate / CONFIG_NAME).is_file():
+            return candidate
+    raise AWMError(
+        "No project selected; use --project, --root, or run inside an initialized project"
+    )
+
+
+def initialize(
+    root: Path,
+    base: Path,
+    backend: str,
+    name: str | None,
+    repositories: list[str],
+    *,
+    dry_run: bool = False,
+) -> Project | None:
+    root, base = root.expanduser().resolve(), base.expanduser().resolve()
+    if not root.is_dir():
+        raise AWMError(f"Project directory does not exist: {root}")
+    if not (base / "bin" / "python").is_file():
+        raise AWMError(f"Base has no Python interpreter: {base}")
+    if backend == "conda" and not (base / "conda-meta").is_dir():
+        raise AWMError(f"Not a conda environment: {base}")
+    if backend != "conda" and not (base / "pyvenv.cfg").is_file():
+        raise AWMError(f"Select a dedicated venv base, or use --backend conda: {base}")
+    if (root / ".awm").is_symlink():
+        raise AWMError("Project state directory must not be a symlink")
+    shared_path = root / CONFIG_NAME
+    if shared_path.exists():
+        if repositories or name:
+            raise AWMError(
+                "Configuration already exists; edit awm.toml to change its name/repositories"
+            )
+        shared = read_toml(shared_path)
+        text = None
+    else:
+        entries = repositories or ["repo=."]
+        text = f"schema_version = 1\nname = {json.dumps(name or root.name)}\n"
+        seen = set()
+        for entry in entries:
+            alias, sep, value = entry.partition("=")
+            if not sep or not value or slug(alias) in seen:
+                raise AWMError("Repositories use unique ALIAS=PATH entries")
+            seen.add(alias)
+            path = (root / Path(value).expanduser()).resolve()
+            check_repo(path)
+            text += f"\n[repositories.{json.dumps(alias)}]\npath = {json.dumps(os.path.relpath(path, root))}\ntargets = []\n"
+    if (root / ".awm" / "local.toml").exists():
+        raise AWMError("Project is already initialized; edit .awm/local.toml to change its base")
+    local_text = (
+        f'schema_version = 1\nproject_id = "{uuid.uuid4()}"\n\n[environment]\n'
+        f"backend = {json.dumps(backend)}\nbase = {json.dumps(str(base))}\n"
+    )
+    candidate = parse_project(
+        root, tomllib.loads(text) if text is not None else shared, tomllib.loads(local_text)
+    )
+    for repo in candidate.repos.values():
+        check_repo(repo.path)
+    if dry_run:
+        return None
+    with lock(root / ".awm" / "operation.lock"):
+        if (root / ".awm" / "local.toml").exists():
+            raise AWMError("Project was initialized by another process")
+        atomic_text(root / ".awm" / ".gitignore", "*\n")
+        if text is not None:
+            atomic_text(shared_path, text)
+        atomic_text(root / ".awm" / "local.toml", local_text)
+    return load_project(root)