worktree-env 0.2.0__py3-none-any.whl

git_worktree_env/registry.py

@@ -0,0 +1,166 @@
+"""Concurrent, sticky allocation of per-worktree port blocks."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import socket
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Dict, Iterator, Set, Tuple
+
+from .config import PortPool
+from .paths import AppPaths
+from .profiles import Profile
+from .utils import WteError
+
+Registry = Dict[str, Any]
+
+
+def load_registry(paths: AppPaths) -> Registry:
+    """Load the registry and reject corruption instead of silently resetting it."""
+    if not paths.registry.exists():
+        return {}
+    try:
+        raw = json.loads(paths.registry.read_text() or "{}")
+    except (OSError, json.JSONDecodeError) as exc:
+        raise WteError(f"cannot read port registry {paths.registry}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise WteError(f"port registry root must be an object: {paths.registry}")
+    return raw
+
+
+def save_registry(paths: AppPaths, registry: Registry) -> None:
+    """Atomically replace the registry while preserving a valid old copy on crash."""
+    paths.root.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(registry, indent=2, sort_keys=True) + "\n"
+    descriptor, temporary = tempfile.mkstemp(prefix=".ports-", suffix=".tmp", dir=paths.root)
+    temp_path = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temp_path, 0o600)
+        os.replace(temp_path, paths.registry)
+        try:
+            directory_fd = os.open(str(paths.root), os.O_RDONLY)
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+        except OSError:
+            # Directory fsync is not available on every supported filesystem.
+            pass
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()
+
+
+@contextmanager
+def registry_lock(paths: AppPaths) -> Iterator[None]:
+    """Serialize registry reads, allocation, garbage collection, and writes."""
+    paths.root.mkdir(parents=True, exist_ok=True)
+    paths.lock.touch(exist_ok=True)
+    try:
+        os.chmod(paths.lock, 0o600)
+    except OSError:
+        pass
+    with paths.lock.open("a+") as handle:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def is_live_worktree(path: str) -> bool:
+    """Return whether a registered worktree directory still exists."""
+    return Path(path).is_dir()
+
+
+def prune_registry(registry: Registry) -> Registry:
+    """Drop entries whose worktree directory no longer exists."""
+    return {
+        path: metadata
+        for path, metadata in registry.items()
+        if isinstance(metadata, dict) and is_live_worktree(path)
+    }
+
+
+def port_is_free(port: int) -> bool:
+    """Return whether a new process can bind the port on loopback."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind(("127.0.0.1", port))
+        return True
+    except OSError:
+        return False
+    finally:
+        sock.close()
+
+
+def _used_by_other_worktrees(registry: Registry, current: str) -> Set[int]:
+    used: Set[int] = set()
+    for path, metadata in registry.items():
+        if path == current or not isinstance(metadata, dict) or not Path(path).exists():
+            continue
+        ports = metadata.get("ports") or {}
+        if not isinstance(ports, dict):
+            continue
+        for raw_port in ports.values():
+            try:
+                used.add(int(raw_port))
+            except (TypeError, ValueError):
+                continue
+    return used
+
+
+def allocate_ports(
+    profile: Profile,
+    root: Path,
+    registry: Registry,
+    pool: PortPool,
+) -> Tuple[int, Dict[str, int]]:
+    """Reuse a valid sticky allocation or claim the first free contiguous block."""
+    claims = profile.get("ports") or profile.get("services") or []
+    if not isinstance(claims, list) or not claims:
+        raise WteError(f"profile {profile.get('name')} has no ports to claim")
+    try:
+        ids = [str(item["id"]) for item in claims]
+    except (TypeError, KeyError) as exc:
+        raise WteError(f"profile {profile.get('name')} has an invalid port claim") from exc
+
+    count = len(ids)
+    current = str(root)
+    used = _used_by_other_worktrees(registry, current)
+    existing = registry.get(current) if isinstance(registry.get(current), dict) else None
+    profile_file = Path(profile.get("_file") or "").name
+    if existing:
+        same_profile = existing.get("profile") == profile.get("name")
+        # File identity preserves allocations created before profiles had unique names.
+        same_file = bool(profile_file) and existing.get("file") == profile_file
+        saved = existing.get("ports") or {}
+        if (same_profile or same_file) and isinstance(saved, dict):
+            try:
+                values = [int(saved[port_id]) for port_id in ids]
+            except (KeyError, TypeError, ValueError):
+                values = []
+            if (
+                len(values) == count
+                and all(pool.start <= port <= pool.end for port in values)
+                and not (set(values) & used)
+            ):
+                return min(values), dict(zip(ids, values))
+
+    last_start = pool.end - count + 1
+    for start in range(pool.start, last_start + 1):
+        ports = list(range(start, start + count))
+        if set(ports) & used:
+            continue
+        if all(port_is_free(port) for port in ports):
+            return start, dict(zip(ids, ports))
+    raise WteError(f"no free block of {count} ports in pool {pool.start}-{pool.end}")

git_worktree_env/utils.py

@@ -0,0 +1,82 @@
+"""Small shared helpers for subprocesses, paths, and diagnostics."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from string import Template
+from typing import Any, Dict, Optional
+
+
+class WteError(RuntimeError):
+    """Base exception for expected user-facing failures."""
+
+
+def log(message: str) -> None:
+    """Write a consistently prefixed diagnostic to stderr."""
+    sys.stderr.write(f"[wte] {message}\n")
+
+
+def run_git(*args: str, cwd: Optional[Path] = None) -> str:
+    """Run Git and return stripped stdout, raising a user-facing error."""
+    result = subprocess.run(
+        ["git", *args],
+        cwd=str(cwd) if cwd else None,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+    )
+    if result.returncode != 0:
+        detail = result.stderr.strip() or f"git {' '.join(args)} failed"
+        raise WteError(detail)
+    return result.stdout.strip()
+
+
+def expand_home(value: str) -> Path:
+    """Expand ``~``, ``$HOME``, and ``${HOME}`` in a configured path."""
+    text = str(value).strip()
+    home = str(Path.home())
+    text = text.replace("${HOME}", home).replace("$HOME", home)
+    return Path(os.path.expanduser(text))
+
+
+def expand_profile_path(
+    value: str,
+    profile: Dict[str, Any],
+    root: Optional[Path] = None,
+) -> Path:
+    """Expand profile variables and resolve a relative path against ``root``."""
+    text = str(value).strip()
+    home = str(Path.home())
+    text = text.replace("${HOME}", home).replace("$HOME", home)
+    text = Template(text).safe_substitute(
+        name=profile.get("name") or "",
+        HOME=home,
+    )
+    path = Path(os.path.expanduser(text))
+    if not path.is_absolute() and root is not None:
+        path = root / path
+    return path
+
+
+def is_within(path: Path, root: Path) -> bool:
+    """Return whether a resolved path is inside a resolved root (Python 3.9)."""
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def safe_worktree_target(root: Path, value: str) -> Path:
+    """Resolve a profile target and reject paths outside the worktree."""
+    raw = Path(str(value))
+    target = raw if raw.is_absolute() else root / raw
+    # Resolve the parent but not the final component: an existing target may be
+    # a secret symlink that intentionally points outside the worktree.
+    target = target.parent.resolve(strict=False) / target.name
+    if not is_within(target.parent, root):
+        raise WteError(f"target escapes the worktree: {value}")
+    return target

worktree_env-0.2.0.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.5
+Name: worktree-env
+Version: 0.2.0
+Summary: Per-worktree ports, secrets, and local environment setup for Git
+Project-URL: Homepage, https://github.com/archcst/worktree-env
+Project-URL: Repository, https://github.com/archcst/worktree-env
+Project-URL: Issues, https://github.com/archcst/worktree-env/issues
+Author: Shitong Chen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: development,environment,git,ports,worktree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# worktree-env (`wte`)
+
+[中文文档](README.zh-CN.md)
+
+Automatically prepare an isolated, runnable local development environment for every
+Git worktree. Lightweight, minimal, no magic.
+
+## The problem
+
+Git worktrees are widely used for parallel development and task isolation. However,
+a new worktree usually contains only code, not a development environment that is
+ready to run:
+
+- The frontend, backend, database, and debugger still use the same fixed ports,
+  preventing multiple worktrees from running at the same time.
+- `.env` files, private keys, and other local secrets must be copied repeatedly and
+  can easily be committed by mistake.
+- URLs and port settings shared by services within a project must be kept in sync
+  manually.
+
+Common solutions often require adding extra scripts to the project, changing how it
+is started, modifying `AGENTS.md` or `CLAUDE.md`, or creating skills.
+These approaches are intrusive to some degree: they must either be adopted across
+the team or affect how other team members work.
+
+`wte` uses a Git `post-checkout` hook to assign stable, conflict-free ports to a
+project's worktrees, link environment variables, and generate local configuration.
+The hook is not committed to the repository. It is available globally on the local
+machine and does not modify any project code.
+
+## Comparison with existing tools
+
+- [Portless](https://github.com/vercel-labs/portless): Requires applications to be
+  started through `portless`, introducing a reverse proxy, a local CA, and a
+  background service.
+- [devports](https://github.com/bendechrai/devports): Wraps worktree creation and
+  removal in `devports` commands; worktrees created directly by an agent or IDE are
+  not handled automatically.
+- [Worktrunk](https://worktrunk.dev/): Replaces the native Git workflow with `wt`,
+  does not participate in environment setup, and does not automatically handle
+  worktrees created directly by an agent or IDE.
+- [workz](https://github.com/rohansx/workz): Uses `.workz.toml`,
+  `workz sync`/`workz start`, or separately configured hooks for Cursor, Claude Code,
+  and Worktrunk.
+- [Hyve](https://github.com/eladkishon/hyve): Adopts a
+  `hyve create`/`hyve run` workflow and depends on Docker, database containers, and
+  service orchestration.
+
+`wte` does not take over how worktrees are created or how a project is started.
+Instead, it automatically projects a complete local development environment after a
+worktree is created. It requires no changes to project code, start commands, or agent
+prompts; no scripts need to be added to the project, and no traffic proxy or resident
+process is required. Worktrees created by Git, an IDE, or a coding agent can all be
+handled automatically.
+
+All rules are declared explicitly in profiles stored outside the repository. For each
+worktree, `wte` assigns stable ports, mounts secrets, generates local configuration,
+and can initialize dependencies in the background, making the worktree ready
+immediately after creation.
+
+## Features
+
+- Allocates contiguous port blocks from a machine-wide shared pool and keeps them
+  stable for the lifetime of the worktree path.
+- Mounts secrets stored outside the repository into the worktree as symlinks,
+  preserving a single source of truth and avoiding copy and paste.
+- Organizes configuration by repository rather than by service. Supports monorepos
+  and multiple port requests.
+- Optionally monitors host directories to discover newly added linked worktrees,
+  including those created within coding agent sandboxes.
+- Preserves the project's own Git hooks. After the `post-checkout` hook for `wte`
+  finishes, it invokes the project's own executable Git hook.
+- Zero intrusion: no wrapper, no skill, and no changes to coding agent prompts or
+  project start commands.
+
+## Requirements
+
+- macOS or Linux
+- Python 3.9+
+- Git
+- Bash
+
+## Installation
+
+```bash
+uv tool install worktree-env
+```
+
+## Upgrading
+
+```bash
+uv tool upgrade worktree-env
+```
+
+## Migrating from `git-worktree-env`
+
+The PyPI package and GitHub repository were renamed in version 0.2.0. Existing
+configuration under `~/.config/wte/` is fully compatible:
+
+```bash
+uv tool uninstall git-worktree-env
+uv tool install worktree-env
+wte init
+# If you previously enabled the optional Monitor:
+wte monitor enable
+```
+
+Running `wte init` refreshes the Git hook's absolute executable path. The `wte`
+command and all existing profiles and state remain unchanged.
+
+## Getting started
+
+```bash
+wte init
+```
+
+This command:
+
+- Initializes the personal configuration directory at `~/.config/wte/`.
+- Runs `git config --global core.hooksPath ~/.config/wte/hooks` to install the global
+  Git hook dispatcher.
+
+> If the global `core.hooksPath` already points somewhere else, `wte` displays the
+> current value and refuses to change it. Confirm its purpose and migrate or remove
+> it as appropriate before retrying `wte init`.
+
+## `~/.config/wte/`
+
+Personal profiles, hooks, and runtime state are stored together in:
+
+```text
+~/.config/wte/
+├── config.yaml                       # Machine-wide port pool
+├── project_a.yaml                    # Project A profile
+├── project_b.yaml                    # Project B profile
+├── hooks/                            # Global Git hook dispatcher
+└── state/                            # Managed by wte; do not edit manually.
+    ├── ports.json                    # Port registry
+    ├── ports.lock                    # Concurrency lock
+    ├── hooks-state.json              # Hook installation state
+    └── reconciler.log                # Monitor log (present only when the optional Monitor is enabled; see the Monitor section)
+```
+
+Every root-level `*.yaml` file except `config.yaml` is loaded as a project profile.
+
+Set `WTE_CONFIG_HOME` to change this directory. When it is not set,
+`XDG_CONFIG_HOME` is respected.
+
+## Configuration examples
+
+### Port range
+
+The machine-wide port range is configured in `~/.config/wte/config.yaml`:
+
+```yaml
+port_range:
+  start: 20000
+  end: 29999
+```
+
+The default range is `20000-29999`. You can change it manually; new worktrees will
+be allocated from the new range, while existing allocations remain unchanged.
+
+### Project profile
+
+Copy the configuration template:
+
+```bash
+cp ~/.config/wte/project.example.yaml.template \
+   ~/.config/wte/example-project.yaml
+```
+
+The following profile describes a project with separate frontend and backend services:
+
+```yaml
+name: example-project
+
+match:
+  # Points to the project's main worktree directory.
+  main_worktree: $HOME/code/example-app
+
+ports:
+  # Names of the ports to request. Add as many as the project needs;
+  # each id must be unique within the profile.
+  - id: frontend_port
+  - id: backend_port
+
+secrets:
+  # Environment files shared through symlinks.
+  # source points to the original environment file, while target is a path
+  # relative to the worktree root.
+  - source: $HOME/path/to/your/frontend.env
+    target: frontend-dir/.env
+  - source: $HOME/path/to/your/backend.env
+    target: backend-dir/.env
+
+writes:
+  # Frontend configuration:
+  - path: frontend-dir/.env.development
+    body: |
+      VITE_PORT=${frontend_port}
+      SERVER_URL=http://127.0.0.1:${backend_port}
+
+  # Backend configuration:
+  - path: backend-dir/.env.development
+    body: |
+      PORT=${backend_port}
+```
+
+> This example applies when both the frontend and backend can load `.env.{env name}`
+> files. Adjust it to match how your project loads environment variables.
+>
+> After a worktree directory is deleted, its ports are reclaimed the next time `wte`
+> is triggered.
+
+## Monitor
+
+Some coding agents create worktrees inside a sandbox, which can prevent the `wte` hook from running.
+To support these tools, enable the Monitor:
+
+```bash
+wte monitor enable
+```
+
+It watches the `.git/worktrees/` metadata directory associated with each configured
+main worktree:
+
+- macOS uses a LaunchAgent with `WatchPaths`.
+- Linux uses a systemd user path unit.
+
+When the directory changes, the operating system starts a short-lived Reconciler.
+_It is not a resident daemon and does not poll on a timer_, so its resource usage is
+minimal.
+
+The Reconciler:
+
+1. Runs `git worktree list --porcelain` to retrieve the actual list of worktrees.
+2. Compares it with `ports.json`, then assigns ports, mounts secrets, and generates
+   files for unregistered worktrees.
+
+After adding a profile or changing a `main_worktree` path, run this command again:
+
+```bash
+wte monitor enable
+```
+
+To disable the Monitor, run:
+
+```bash
+wte monitor disable
+```
+
+Afterward, filesystem changes will no longer be monitored.
+
+## Asynchronous initialization
+
+`wte` can automatically run commands after a worktree is created, allowing the
+environment to be initialized in the background:
+
+```yaml
+init:
+  - command: npm install
+    cwd: frontend-dir  # Use "." to run from the worktree root.
+    skip_if: node_modules  # Skip this command if the file or directory exists.
+
+  - command: uv sync
+    cwd: backend-dir  # Use "." to run from the worktree root.
+    skip_if: .venv  # Skip this command if the file or directory exists.
+```
+
+A typical timeline looks like this:
+
+```text
+Create a worktree
+  → wte projects the environment and starts npm install in the background
+  → The user describes the task; the AI reads, analyzes, and modifies the code
+  → By the time the user or AI starts the project, dependencies are usually ready
+```
+
+Asynchronous initialization is started only by the normal `post-checkout` hook.
+Neither `wte sync` nor the Monitor Reconciler runs these commands, preventing manual
+synchronization or background reconciliation from repeatedly starting expensive
+tasks.
+
+## Commands supported by `wte`
+
+```text
+wte init              Create personal configuration and templates, and install core Git hooks
+wte sync              Synchronize ports, secrets, and generated files for the current worktree
+wte list              List port allocations for worktrees that still exist
+wte doctor            Diagnose configuration, profiles, registry, secrets, hooks, and Monitor
+wte monitor enable    Install or refresh optional host monitoring
+wte monitor disable   Remove host monitoring only, preserving Git hooks
+wte uninstall         Remove hooks and the Monitor, preserving configuration and runtime state
+```
+
+Run `wte sync` from inside the target worktree. It reuses existing ports, recreates
+secret symlinks, and regenerates configuration files.
+You may need it when a worktree is created through an unconventional method.
+
+## License
+
+[MIT](LICENSE)

worktree_env-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+git_worktree_env/__init__.py,sha256=6Yq8i_EGAqESUfMPzQBOcPBNqcogUCW_JsJOQ6kbvv0,58
+git_worktree_env/__main__.py,sha256=exBDURFpBCFo2WGaf2RYs_xCBLylUWaYZkzh3e_viso,148
+git_worktree_env/cli.py,sha256=gy9MIbaCKzV8PeuCbA_jT6Da1tkAtCk5DMf5HkTqmEg,8543
+git_worktree_env/config.py,sha256=K97bg--G8xlFXAbmUMx6kwbysZZYe2wp3Q-ox5KoqEo,4369
+git_worktree_env/hooks.py,sha256=NUf0506cu9qnlq_3fEiUPnhhCbxn-d1JyJQ6GELHm_Q,7185
+git_worktree_env/paths.py,sha256=B2pwcIifkgVCG4aANGOdc2fv5TQs3kYdVnamgFcSgFk,1976
+git_worktree_env/profiles.py,sha256=0VV4mjsOZKm4xbDnGxLZLBwMXaNQDic45jJ_RItXm10,8359
+git_worktree_env/projector.py,sha256=FgF4y6b8q7X3JhCf28q3LhqhQNLx2V94VHQOpQ0r4GM,6232
+git_worktree_env/reconciler.py,sha256=qOp-XT3PP8m39kZUAy8sBpidbOuNJ8I1ZkvWsWZXovQ,9692
+git_worktree_env/registry.py,sha256=mwNRiXzEbcxeLk0hb4pBx5SaXjnEbF2M0wp7M8QNV9A,5852
+git_worktree_env/utils.py,sha256=-XDWw5i4ZSnjckFWbL1WEh1_lgR_u6zr5wKSZVv78ms,2615
+worktree_env-0.2.0.dist-info/METADATA,sha256=QZW0_BYByWSEIndj9MCz-eX4MnFi0A_lAOcZNvua-Fo,11700
+worktree_env-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+worktree_env-0.2.0.dist-info/entry_points.txt,sha256=ssn_gQ9ASkh3eXfPzvTr_-nJmMNoqCHnjVGTA0dbIDM,91
+worktree_env-0.2.0.dist-info/licenses/LICENSE,sha256=acld2wTtDRQwmQJerEphpmlgYDW2jMvsmoA1fcoi3dA,1069
+worktree_env-0.2.0.dist-info/RECORD,,

worktree_env-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

worktree_env-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+worktree-env = git_worktree_env.cli:main
+wte = git_worktree_env.cli:main

worktree_env-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shitong Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.