worktree-env 0.2.0__py3-none-any.whl

git_worktree_env/profiles.py

@@ -0,0 +1,215 @@
+"""Project-profile loading, validation, and worktree matching."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from string import Template
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import yaml
+
+from .paths import AppPaths
+from .utils import WteError, expand_home, run_git
+
+Profile = Dict[str, Any]
+PORT_ID = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def parse_profile(path: Path) -> Profile:
+    """Parse one YAML or JSON profile and attach its source path."""
+    try:
+        if path.suffix.lower() in (".yaml", ".yml"):
+            raw = yaml.safe_load(path.read_text()) or {}
+        else:
+            raw = json.loads(path.read_text() or "{}")
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        raise WteError(f"cannot parse profile {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise WteError(f"profile root must be a mapping: {path}")
+    raw["_file"] = str(path)
+    return raw
+
+
+def load_profiles(paths: AppPaths, strict: bool = True) -> List[Profile]:
+    """Load profiles, preferring YAML when files share the same stem."""
+    if not paths.profiles.is_dir():
+        return []
+    rank = {".yaml": 0, ".yml": 1, ".json": 2}
+    files: List[Path] = []
+    for pattern in ("*.yaml", "*.yml", "*.json"):
+        files.extend(paths.profiles.glob(pattern))
+    files = [path for path in files if path.resolve() != paths.config.resolve()]
+
+    profiles: List[Profile] = []
+    seen = set()
+    for path in sorted(files, key=lambda item: (item.stem, rank[item.suffix.lower()])):
+        if path.stem in seen:
+            continue
+        seen.add(path.stem)
+        try:
+            profile = parse_profile(path)
+        except WteError:
+            if strict:
+                raise
+            continue
+        if profile.get("name"):
+            profiles.append(profile)
+        elif strict:
+            raise WteError(f"profile has no name: {path}")
+    return profiles
+
+
+def worktree_root(cwd: Optional[Path] = None) -> Path:
+    """Return the root of the Git worktree containing ``cwd``."""
+    return Path(run_git("rev-parse", "--show-toplevel", cwd=cwd)).resolve()
+
+
+def main_worktree_root(root: Path) -> Path:
+    """Return the main worktree associated with ``root``.
+
+    Normal and linked worktrees share the main worktree's ``.git`` directory.
+    The porcelain listing is a fallback for repositories whose common Git
+    directory uses a non-standard location.
+    """
+    try:
+        common = Path(run_git("rev-parse", "--git-common-dir", cwd=root))
+    except WteError:
+        return root.resolve()
+    common = (root / common).resolve() if not common.is_absolute() else common.resolve()
+    if common.name == ".git":
+        return common.parent
+
+    try:
+        listing = run_git("worktree", "list", "--porcelain", cwd=root)
+        first = next(
+            line[len("worktree ") :]
+            for line in listing.splitlines()
+            if line.startswith("worktree ")
+        )
+        return Path(first).resolve()
+    except (WteError, StopIteration):
+        return root.resolve()
+
+
+def configured_main_worktree(profile: Profile) -> Optional[Path]:
+    """Return the normalized main-worktree path configured by a profile."""
+    match = profile.get("match") or {}
+    raw = match.get("main_worktree") if isinstance(match, dict) else None
+    if not raw:
+        return None
+    return expand_home(str(raw)).resolve()
+
+
+def find_profile(paths: AppPaths, root: Path) -> Optional[Profile]:
+    """Find the unique profile whose main worktree owns ``root``."""
+    actual = main_worktree_root(root)
+    hits = [
+        profile
+        for profile in load_profiles(paths)
+        if configured_main_worktree(profile) == actual
+    ]
+    if not hits:
+        return None
+    if len(hits) > 1:
+        sources = ", ".join(Path(item["_file"]).name for item in hits)
+        raise WteError(f"multiple profiles match main worktree {actual}: {sources}")
+    return hits[0]
+
+
+def _port_claims(profile: Profile) -> Sequence[Dict[str, Any]]:
+    raw = profile.get("ports") or profile.get("services") or []
+    return raw if isinstance(raw, list) else []
+
+
+def validate_profiles(paths: AppPaths) -> Tuple[List[str], List[str]]:
+    """Validate all profiles without requiring their worktrees to exist."""
+    errors: List[str] = []
+    warnings: List[str] = []
+    try:
+        profiles = load_profiles(paths)
+    except WteError as exc:
+        return [str(exc)], warnings
+
+    names: Dict[str, Path] = {}
+    main_roots: Dict[Path, Path] = {}
+    for profile in profiles:
+        source = Path(profile["_file"])
+        label = source.name
+        name = profile.get("name")
+        if not isinstance(name, str) or not name.strip():
+            errors.append(f"{label}: name must be a non-empty string")
+        elif name in names:
+            errors.append(f"{label}: duplicate profile name {name!r} (also in {names[name].name})")
+        else:
+            names[name] = source
+
+        match = profile.get("match") or {}
+        main_raw = match.get("main_worktree") if isinstance(match, dict) else None
+        main_root = configured_main_worktree(profile)
+        if main_root is None:
+            errors.append(f"{label}: match.main_worktree is required")
+        elif not expand_home(str(main_raw)).is_absolute():
+            errors.append(f"{label}: match.main_worktree must be an absolute or home-relative path")
+        elif main_root in main_roots:
+            errors.append(
+                f"{label}: main worktree is also configured by {main_roots[main_root].name}"
+            )
+        else:
+            main_roots[main_root] = source
+            if not main_root.exists():
+                warnings.append(f"{label}: main worktree does not exist: {main_root}")
+
+        claims = _port_claims(profile)
+        if not claims:
+            errors.append(f"{label}: ports must contain at least one claim")
+            continue
+        ids: List[str] = []
+        for index, claim in enumerate(claims):
+            port_id = claim.get("id") if isinstance(claim, dict) else None
+            if not isinstance(port_id, str) or not PORT_ID.match(port_id):
+                errors.append(f"{label}: ports[{index}].id is invalid")
+            elif port_id in ids:
+                errors.append(f"{label}: duplicate port id {port_id!r}")
+            else:
+                ids.append(port_id)
+
+        mapping = {port_id: "0" for port_id in ids}
+        writes = profile.get("writes") or []
+        if not isinstance(writes, list):
+            errors.append(f"{label}: writes must be a list")
+            continue
+        for index, spec in enumerate(writes):
+            if not isinstance(spec, dict):
+                errors.append(f"{label}: writes[{index}] must be a mapping")
+                continue
+            write_path = spec.get("path")
+            if not write_path:
+                errors.append(f"{label}: writes[{index}].path is required")
+            elif Path(str(write_path)).is_absolute() or ".." in Path(str(write_path)).parts:
+                errors.append(f"{label}: writes[{index}].path must stay inside the worktree")
+            try:
+                Template(str(spec.get("body") or "")).substitute(mapping)
+            except (KeyError, ValueError) as exc:
+                errors.append(f"{label}: writes[{index}].body has an invalid variable: {exc}")
+
+        secrets = profile.get("secrets") or []
+        if not isinstance(secrets, list):
+            errors.append(f"{label}: secrets must be a list")
+        else:
+            for index, entry in enumerate(secrets):
+                if not isinstance(entry, dict):
+                    errors.append(f"{label}: secrets[{index}] must be a mapping")
+                    continue
+                if not entry.get("source"):
+                    errors.append(f"{label}: secrets[{index}].source is required")
+                target = entry.get("target")
+                if not target:
+                    errors.append(f"{label}: secrets[{index}].target is required")
+                elif Path(str(target)).is_absolute() or ".." in Path(str(target)).parts:
+                    errors.append(f"{label}: secrets[{index}].target must stay inside the worktree")
+
+    if not profiles:
+        warnings.append(f"no profiles found in {paths.profiles}")
+    return errors, warnings

git_worktree_env/projector.py

@@ -0,0 +1,166 @@
+"""Projection of ports, local secrets, and setup commands into a worktree."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from string import Template
+from typing import Any, Dict, List, Optional
+
+from .config import load_port_pool
+from .paths import AppPaths
+from .profiles import Profile, find_profile
+from .registry import (
+    allocate_ports,
+    load_registry,
+    prune_registry,
+    registry_lock,
+    save_registry,
+)
+from .utils import WteError, expand_profile_path, log, safe_worktree_target
+
+@dataclass(frozen=True)
+class ApplyResult:
+    """Details of a successful profile projection."""
+
+    profile: str
+    root: Path
+    ports: Dict[str, int]
+
+
+def render_template(body: str, ports: Dict[str, int]) -> str:
+    """Replace profile port variables such as ``${frontend}``."""
+    try:
+        return Template(body).substitute({key: str(value) for key, value in ports.items()})
+    except (KeyError, ValueError) as exc:
+        raise WteError(f"cannot render port template: {exc}") from exc
+
+
+def _secret_entries(profile: Profile) -> List[Dict[str, Any]]:
+    raw = profile.get("secrets") or []
+    return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
+
+
+def apply_secrets(profile: Profile, root: Path) -> None:
+    """Replace configured targets with symlinks to existing local secret files."""
+    for entry in _secret_entries(profile):
+        source_raw = str(entry.get("source") or "").strip()
+        target_raw = str(entry.get("target") or "").strip()
+        if not source_raw or not target_raw:
+            continue
+        source = expand_profile_path(source_raw, profile).resolve()
+        target = safe_worktree_target(root, target_raw)
+        if not source.is_file():
+            log(f"secret skipped; source does not exist: {source}")
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.is_symlink() or target.exists():
+            if target.is_dir() and not target.is_symlink():
+                raise WteError(f"secret target is a directory: {target}")
+            target.unlink()
+        target.symlink_to(source)
+
+
+def apply_writes(profile: Profile, root: Path, ports: Dict[str, int]) -> None:
+    """Render complete generated files declared by the profile."""
+    writes = profile.get("writes") or []
+    if not isinstance(writes, list):
+        raise WteError(f"profile {profile.get('name')} has an invalid writes section")
+    for spec in writes:
+        if not isinstance(spec, dict) or not spec.get("path"):
+            raise WteError(f"profile {profile.get('name')} has an invalid write entry")
+        target = safe_worktree_target(root, str(spec["path"]))
+        body = render_template(str(spec.get("body") or ""), ports)
+        if target.is_symlink():
+            target.unlink()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        header = str(spec.get("header") or "# Generated by wte; changes will be overwritten.\n")
+        payload = header + body
+        target.write_text(payload if payload.endswith("\n") else payload + "\n")
+
+
+def _init_entries(profile: Profile) -> List[Dict[str, Any]]:
+    raw = profile.get("init") or []
+    return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
+
+
+def run_initializers(profile: Profile, root: Path) -> None:
+    """Start missing dependency setup tasks without blocking Git checkout."""
+    for index, item in enumerate(_init_entries(profile)):
+        command = str(item.get("command") or "").strip()
+        cwd_raw = str(item.get("cwd") or "").strip()
+        if not command or not cwd_raw:
+            log(f"initializer skipped; command and cwd are required: {item}")
+            continue
+        cwd = expand_profile_path(cwd_raw, profile, root=root).resolve()
+        if not cwd.is_dir():
+            log(f"initializer skipped; directory does not exist: {cwd}")
+            continue
+        skip_if = item.get("skip_if")
+        if skip_if:
+            marker = expand_profile_path(str(skip_if), profile, root=cwd)
+            if marker.exists():
+                continue
+        log_path = Path(tempfile.gettempdir()) / f"wte-init-{os.getpid()}-{index}.log"
+        output = log_path.open("a")
+        try:
+            subprocess.Popen(
+                ["bash", "-lc", command],
+                cwd=str(cwd),
+                stdout=output,
+                stderr=subprocess.STDOUT,
+                start_new_session=True,
+            )
+        finally:
+            output.close()
+        log(f"initializer started: {command} -> {log_path}")
+
+
+def apply_worktree(
+    paths: AppPaths,
+    root: Path,
+    setup: bool = False,
+) -> Optional[ApplyResult]:
+    """Apply the matching profile to one worktree.
+
+    An unmatched repository is intentionally a no-op so the global checkout
+    hook remains safe for every Git repository on the machine.
+    """
+    root = root.resolve()
+    profile = find_profile(paths, root)
+    if profile is None:
+        return None
+
+    pool = load_port_pool(paths)
+    with registry_lock(paths):
+        registry = prune_registry(load_registry(paths))
+        block_start, ports = allocate_ports(profile, root, registry, pool)
+
+        # Keep allocation and projection in one short transaction. If writing
+        # fails, no registry entry is committed and the reconciler can retry.
+        apply_secrets(profile, root)
+        apply_writes(profile, root, ports)
+        registry[str(root)] = {
+            "profile": profile["name"],
+            "file": Path(profile.get("_file") or "").name,
+            "block_start": block_start,
+            "ports": ports,
+        }
+        save_registry(paths, registry)
+
+    if setup:
+        run_initializers(profile, root)
+    return ApplyResult(str(profile["name"]), root, ports)
+
+
+def print_apply_result(result: ApplyResult) -> None:
+    """Print a compact, stable summary for interactive use and hook logs."""
+    endpoints = "  ".join(
+        f"{name}=http://127.0.0.1:{port}" for name, port in result.ports.items()
+    )
+    print(f"[wte] profile={result.profile}")
+    print(f"[wte] root={result.root}")
+    print(f"[wte] {endpoints}")

git_worktree_env/reconciler.py

@@ -0,0 +1,273 @@
+"""Host-side reconciliation for worktrees created without Git hooks."""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import platform
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Sequence, Set, Tuple
+
+from .hooks import resolve_wte_executable
+from .paths import AppPaths
+from .profiles import configured_main_worktree, load_profiles, worktree_root
+from .projector import apply_worktree, print_apply_result
+from .registry import load_registry, prune_registry
+from .utils import WteError, log, run_git
+
+LAUNCHD_LABEL = "io.github.archcst.wte-reconciler"
+SYSTEMD_SERVICE = "wte-reconciler.service"
+SYSTEMD_PATH = "wte-reconciler.path"
+
+
+@dataclass(frozen=True)
+class MonitorStatus:
+    """Installation and runtime state of the host filesystem monitor."""
+
+    supported: bool
+    installed: bool
+    active: bool
+    watch_paths: Tuple[Path, ...]
+    detail: str
+
+
+@dataclass(frozen=True)
+class ReconcileResult:
+    """Summary of one scan across all configured Git repositories."""
+
+    discovered: int
+    applied: int
+    pending: int
+
+
+def _run(command: Sequence[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        list(command),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+    )
+
+
+def _common_git_dir(main: Path) -> Optional[Path]:
+    try:
+        raw = Path(run_git("rev-parse", "--git-common-dir", cwd=main))
+    except WteError:
+        return None
+    return (main / raw).resolve() if not raw.is_absolute() else raw.resolve()
+
+
+def discover_watch_paths(paths: AppPaths) -> Tuple[Path, ...]:
+    """Return each configured repository's linked-worktree metadata directory."""
+    watched: Set[Path] = set()
+    for profile in load_profiles(paths, strict=False):
+        main = configured_main_worktree(profile)
+        if main is None or not main.is_dir():
+            continue
+        common = _common_git_dir(main)
+        if common is not None:
+            watched.add(common / "worktrees")
+    return tuple(sorted(watched))
+
+
+def _listed_worktrees(main: Path) -> List[Path]:
+    """Read worktree paths from Git's NUL-delimited porcelain output."""
+    output = run_git("worktree", "list", "--porcelain", "-z", cwd=main)
+    roots: List[Path] = []
+    for field in output.split("\0"):
+        if field.startswith("worktree "):
+            roots.append(Path(field[len("worktree ") :]).resolve())
+    return roots
+
+
+def _candidate_worktrees(paths: AppPaths) -> Set[Path]:
+    candidates: Set[Path] = set()
+    for profile in load_profiles(paths):
+        main = configured_main_worktree(profile)
+        if main is None or not main.is_dir():
+            continue
+        try:
+            candidates.update(_listed_worktrees(main))
+        except WteError as exc:
+            log(f"reconcile skipped repository {main}: {exc}")
+    return candidates
+
+
+def reconcile_once(paths: AppPaths) -> ReconcileResult:
+    """Project configuration into worktrees missing from the port registry."""
+    registered = set(prune_registry(load_registry(paths)))
+    candidates = _candidate_worktrees(paths)
+    applied = 0
+    pending = 0
+
+    for candidate in sorted(candidates):
+        if str(candidate) in registered:
+            continue
+        try:
+            # Git may publish common-dir metadata before checkout is complete.
+            if worktree_root(candidate) != candidate:
+                raise WteError(f"worktree root is not stable yet: {candidate}")
+            result = apply_worktree(paths, candidate, setup=False)
+            if result is None:
+                continue
+            print_apply_result(result)
+            registered.add(str(candidate))
+            applied += 1
+        except (OSError, WteError) as exc:
+            pending += 1
+            log(f"reconcile will retry {candidate}: {exc}")
+
+    return ReconcileResult(len(candidates), applied, pending)
+
+
+def reconcile_with_retry(paths: AppPaths) -> ReconcileResult:
+    """Retry briefly while a newly announced checkout becomes readable."""
+    result = reconcile_once(paths)
+    for delay in (0.5, 1.0, 2.0):
+        if result.pending == 0:
+            break
+        time.sleep(delay)
+        result = reconcile_once(paths)
+    return result
+
+
+def _launch_agent_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LAUNCHD_LABEL}.plist"
+
+
+def _launch_domain() -> str:
+    return f"gui/{os.getuid()}"
+
+
+def _write_launch_agent(paths: AppPaths, executable: Path, watched: Tuple[Path, ...]) -> Path:
+    agent = _launch_agent_path()
+    agent.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "Label": LAUNCHD_LABEL,
+        "ProgramArguments": [str(executable), "_reconcile"],
+        "RunAtLoad": True,
+        "WatchPaths": [str(path) for path in watched],
+        "ProcessType": "Background",
+        "ThrottleInterval": 2,
+        "StandardOutPath": str(paths.state / "reconciler.log"),
+        "StandardErrorPath": str(paths.state / "reconciler.log"),
+    }
+    with agent.open("wb") as handle:
+        plistlib.dump(payload, handle, sort_keys=True)
+    return agent
+
+
+def _install_launchd(paths: AppPaths, executable: Path, watched: Tuple[Path, ...]) -> MonitorStatus:
+    agent = _write_launch_agent(paths, executable, watched)
+    _run(["launchctl", "bootout", f"{_launch_domain()}/{LAUNCHD_LABEL}"])
+    result = _run(["launchctl", "bootstrap", _launch_domain(), str(agent)])
+    if result.returncode != 0:
+        raise WteError(result.stderr.strip() or "launchctl bootstrap failed")
+    return monitor_status(paths, watched)
+
+
+def _systemd_user_dir() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(os.path.expanduser(xdg)) if xdg else Path.home() / ".config"
+    return base / "systemd" / "user"
+
+
+def _write_systemd_units(executable: Path, watched: Tuple[Path, ...]) -> Tuple[Path, Path]:
+    unit_dir = _systemd_user_dir()
+    unit_dir.mkdir(parents=True, exist_ok=True)
+    service = unit_dir / SYSTEMD_SERVICE
+    path_unit = unit_dir / SYSTEMD_PATH
+    escaped_executable = str(executable).replace("%", "%%")
+    service.write_text(
+        "[Unit]\nDescription=Reconcile worktree-env projects\n\n"
+        "[Service]\nType=oneshot\n"
+        f'ExecStart="{escaped_executable}" _reconcile\n'
+    )
+    path_lines = "\n".join(
+        f"PathChanged={str(path).replace('%', '%%')}" for path in watched
+    )
+    path_unit.write_text(
+        "[Unit]\nDescription=Watch Git linked-worktree metadata for wte\n\n"
+        f"[Path]\n{path_lines}\nUnit={SYSTEMD_SERVICE}\n\n"
+        "[Install]\nWantedBy=default.target\n"
+    )
+    return service, path_unit
+
+
+def _install_systemd(paths: AppPaths, executable: Path, watched: Tuple[Path, ...]) -> MonitorStatus:
+    _write_systemd_units(executable, watched)
+    reload_result = _run(["systemctl", "--user", "daemon-reload"])
+    if reload_result.returncode != 0:
+        raise WteError(reload_result.stderr.strip() or "systemd user manager is unavailable")
+    result = _run(["systemctl", "--user", "enable", "--now", SYSTEMD_PATH])
+    if result.returncode != 0:
+        raise WteError(result.stderr.strip() or "cannot enable wte-reconciler.path")
+    return monitor_status(paths, watched)
+
+
+def install_monitor(paths: AppPaths) -> MonitorStatus:
+    """Install or refresh the OS-managed directory monitor for current profiles."""
+    watched = discover_watch_paths(paths)
+    if not watched:
+        uninstall_monitor(paths)
+        return MonitorStatus(
+            True,
+            False,
+            False,
+            (),
+            "no configured main worktrees; add a profile and run `wte monitor enable`",
+        )
+    executable = resolve_wte_executable()
+    system = platform.system()
+    if system == "Darwin":
+        return _install_launchd(paths, executable, watched)
+    if system == "Linux":
+        return _install_systemd(paths, executable, watched)
+    return MonitorStatus(False, False, False, watched, f"unsupported platform: {system}")
+
+
+def _uninstall_launchd() -> None:
+    _run(["launchctl", "bootout", f"{_launch_domain()}/{LAUNCHD_LABEL}"])
+    agent = _launch_agent_path()
+    if agent.exists():
+        agent.unlink()
+
+
+def _uninstall_systemd() -> None:
+    _run(["systemctl", "--user", "disable", "--now", SYSTEMD_PATH])
+    unit_dir = _systemd_user_dir()
+    for name in (SYSTEMD_PATH, SYSTEMD_SERVICE):
+        unit = unit_dir / name
+        if unit.exists():
+            unit.unlink()
+    _run(["systemctl", "--user", "daemon-reload"])
+
+
+def uninstall_monitor(paths: AppPaths) -> None:
+    """Remove any platform-specific reconciler registration."""
+    system = platform.system()
+    if system == "Darwin":
+        _uninstall_launchd()
+    elif system == "Linux":
+        _uninstall_systemd()
+
+
+def monitor_status(
+    paths: AppPaths,
+    watched: Optional[Tuple[Path, ...]] = None,
+) -> MonitorStatus:
+    """Inspect the current platform's reconciler registration."""
+    watched = watched if watched is not None else discover_watch_paths(paths)
+    system = platform.system()
+    if system == "Darwin":
+        installed = _launch_agent_path().is_file()
+        active = _run(["launchctl", "print", f"{_launch_domain()}/{LAUNCHD_LABEL}"]).returncode == 0
+        return MonitorStatus(True, installed, active, watched, "launchd")
+    if system == "Linux":
+        path_unit = _systemd_user_dir() / SYSTEMD_PATH
+        active = _run(["systemctl", "--user", "is-active", "--quiet", SYSTEMD_PATH]).returncode == 0
+        return MonitorStatus(True, path_unit.is_file(), active, watched, "systemd.path")
+    return MonitorStatus(False, False, False, watched, f"unsupported platform: {system}")