worktree-env 0.2.0__py3-none-any.whl

git_worktree_env/__init__.py

@@ -0,0 +1,3 @@
+"""worktree-env public package."""
+
+__version__ = "0.2.0"

git_worktree_env/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m git_worktree_env`` to behave like ``wte``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

git_worktree_env/cli.py

@@ -0,0 +1,233 @@
+"""Command-line interface for wte."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib import metadata
+from typing import Optional, Sequence
+
+from . import __version__
+from .config import initialize_config, initialize_profile_template, load_port_pool
+from .hooks import hooks_status, install_hooks, uninstall_hooks
+from .paths import AppPaths
+from .profiles import load_profiles, validate_profiles, worktree_root
+from .projector import apply_worktree, print_apply_result
+from .reconciler import (
+    install_monitor,
+    monitor_status,
+    reconcile_with_retry,
+    uninstall_monitor,
+)
+from .registry import load_registry, prune_registry
+from .utils import WteError, expand_profile_path, log, run_git
+
+INTERNAL_HOOK_COMMAND = "_hook"
+INTERNAL_RECONCILE_COMMAND = "_reconcile"
+LEGACY_DISTRIBUTION = "git-worktree-env"
+
+
+def _warn_if_legacy_distribution_installed() -> None:
+    """Tell users of the transition package how to adopt the new package name."""
+    try:
+        metadata.distribution(LEGACY_DISTRIBUTION)
+    except metadata.PackageNotFoundError:
+        return
+
+    print(
+        "[wte] warning: git-worktree-env has been renamed to worktree-env.\n"
+        "[wte] migrate: uv tool uninstall git-worktree-env && "
+        "uv tool install worktree-env\n"
+        "[wte] then run 'wte init' to refresh the Git hook; refresh the monitor "
+        "with 'wte monitor enable' if used.\n"
+        "[wte] your existing ~/.config/wte configuration will be preserved.",
+        file=sys.stderr,
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the public CLI without exposing internal integration commands."""
+    parser = argparse.ArgumentParser(
+        prog="wte",
+        description="Per-worktree ports, secrets, and local environment setup.",
+    )
+    parser.add_argument("--version", action="version", version=f"wte {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    commands.add_parser(
+        "init",
+        help="create local configuration and install the Git hook dispatcher",
+    )
+    commands.add_parser("sync", help="synchronize the current worktree")
+    commands.add_parser("list", help="list live worktree port allocations")
+    commands.add_parser("doctor", help="diagnose configuration and host integration")
+    monitor_parser = commands.add_parser(
+        "monitor",
+        help="manage optional host monitoring for sandbox-created worktrees",
+    )
+    monitor_commands = monitor_parser.add_subparsers(dest="monitor_command", required=True)
+    monitor_commands.add_parser("enable", help="install or refresh host monitoring")
+    monitor_commands.add_parser("disable", help="remove host monitoring")
+    commands.add_parser(
+        "uninstall",
+        help="remove Git hooks while preserving configuration and state",
+    )
+    return parser
+
+
+def _cmd_init(paths: AppPaths) -> int:
+    config_created = initialize_config(paths)
+    template, template_created = initialize_profile_template(paths)
+    dispatcher = install_hooks(paths)
+    print(f"[wte] config: {paths.config} ({'created' if config_created else 'kept'})")
+    print(f"[wte] project template: {template} ({'created' if template_created else 'kept'})")
+    print(f"[wte] hooks: {dispatcher.parent}")
+    return 0
+
+
+def _cmd_sync(paths: AppPaths, setup: bool = False) -> int:
+    result = apply_worktree(paths, worktree_root(), setup=setup)
+    if result is None:
+        raise WteError("the current worktree does not match any project profile")
+    print_apply_result(result)
+    return 0
+
+
+def _cmd_list(paths: AppPaths) -> int:
+    registry = prune_registry(load_registry(paths))
+    print(json.dumps(registry, indent=2, sort_keys=True) if registry else "(empty)")
+    return 0
+
+
+def _print_validation(paths: AppPaths) -> int:
+    load_port_pool(paths)
+    errors, warnings = validate_profiles(paths)
+    for warning in warnings:
+        print(f"[wte] warning: {warning}")
+    for error in errors:
+        print(f"[wte] error: {error}", file=sys.stderr)
+    if errors:
+        return 1
+    print(f"[wte] configuration is valid ({len(load_profiles(paths))} profile(s))")
+    return 0
+
+
+def _cmd_doctor(paths: AppPaths) -> int:
+    failures = 0
+    print(f"[wte] config: {paths.root}")
+    try:
+        print(f"[wte] git: {run_git('--version')}")
+    except WteError as exc:
+        print(f"[wte] error: {exc}", file=sys.stderr)
+        failures += 1
+
+    failures += int(_print_validation(paths) != 0)
+    try:
+        registry = load_registry(paths)
+        print(f"[wte] registry: {paths.registry} ({len(registry)} allocation(s))")
+    except WteError as exc:
+        print(f"[wte] error: {exc}", file=sys.stderr)
+        failures += 1
+
+    status = hooks_status(paths)
+    if status["installed"]:
+        print(f"[wte] hooks: installed at {status['expected_hooks_path']}")
+        print(f"[wte] hook executable: {status.get('wte_executable')}")
+    else:
+        print(f"[wte] warning: hooks are not installed (current: {status['current_hooks_path']})")
+
+    monitor = monitor_status(paths)
+    if monitor.installed and monitor.active:
+        print(f"[wte] reconciler: active via {monitor.detail} ({len(monitor.watch_paths)} path(s))")
+    else:
+        print(f"[wte] warning: reconciler is not active ({monitor.detail})")
+
+    for profile in load_profiles(paths, strict=False):
+        for entry in profile.get("secrets") or []:
+            if not isinstance(entry, dict) or not entry.get("source"):
+                continue
+            source = expand_profile_path(str(entry["source"]), profile).resolve()
+            if not source.is_file():
+                print(f"[wte] warning: missing secret source: {source}")
+    return 1 if failures else 0
+
+
+def _cmd_monitor(paths: AppPaths, command: str) -> int:
+    if command == "enable":
+        monitor = install_monitor(paths)
+        if not monitor.installed:
+            raise WteError(monitor.detail)
+        print(f"[wte] reconciler: {monitor.detail} watching {len(monitor.watch_paths)} path(s)")
+        return 0
+    uninstall_monitor(paths)
+    print("[wte] reconciler monitoring disabled")
+    return 0
+
+
+def _cmd_uninstall(paths: AppPaths) -> int:
+    uninstall_monitor(paths)
+    previous = uninstall_hooks(paths)
+    print("[wte] hooks and reconciler uninstalled; configuration and state were preserved")
+    print(f"[wte] restored core.hooksPath: {previous or '(unset)'}")
+    return 0
+
+
+def _cmd_internal_hook(paths: AppPaths) -> int:
+    """Synchronize after checkout without ever blocking the Git operation."""
+    try:
+        result = apply_worktree(paths, worktree_root(), setup=True)
+        if result is not None:
+            print_apply_result(result)
+        return 0
+    except Exception as exc:  # Git hooks must fail open, including unexpected errors.
+        log(f"hook skipped: {exc}")
+        return 0
+
+
+def _cmd_internal_reconcile(paths: AppPaths) -> int:
+    """Reconcile host-visible worktrees after a common-dir filesystem event."""
+    try:
+        result = reconcile_with_retry(paths)
+        print(
+            f"[wte] reconcile: discovered={result.discovered} "
+            f"applied={result.applied} pending={result.pending}"
+        )
+        return 0 if result.pending == 0 else 1
+    except Exception as exc:
+        log(f"reconcile failed: {exc}")
+        return 1
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Parse arguments and return a process exit status."""
+    arguments = list(argv) if argv is not None else sys.argv[1:]
+    paths = AppPaths.discover()
+    if arguments and arguments[0] == INTERNAL_HOOK_COMMAND:
+        return _cmd_internal_hook(paths)
+    if arguments and arguments[0] == INTERNAL_RECONCILE_COMMAND:
+        return _cmd_internal_reconcile(paths)
+
+    _warn_if_legacy_distribution_installed()
+    args = _build_parser().parse_args(arguments)
+    try:
+        if args.command == "init":
+            return _cmd_init(paths)
+        if args.command == "sync":
+            return _cmd_sync(paths)
+        if args.command == "list":
+            return _cmd_list(paths)
+        if args.command == "doctor":
+            return _cmd_doctor(paths)
+        if args.command == "monitor":
+            return _cmd_monitor(paths, args.monitor_command)
+        if args.command == "uninstall":
+            return _cmd_uninstall(paths)
+        raise WteError(f"unknown command: {args.command}")
+    except WteError as exc:
+        log(str(exc))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

git_worktree_env/config.py

@@ -0,0 +1,127 @@
+"""Machine-wide port-pool configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict
+
+import yaml
+
+from .paths import AppPaths
+from .utils import WteError
+
+DEFAULT_POOL_START = 20000
+DEFAULT_POOL_END = 29999
+DEFAULT_PROFILE_TEMPLATE_NAME = "project.example.yaml.template"
+DEFAULT_CONFIG = """# Inclusive range used for per-worktree port allocation.\nport_range:\n  start: 20000\n  end: 29999\n"""
+DEFAULT_PROFILE_TEMPLATE = """# Copy this file to a root-level *.yaml file, then edit every example value.
+# Example: cp project.example.yaml.template my-project.yaml
+# Run `wte monitor enable` after adding or changing profiles to refresh monitoring.
+
+# A unique identifier stored in the local port registry.
+name: example-fullstack
+
+match:
+  # Exact path of this project's dedicated main worktree. Linked worktrees
+  # created from it are matched automatically, regardless of their location.
+  main_worktree: $HOME/code/example-app
+
+# Port IDs form one contiguous block in declaration order. Use each ID as a
+# ${placeholder} in writes below.
+ports:
+  - id: frontend
+  - id: backend
+
+# Optional local secret files. Sources stay outside Git; targets are replaced
+# with symlinks inside each matched worktree.
+secrets:
+  - source: $HOME/.config/example-app/backend.env
+    target: apps/backend/.env
+
+# Optional generated files. Each target is overwritten completely on sync.
+writes:
+  - path: apps/frontend/.env.development
+    body: |
+      VITE_PORT=${frontend}
+      VITE_API_URL=http://127.0.0.1:${backend}
+
+  - path: apps/backend/.env.development
+    body: |
+      PORT=${backend}
+      CORS_ORIGIN=http://127.0.0.1:${frontend}
+
+# Optional post-checkout initializers. Commands are trusted local configuration
+# executed by Bash in the background. skip_if is resolved relative to cwd.
+init:
+  - command: npm install
+    cwd: .
+    skip_if: node_modules
+"""
+
+
+@dataclass(frozen=True)
+class PortPool:
+    """Inclusive bounds of the machine-local port pool."""
+
+    start: int
+    end: int
+
+    def validate(self) -> None:
+        if not 1 <= self.start <= 65535:
+            raise WteError(f"port_range.start is outside 1-65535: {self.start}")
+        if not 1 <= self.end <= 65535:
+            raise WteError(f"port_range.end is outside 1-65535: {self.end}")
+        if self.end < self.start:
+            raise WteError("port_range.end must be greater than or equal to port_range.start")
+
+
+def _load_yaml_mapping(path: Path) -> Dict[str, Any]:
+    try:
+        raw = yaml.safe_load(path.read_text()) or {}
+    except (OSError, yaml.YAMLError) as exc:
+        raise WteError(f"cannot read YAML file {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise WteError(f"YAML root must be a mapping: {path}")
+    return raw
+
+
+def load_port_pool(paths: AppPaths) -> PortPool:
+    """Load the configured pool, using defaults when config.yaml is absent."""
+    if not paths.config.exists():
+        pool = PortPool(DEFAULT_POOL_START, DEFAULT_POOL_END)
+        pool.validate()
+        return pool
+    data = _load_yaml_mapping(paths.config)
+    if "pool" in data and "port_range" not in data:
+        raise WteError("config key 'pool' was renamed to 'port_range'")
+    raw_pool = data.get("port_range") or {}
+    if not isinstance(raw_pool, dict):
+        raise WteError(f"port_range must be a mapping: {paths.config}")
+    try:
+        start = int(raw_pool.get("start") or DEFAULT_POOL_START)
+        end = int(raw_pool.get("end") or DEFAULT_POOL_END)
+    except (TypeError, ValueError) as exc:
+        raise WteError("port_range.start and port_range.end must be integers") from exc
+    pool = PortPool(start, end)
+    pool.validate()
+    return pool
+
+
+def initialize_config(paths: AppPaths) -> bool:
+    """Create the default config if absent; return whether it was created."""
+    paths.ensure()
+    if paths.config.exists():
+        return False
+    paths.config.write_text(DEFAULT_CONFIG)
+    return True
+
+
+def initialize_profile_template(paths: AppPaths) -> tuple[Path, bool]:
+    """Create the commented project template without making it an active profile."""
+    paths.ensure()
+    template = paths.root / DEFAULT_PROFILE_TEMPLATE_NAME
+    if template.exists():
+        return template, False
+    template.write_text(DEFAULT_PROFILE_TEMPLATE)
+    return template, True

git_worktree_env/hooks.py

@@ -0,0 +1,217 @@
+"""Installation and removal of the global Git hook dispatcher."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .paths import AppPaths
+from .utils import WteError
+
+# A dispatcher is installed for each common client-side hook. Most only chain
+# an existing hook; post-checkout additionally invokes wte.
+HOOK_NAMES = (
+    "applypatch-msg",
+    "pre-applypatch",
+    "post-applypatch",
+    "pre-commit",
+    "pre-merge-commit",
+    "prepare-commit-msg",
+    "commit-msg",
+    "post-commit",
+    "pre-rebase",
+    "post-checkout",
+    "post-merge",
+    "pre-push",
+    "pre-auto-gc",
+    "post-rewrite",
+    "post-index-change",
+    "sendemail-validate",
+    "reference-transaction",
+)
+
+
+def _git_config(*args: str, check: bool = True) -> subprocess.CompletedProcess:
+    result = subprocess.run(
+        ["git", "config", "--global", *args],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+    )
+    if check and result.returncode != 0:
+        raise WteError(result.stderr.strip() or "git config failed")
+    return result
+
+
+def current_hooks_path() -> Optional[str]:
+    """Return the raw global core.hooksPath, if configured."""
+    result = _git_config("--get", "core.hooksPath", check=False)
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _write_state(path: Path, state: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=".hooks-state-", dir=path.parent)
+    temp_path = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w") as handle:
+            json.dump(state, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temp_path, 0o600)
+        os.replace(temp_path, path)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()
+
+
+def _read_state(paths: AppPaths) -> Dict[str, Any]:
+    if not paths.hooks_state.exists():
+        return {}
+    try:
+        raw = json.loads(paths.hooks_state.read_text() or "{}")
+    except (OSError, json.JSONDecodeError) as exc:
+        raise WteError(f"cannot read hook state {paths.hooks_state}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise WteError(f"hook state must be an object: {paths.hooks_state}")
+    return raw
+
+
+def resolve_wte_executable() -> Path:
+    """Resolve an absolute executable path suitable for GUI-launched Git hooks."""
+    candidate = shutil.which("wte")
+    if candidate:
+        return Path(candidate).resolve()
+    argv0 = Path(sys.argv[0])
+    if argv0.exists():
+        return argv0.resolve()
+    raise WteError("cannot locate the wte executable; install it before installing hooks")
+
+
+def _dispatcher_script(executable: Path, previous: Optional[str]) -> str:
+    executable_value = shlex.quote(str(executable))
+    previous_value = shlex.quote(previous or "")
+    return f'''#!/usr/bin/env bash
+# Generated by wte. Re-run `wte init` instead of editing this file.
+set -u
+
+HOOK_NAME="$(basename "$0")"
+WTE_EXECUTABLE={executable_value}
+PREVIOUS_HOOKS_PATH={previous_value}
+
+if [[ "$HOOK_NAME" == "post-checkout" ]]; then
+  "$WTE_EXECUTABLE" _hook "$@" || true
+fi
+
+# Preserve a hooksPath that existed before wte was installed.
+if [[ -n "$PREVIOUS_HOOKS_PATH" ]]; then
+  if [[ "$PREVIOUS_HOOKS_PATH" = /* ]]; then
+    CHAIN_TARGET="$PREVIOUS_HOOKS_PATH/$HOOK_NAME"
+  else
+    CHAIN_TARGET="$PWD/$PREVIOUS_HOOKS_PATH/$HOOK_NAME"
+  fi
+  if [[ -x "$CHAIN_TARGET" ]]; then
+    exec "$CHAIN_TARGET" "$@"
+  fi
+fi
+
+# Fall back to the repository's native hook directory.
+COMMON="$(git rev-parse --git-common-dir 2>/dev/null)" || exit 0
+LOCAL="$COMMON/hooks/$HOOK_NAME"
+if [[ -x "$LOCAL" ]]; then
+  DISPATCH_DIR="$(cd "$(dirname "$0")" && pwd)"
+  LOCAL_DIR="$(cd "$(dirname "$LOCAL")" && pwd)"
+  if [[ "$LOCAL_DIR/$HOOK_NAME" != "$DISPATCH_DIR/$HOOK_NAME" && "$LOCAL_DIR/$HOOK_NAME" != "$DISPATCH_DIR/_dispatch" ]]; then
+    exec "$LOCAL" "$@"
+  fi
+fi
+exit 0
+'''
+
+
+def install_hooks(paths: AppPaths) -> Path:
+    """Install the global dispatcher without silently replacing another manager."""
+    paths.ensure()
+    target = str(paths.hooks)
+    current = current_hooks_path()
+    legacy = str(Path.home() / ".config" / "git-projects" / "hooks")
+
+    previous: Optional[str] = None
+    if current and Path(os.path.expanduser(current)).resolve() != paths.hooks.resolve():
+        if Path(os.path.expanduser(current)).resolve() == Path(legacy).resolve():
+            # This is the pre-open-source version of wte, not an independent manager.
+            previous = None
+        else:
+            raise WteError(
+                f"core.hooksPath is already set to {current!r}; wte did not change it"
+            )
+    elif paths.hooks_state.exists():
+        previous_raw = _read_state(paths).get("previous_hooks_path")
+        previous = str(previous_raw) if previous_raw else None
+
+    executable = resolve_wte_executable()
+    paths.hooks.mkdir(parents=True, exist_ok=True)
+    dispatcher = paths.hooks / "_dispatch"
+    dispatcher.write_text(_dispatcher_script(executable, previous))
+    dispatcher.chmod(0o755)
+
+    for name in HOOK_NAMES:
+        hook = paths.hooks / name
+        if hook.is_symlink() or hook.exists():
+            if hook.is_dir() and not hook.is_symlink():
+                raise WteError(f"cannot replace hook directory: {hook}")
+            hook.unlink()
+        hook.symlink_to("_dispatch")
+
+    _write_state(
+        paths.hooks_state,
+        {
+            "previous_hooks_path": previous,
+            "installed_hooks_path": target,
+            "wte_executable": str(executable),
+        },
+    )
+    _git_config("core.hooksPath", target)
+    return dispatcher
+
+
+def uninstall_hooks(paths: AppPaths) -> Optional[str]:
+    """Remove wte's dispatcher and restore the previous global hooksPath."""
+    state = _read_state(paths)
+    previous_raw = state.get("previous_hooks_path")
+    previous = str(previous_raw) if previous_raw else None
+    current = current_hooks_path()
+    if current and Path(os.path.expanduser(current)).resolve() == paths.hooks.resolve():
+        if previous:
+            _git_config("core.hooksPath", previous)
+        else:
+            _git_config("--unset", "core.hooksPath", check=False)
+    if paths.hooks.exists():
+        shutil.rmtree(paths.hooks)
+    if paths.hooks_state.exists():
+        paths.hooks_state.unlink()
+    return previous
+
+
+def hooks_status(paths: AppPaths) -> Dict[str, Any]:
+    """Return current installation details for human-readable reporting."""
+    state = _read_state(paths)
+    current = current_hooks_path()
+    installed = bool(current) and Path(os.path.expanduser(current)).resolve() == paths.hooks.resolve()
+    return {
+        "installed": installed,
+        "current_hooks_path": current,
+        "expected_hooks_path": str(paths.hooks),
+        "previous_hooks_path": state.get("previous_hooks_path"),
+        "wte_executable": state.get("wte_executable"),
+    }

git_worktree_env/paths.py

@@ -0,0 +1,64 @@
+"""Filesystem locations used by wte.
+
+Application code and user data are intentionally separate. The package can be
+installed anywhere, while mutable configuration stays under the user's XDG
+configuration directory.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AppPaths:
+    """Resolved paths for one wte configuration directory."""
+
+    root: Path
+    config: Path
+    profiles: Path
+    state: Path
+    registry: Path
+    lock: Path
+    hooks: Path
+    hooks_state: Path
+
+    @classmethod
+    def discover(cls) -> "AppPaths":
+        """Resolve paths from the environment.
+
+        ``WTE_CONFIG_HOME`` is primarily useful for tests and portable setups.
+        Otherwise wte follows ``XDG_CONFIG_HOME`` and falls back to
+        ``~/.config/wte``.
+        """
+        override = os.environ.get("WTE_CONFIG_HOME")
+        if override:
+            root = Path(os.path.expanduser(override)).resolve()
+        else:
+            xdg = os.environ.get("XDG_CONFIG_HOME")
+            base = Path(os.path.expanduser(xdg)) if xdg else Path.home() / ".config"
+            root = (base / "wte").resolve()
+        state = root / "state"
+        return cls(
+            root=root,
+            config=root / "config.yaml",
+            profiles=root,
+            state=state,
+            registry=state / "ports.json",
+            lock=state / "ports.lock",
+            hooks=root / "hooks",
+            hooks_state=state / "hooks-state.json",
+        )
+
+    def ensure(self) -> None:
+        """Create private configuration and state directories."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.state.mkdir(parents=True, exist_ok=True)
+        for directory in (self.root, self.state):
+            try:
+                directory.chmod(0o700)
+            except OSError:
+                # Some network filesystems do not expose POSIX permission bits.
+                pass