worktree-env 0.3.0__tar.gz → 0.4.0__tar.gz

{worktree_env-0.3.0 → worktree_env-0.4.0}/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-22
+
+- Standardized user-facing configuration keys on hyphenated names while keeping
+  underscore-based profile and port-range keys as backward-compatible aliases.
+
+## [0.3.1] - 2026-08-21
+
+- Run profile initializers from the Monitor Reconciler so worktrees created by
+  sandboxed coding agents and IDEs receive the same setup as hook-created worktrees.
+
 ## [0.3.0] - 2026-08-21
 
 - Changed profile initializers to `command` and `args` string arrays, executed

{worktree_env-0.3.0 → worktree_env-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: worktree-env
-Version: 0.3.0
+Version: 0.4.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
@@ -180,7 +180,7 @@ Set `WTE_CONFIG_HOME` to change this directory. When it is not set,
 The machine-wide port range is configured in `~/.config/wte/config.yaml`:
 
 ```yaml
-port_range:
+port-range:
   start: 20000
   end: 29999
 ```
@@ -204,15 +204,15 @@ name: example-project
 
 match:
   # Points to the project's main worktree directory.
-  main_worktree: $HOME/code/example-app
+  main-worktree: $HOME/code/example-app
 
-ports:
+port-claims:
   # 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:
+link-files:
   # Environment files shared through symlinks.
   # source points to the original environment file, while target is a path
   # relative to the worktree root.
@@ -221,7 +221,7 @@ secrets:
   - source: $HOME/path/to/your/backend.env
     target: backend-dir/.env
 
-writes:
+write-files:
   # Frontend configuration:
   - path: frontend-dir/.env.development
     body: |
@@ -239,6 +239,10 @@ writes:
 >
 > After a worktree directory is deleted, its ports are reclaimed the next time `wte`
 > is triggered.
+>
+> Configuration generated by older versions remains supported. The legacy keys
+> `port_range`, `main_worktree`, `ports`, `secrets`, `writes`, `init`, and `skip_if`
+> are aliases for the hyphenated keys shown above.
 
 ## Monitor
 
@@ -262,10 +266,10 @@ 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.
+2. Compares it with `ports.json`, then assigns ports, mounts secrets, generates
+   files, and starts configured initializers for unregistered worktrees.
 
-After adding a profile or changing a `main_worktree` path, run this command again:
+After adding a profile or changing a `main-worktree` path, run this command again:
 
 ```bash
 wte monitor enable
@@ -285,16 +289,16 @@ Afterward, filesystem changes will no longer be monitored.
 environment to be initialized in the background:
 
 ```yaml
-init:
+setup-commands:
   - command: [npm]
     args: [install]
     cwd: frontend-dir  # Use "." to run from the worktree root.
-    skip_if: node_modules  # Skip this command if the file or directory exists.
+    skip-if: node_modules  # Skip this command if the file or directory exists.
 
   - command: [uv]
     args: [sync]
     cwd: backend-dir  # Use "." to run from the worktree root.
-    skip_if: .venv  # Skip this command if the file or directory exists.
+    skip-if: .venv  # Skip this command if the file or directory exists.
 ```
 
 A typical timeline looks like this:
@@ -306,10 +310,10 @@ Create a worktree
   → 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.
+Asynchronous initialization is started by the normal `post-checkout` hook or by the
+Monitor Reconciler when it discovers an unregistered worktree. The Reconciler does
+not process registered worktrees again, and each command's `skip-if` marker provides
+additional protection against repeated setup. `wte sync` does not run initializers.
 
 ## Commands supported by `wte`
 

{worktree_env-0.3.0 → worktree_env-0.4.0}/README.md

@@ -153,7 +153,7 @@ Set `WTE_CONFIG_HOME` to change this directory. When it is not set,
 The machine-wide port range is configured in `~/.config/wte/config.yaml`:
 
 ```yaml
-port_range:
+port-range:
   start: 20000
   end: 29999
 ```
@@ -177,15 +177,15 @@ name: example-project
 
 match:
   # Points to the project's main worktree directory.
-  main_worktree: $HOME/code/example-app
+  main-worktree: $HOME/code/example-app
 
-ports:
+port-claims:
   # 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:
+link-files:
   # Environment files shared through symlinks.
   # source points to the original environment file, while target is a path
   # relative to the worktree root.
@@ -194,7 +194,7 @@ secrets:
   - source: $HOME/path/to/your/backend.env
     target: backend-dir/.env
 
-writes:
+write-files:
   # Frontend configuration:
   - path: frontend-dir/.env.development
     body: |
@@ -212,6 +212,10 @@ writes:
 >
 > After a worktree directory is deleted, its ports are reclaimed the next time `wte`
 > is triggered.
+>
+> Configuration generated by older versions remains supported. The legacy keys
+> `port_range`, `main_worktree`, `ports`, `secrets`, `writes`, `init`, and `skip_if`
+> are aliases for the hyphenated keys shown above.
 
 ## Monitor
 
@@ -235,10 +239,10 @@ 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.
+2. Compares it with `ports.json`, then assigns ports, mounts secrets, generates
+   files, and starts configured initializers for unregistered worktrees.
 
-After adding a profile or changing a `main_worktree` path, run this command again:
+After adding a profile or changing a `main-worktree` path, run this command again:
 
 ```bash
 wte monitor enable
@@ -258,16 +262,16 @@ Afterward, filesystem changes will no longer be monitored.
 environment to be initialized in the background:
 
 ```yaml
-init:
+setup-commands:
   - command: [npm]
     args: [install]
     cwd: frontend-dir  # Use "." to run from the worktree root.
-    skip_if: node_modules  # Skip this command if the file or directory exists.
+    skip-if: node_modules  # Skip this command if the file or directory exists.
 
   - command: [uv]
     args: [sync]
     cwd: backend-dir  # Use "." to run from the worktree root.
-    skip_if: .venv  # Skip this command if the file or directory exists.
+    skip-if: .venv  # Skip this command if the file or directory exists.
 ```
 
 A typical timeline looks like this:
@@ -279,10 +283,10 @@ Create a worktree
   → 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.
+Asynchronous initialization is started by the normal `post-checkout` hook or by the
+Monitor Reconciler when it discovers an unregistered worktree. The Reconciler does
+not process registered worktrees again, and each command's `skip-if` marker provides
+additional protection against repeated setup. `wte sync` does not run initializers.
 
 ## Commands supported by `wte`
 

{worktree_env-0.3.0 → worktree_env-0.4.0}/README.zh-CN.md

@@ -114,7 +114,7 @@ wte init
 全机端口范围位于 `~/.config/wte/config.yaml`：
 
 ```yaml
-port_range:
+port-range:
   start: 20000
   end: 29999
 ```
@@ -137,14 +137,14 @@ name: example-project
 
 match:
   # 指向该项目的 main worktree 目录。
-  main_worktree: $HOME/code/example-app
+  main-worktree: $HOME/code/example-app
 
-ports:
+port-claims:
   # 需要申请的端口的名称，项目需要多少就申请多少，id 在同一个 profile 中应保持唯一
   - id: frontend_port
   - id: backend_port
 
-secrets:
+link-files:
   # 软链接共享的环境变量
   # source 指向原始环境变量文件，target 是目标位置，路径是基于 worktree 根目录的相对路径。
   - source: $HOME/path/to/your/frontend.env
@@ -152,7 +152,7 @@ secrets:
   - source: $HOME/path/to/your/backend.env
     target: backend-dir/.env
 
-writes:
+write-files:
   # 前端配置：
   - path: frontend-dir/.env.development
     body: |
@@ -168,6 +168,9 @@ writes:
 > 该示例适用于前后端均可加载 `.env.{env name}` 的情况，请根据具体项目环境变量加载方式自行修改。
 >
 > Worktree 目录删除后，其对应的端口会在下一次触发 `wte` 时被回收。
+>
+> 旧版本生成的配置仍然兼容。旧配置项 `port_range`、`main_worktree`、`ports`、
+> `secrets`、`writes`、`init` 和 `skip_if` 均作为上述短横线配置项的别名继续支持。
 
 ## Monitor 说明
 
@@ -188,9 +191,9 @@ wte monitor enable
 Reconciler 会：
 
 1. 执行 `git worktree list --porcelain` 获取真实 Worktree 列表。
-2. 与 `ports.json` 对比，为尚未注册的 Worktree 分配端口、挂载 Secrets、生成文件。
+2. 与 `ports.json` 对比，为尚未注册的 Worktree 分配端口、挂载 Secrets、生成文件并启动配置的初始化命令。
 
-新增 Profile 或修改 `main_worktree` 路径后，需要再次执行：
+新增 Profile 或修改 `main-worktree` 路径后，需要再次执行：
 
 ```bash
 wte monitor enable
@@ -209,16 +212,16 @@ wte monitor disable
 `wte` 可在 Worktree 创建后自动运行命令，可用于环境初始化：
 
 ```yaml
-init:
+setup-commands:
   - command: [npm]
     args: [install]
     cwd: frontend-dir # 若在 Worktree 根目录执行，则填写“.”
-    skip_if: node_modules # 若该文件或目录存在，则跳过该命令
+    skip-if: node_modules # 若该文件或目录存在，则跳过该命令
 
   - command: [uv]
     args: [sync]
     cwd: backend-dir # 若在 Worktree 根目录执行，则填写“.”
-    skip_if: .venv # 若该文件或目录存在，则跳过该命令
+    skip-if: .venv # 若该文件或目录存在，则跳过该命令
 ```
 
 典型时间线如下：
@@ -230,7 +233,7 @@ init:
   → 用户或 AI 启动项目时，依赖通常已经准备完成
 ```
 
-异步初始化只由正常的 `post-checkout` Hook 启动。`wte sync` 和 Monitor Reconciler 都不会执行这些命令，避免手动同步或后台补偿重复启动耗时任务。
+异步初始化由正常的 `post-checkout` Hook 启动；当 Monitor Reconciler 发现尚未注册的 Worktree 时也会启动。Reconciler 不会重复处理已注册的 Worktree，同时每条命令的 `skip-if` 标记可进一步避免重复初始化。`wte sync` 不会执行初始化命令。
 
 ## `wte` 支持的命令
 

{worktree_env-0.3.0 → worktree_env-0.4.0}/examples/fullstack.yaml

@@ -2,21 +2,21 @@
 name: example-fullstack
 
 match:
-  main_worktree: $HOME/code/example-app
+  main-worktree: $HOME/code/example-app
 
 # Claims are allocated as one contiguous block in declaration order.
-ports:
+port-claims:
   - id: frontend
   - id: backend
 
 # Sources stay outside Git. Targets are symlinks inside every linked worktree.
-secrets:
+link-files:
   - source: $HOME/.config/example-app/frontend.env
     target: apps/frontend/.env
   - source: $HOME/.config/example-app/backend.env
     target: apps/backend/.env
 
-writes:
+write-files:
   - path: apps/frontend/.env.development
     body: |
       VITE_PORT=${frontend}
@@ -29,12 +29,12 @@ writes:
 
 # Initializers run in the background only from the post-checkout hook.
 # Each command is trusted local configuration and is executed directly.
-init:
+setup-commands:
   - command: [npm]
     args: [install]
     cwd: apps/frontend
-    skip_if: node_modules
+    skip-if: node_modules
   - command: [uv]
     args: [sync]
     cwd: apps/backend
-    skip_if: .venv
+    skip-if: .venv

{worktree_env-0.3.0 → worktree_env-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "worktree-env"
-version = "0.3.0"
+version = "0.4.0"
 description = "Per-worktree ports, secrets, and local environment setup for Git"
 readme = "README.md"
 requires-python = ">=3.9"

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/__init__.py

@@ -1,3 +1,3 @@
 """worktree-env public package."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/cli.py

@@ -12,7 +12,7 @@ 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 .profiles import aliased_value, load_profiles, validate_profiles, worktree_root
 from .projector import apply_worktree, print_apply_result
 from .reconciler import (
     install_monitor,
@@ -144,7 +144,7 @@ def _cmd_doctor(paths: AppPaths) -> int:
         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 []:
+        for entry in aliased_value(profile, "link-files", "secrets", default=[]) or []:
             if not isinstance(entry, dict) or not entry.get("source"):
                 continue
             source = expand_profile_path(str(entry["source"]), profile).resolve()

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/config.py

@@ -14,7 +14,7 @@ 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_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.
@@ -25,24 +25,24 @@ 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
+  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:
+# ${placeholder} in write-files below.
+port-claims:
   - id: frontend
   - id: backend
 
 # Optional local secret files. Sources stay outside Git; targets are replaced
 # with symlinks inside each matched worktree.
-secrets:
+link-files:
   - source: $HOME/.config/example-app/frontend.env
     target: apps/frontend/.env
   - source: $HOME/.config/example-app/backend.env
     target: apps/backend/.env
 
 # Optional generated files. Each target is overwritten completely on sync.
-writes:
+write-files:
   - path: apps/frontend/.env.development
     body: |
       VITE_PORT=${frontend}
@@ -53,18 +53,18 @@ writes:
       PORT=${backend}
       CORS_ORIGIN=http://127.0.0.1:${frontend}
 
-# Optional post-checkout initializers. Commands are trusted local configuration
-# executed directly in the background. args are appended to command, and skip_if
-# is resolved relative to cwd.
-init:
+# Optional worktree initializers started by post-checkout or the Monitor Reconciler.
+# Commands are trusted local configuration executed directly in the background.
+# args are appended to command, and skip-if is resolved relative to cwd.
+setup-commands:
   - command: [npm]
     args: [install]
     cwd: apps/frontend
-    skip_if: node_modules
+    skip-if: node_modules
   - command: [uv]
     args: [sync]
     cwd: apps/backend
-    skip_if: .venv
+    skip-if: .venv
 """
 
 
@@ -77,11 +77,11 @@ class PortPool:
 
     def validate(self) -> None:
         if not 1 <= self.start <= 65535:
-            raise WteError(f"port_range.start is outside 1-65535: {self.start}")
+            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}")
+            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")
+            raise WteError("port-range.end must be greater than or equal to port-range.start")
 
 
 def _load_yaml_mapping(path: Path) -> Dict[str, Any]:
@@ -101,16 +101,20 @@ def load_port_pool(paths: AppPaths) -> PortPool:
         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 "pool" in data and "port-range" not in data and "port_range" not in data:
+        raise WteError("config key 'pool' was renamed to 'port-range'")
+    if "port-range" in data:
+        raw_pool = data["port-range"]
+    else:
+        # ``port_range`` remains supported for configs created by older releases.
+        raw_pool = data.get("port_range") or {}
     if not isinstance(raw_pool, dict):
-        raise WteError(f"port_range must be a mapping: {paths.config}")
+        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
+        raise WteError("port-range.start and port-range.end must be integers") from exc
     pool = PortPool(start, end)
     pool.validate()
     return pool

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/profiles.py

@@ -17,6 +17,21 @@ Profile = Dict[str, Any]
 PORT_ID = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
 
+def aliased_value(
+    mapping: Dict[str, Any], canonical: str, *legacy: str, default: Any = None
+) -> Any:
+    """Read a canonical configuration key, falling back to legacy aliases."""
+    for key in (canonical, *legacy):
+        if key in mapping:
+            return mapping[key]
+    return default
+
+
+def _selected_key(mapping: Dict[str, Any], canonical: str, *legacy: str) -> str:
+    """Return the key whose value :func:`aliased_value` will select."""
+    return next((key for key in (canonical, *legacy) if key in mapping), canonical)
+
+
 def parse_profile(path: Path) -> Profile:
     """Parse one YAML or JSON profile and attach its source path."""
     try:
@@ -96,7 +111,11 @@ def main_worktree_root(root: Path) -> Path:
 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
+    raw = (
+        aliased_value(match, "main-worktree", "main_worktree")
+        if isinstance(match, dict)
+        else None
+    )
     if not raw:
         return None
     return expand_home(str(raw)).resolve()
@@ -118,8 +137,15 @@ def find_profile(paths: AppPaths, root: Path) -> Optional[Profile]:
     return hits[0]
 
 
+def port_claims_value(profile: Profile) -> Any:
+    """Read port claims while preserving the older ``ports``/``services`` fallback."""
+    if "port-claims" in profile:
+        return profile["port-claims"]
+    return profile.get("ports") or profile.get("services") or []
+
+
 def _port_claims(profile: Profile) -> Sequence[Dict[str, Any]]:
-    raw = profile.get("ports") or profile.get("services") or []
+    raw = port_claims_value(profile)
     return raw if isinstance(raw, list) else []
 
 
@@ -146,12 +172,19 @@ def validate_profiles(paths: AppPaths) -> Tuple[List[str], List[str]]:
             names[name] = source
 
         match = profile.get("match") or {}
-        main_raw = match.get("main_worktree") if isinstance(match, dict) else None
+        if isinstance(match, dict):
+            main_key = _selected_key(match, "main-worktree", "main_worktree")
+            main_raw = aliased_value(match, "main-worktree", "main_worktree")
+        else:
+            main_key = "main-worktree"
+            main_raw = None
         main_root = configured_main_worktree(profile)
         if main_root is None:
-            errors.append(f"{label}: match.main_worktree is required")
+            errors.append(f"{label}: match.{main_key} 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")
+            errors.append(
+                f"{label}: match.{main_key} 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}"
@@ -161,64 +194,85 @@ def validate_profiles(paths: AppPaths) -> Tuple[List[str], List[str]]:
             if not main_root.exists():
                 warnings.append(f"{label}: main worktree does not exist: {main_root}")
 
+        if "port-claims" in profile:
+            claims_key = "port-claims"
+        elif profile.get("ports") or "services" not in profile:
+            claims_key = "ports"
+        else:
+            claims_key = "services"
         claims = _port_claims(profile)
         if not claims:
-            errors.append(f"{label}: ports must contain at least one claim")
+            errors.append(f"{label}: {claims_key} 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")
+                errors.append(f"{label}: {claims_key}[{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 []
+        writes_key = _selected_key(profile, "write-files", "writes")
+        writes = aliased_value(profile, "write-files", "writes", default=[])
+        if writes is None:
+            writes = []
         if not isinstance(writes, list):
-            errors.append(f"{label}: writes must be a list")
+            errors.append(f"{label}: {writes_key} 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")
+                errors.append(f"{label}: {writes_key}[{index}] must be a mapping")
                 continue
             write_path = spec.get("path")
             if not write_path:
-                errors.append(f"{label}: writes[{index}].path is required")
+                errors.append(f"{label}: {writes_key}[{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")
+                errors.append(
+                    f"{label}: {writes_key}[{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}")
+                errors.append(
+                    f"{label}: {writes_key}[{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")
+        links_key = _selected_key(profile, "link-files", "secrets")
+        links = aliased_value(profile, "link-files", "secrets", default=[])
+        if links is None:
+            links = []
+        if not isinstance(links, list):
+            errors.append(f"{label}: {links_key} must be a list")
         else:
-            for index, entry in enumerate(secrets):
+            for index, entry in enumerate(links):
                 if not isinstance(entry, dict):
-                    errors.append(f"{label}: secrets[{index}] must be a mapping")
+                    errors.append(f"{label}: {links_key}[{index}] must be a mapping")
                     continue
                 if not entry.get("source"):
-                    errors.append(f"{label}: secrets[{index}].source is required")
+                    errors.append(f"{label}: {links_key}[{index}].source is required")
                 target = entry.get("target")
                 if not target:
-                    errors.append(f"{label}: secrets[{index}].target is required")
+                    errors.append(f"{label}: {links_key}[{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")
+                    errors.append(
+                        f"{label}: {links_key}[{index}].target must stay inside the worktree"
+                    )
 
-        initializers = profile.get("init")
-        if initializers is None:
-            initializers = []
-        if not isinstance(initializers, list):
-            errors.append(f"{label}: init must be a list")
+        setup_key = _selected_key(profile, "setup-commands", "init")
+        setup_commands = aliased_value(
+            profile, "setup-commands", "init", default=[]
+        )
+        if setup_commands is None:
+            setup_commands = []
+        if not isinstance(setup_commands, list):
+            errors.append(f"{label}: {setup_key} must be a list")
         else:
-            for index, entry in enumerate(initializers):
+            for index, entry in enumerate(setup_commands):
                 if not isinstance(entry, dict):
-                    errors.append(f"{label}: init[{index}] must be a mapping")
+                    errors.append(f"{label}: {setup_key}[{index}] must be a mapping")
                     continue
                 command = entry.get("command")
                 if (
@@ -228,16 +282,18 @@ def validate_profiles(paths: AppPaths) -> Tuple[List[str], List[str]]:
                     or not command[0].strip()
                 ):
                     errors.append(
-                        f"{label}: init[{index}].command must be a non-empty string list"
+                        f"{label}: {setup_key}[{index}].command must be a non-empty string list"
                     )
                 args = entry.get("args", [])
                 if not isinstance(args, list) or not all(
                     isinstance(value, str) for value in args
                 ):
-                    errors.append(f"{label}: init[{index}].args must be a string list")
+                    errors.append(
+                        f"{label}: {setup_key}[{index}].args must be a string list"
+                    )
                 cwd = entry.get("cwd")
                 if not isinstance(cwd, str) or not cwd.strip():
-                    errors.append(f"{label}: init[{index}].cwd is required")
+                    errors.append(f"{label}: {setup_key}[{index}].cwd is required")
 
     if not profiles:
         warnings.append(f"no profiles found in {paths.profiles}")

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/projector.py

@@ -13,7 +13,7 @@ from typing import Any, Dict, List, Optional
 
 from .config import load_port_pool
 from .paths import AppPaths
-from .profiles import Profile, find_profile
+from .profiles import Profile, aliased_value, find_profile
 from .registry import (
     allocate_ports,
     load_registry,
@@ -41,7 +41,7 @@ def render_template(body: str, ports: Dict[str, int]) -> str:
 
 
 def _secret_entries(profile: Profile) -> List[Dict[str, Any]]:
-    raw = profile.get("secrets") or []
+    raw = aliased_value(profile, "link-files", "secrets", default=[]) or []
     return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
 
 
@@ -67,9 +67,9 @@ def apply_secrets(profile: Profile, root: Path) -> None:
 
 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 []
+    writes = aliased_value(profile, "write-files", "writes", default=[]) or []
     if not isinstance(writes, list):
-        raise WteError(f"profile {profile.get('name')} has an invalid writes section")
+        raise WteError(f"profile {profile.get('name')} has an invalid write-files 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")
@@ -84,7 +84,7 @@ def apply_writes(profile: Profile, root: Path, ports: Dict[str, int]) -> None:
 
 
 def _init_entries(profile: Profile) -> List[Dict[str, Any]]:
-    raw = profile.get("init") or []
+    raw = aliased_value(profile, "setup-commands", "init", default=[]) or []
     return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
 
 
@@ -115,7 +115,7 @@ def run_initializers(profile: Profile, root: Path) -> None:
         if not cwd.is_dir():
             log(f"initializer skipped; directory does not exist: {cwd}")
             continue
-        skip_if = item.get("skip_if")
+        skip_if = aliased_value(item, "skip-if", "skip_if")
         if skip_if:
             marker = expand_profile_path(str(skip_if), profile, root=cwd)
             if marker.exists():

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/reconciler.py

@@ -110,7 +110,10 @@ def reconcile_once(paths: AppPaths) -> ReconcileResult:
             # 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)
+            # The reconciler is the fallback for sandboxed Git clients that
+            # cannot invoke the host's post-checkout hook, so it must perform
+            # the same asynchronous initialization for a new worktree.
+            result = apply_worktree(paths, candidate, setup=True)
             if result is None:
                 continue
             print_apply_result(result)

{worktree_env-0.3.0 → worktree_env-0.4.0}/src/worktree_env/registry.py

@@ -13,7 +13,7 @@ from typing import Any, Dict, Iterator, Set, Tuple
 
 from .config import PortPool
 from .paths import AppPaths
-from .profiles import Profile
+from .profiles import Profile, port_claims_value
 from .utils import WteError
 
 Registry = Dict[str, Any]
@@ -126,7 +126,7 @@ def allocate_ports(
     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 []
+    claims = port_claims_value(profile)
     if not isinstance(claims, list) or not claims:
         raise WteError(f"profile {profile.get('name')} has no ports to claim")
     try:

{worktree_env-0.3.0 → worktree_env-0.4.0}/tests/test_config.py

@@ -16,10 +16,11 @@ def test_init_generates_documented_port_range(tmp_path, monkeypatch):
     assert initialize_config(paths) is True
     assert paths.config.read_text() == (
         "# Inclusive range used for per-worktree port allocation.\n"
-        "port_range:\n"
+        "port-range:\n"
         "  start: 20000\n"
         "  end: 29999\n"
     )
+    assert load_port_pool(paths).start == 20000
 
 
 def test_init_template_is_commented_and_not_an_active_yaml_profile(app_paths):
@@ -32,7 +33,13 @@ def test_init_template_is_commented_and_not_an_active_yaml_profile(app_paths):
     assert "# Port IDs form one contiguous block" in text
     assert "# Optional local secret files" in text
     assert "# Optional generated files" in text
-    assert "# Optional post-checkout initializers" in text
+    assert "# Optional worktree initializers" in text
+    assert "main-worktree:" in text
+    assert "port-claims:" in text
+    assert "link-files:" in text
+    assert "write-files:" in text
+    assert "setup-commands:" in text
+    assert "skip-if:" in text
     assert "$HOME/.config/example-app/frontend.env" in text
     assert "$HOME/.config/example-app/backend.env" in text
     assert "cwd: apps/frontend" in text
@@ -40,8 +47,16 @@ def test_init_template_is_commented_and_not_an_active_yaml_profile(app_paths):
     assert "wte monitor enable" in text
 
 
+def test_legacy_port_range_key_remains_supported(app_paths):
+    app_paths.config.write_text("port_range:\n  start: 41000\n  end: 41099\n")
+
+    pool = load_port_pool(app_paths)
+
+    assert (pool.start, pool.end) == (41000, 41099)
+
+
 def test_legacy_pool_key_is_rejected(app_paths):
     app_paths.config.write_text("pool:\n  start: 41000\n  end: 41099\n")
 
-    with pytest.raises(WteError, match="renamed to 'port_range'"):
+    with pytest.raises(WteError, match="renamed to 'port-range'"):
         load_port_pool(app_paths)

{worktree_env-0.3.0 → worktree_env-0.4.0}/tests/test_profiles.py

@@ -34,12 +34,12 @@ def test_validation_rejects_duplicate_main_worktrees(app_paths, git_worktrees):
     assert any("also configured" in error for error in errors)
 
 
-def test_validation_accepts_initializer_command_and_args_lists(app_paths, tmp_path):
+def test_validation_accepts_setup_command_and_args_lists(app_paths, tmp_path):
     (app_paths.profiles / "example.yaml").write_text(
         "name: example\n"
-        f"match:\n  main_worktree: {tmp_path}\n"
-        "ports:\n  - id: web\n"
-        "init:\n"
+        f"match:\n  main-worktree: {tmp_path}\n"
+        "port-claims:\n  - id: web\n"
+        "setup-commands:\n"
         "  - command: [npm]\n"
         "    args: [install]\n"
         "    cwd: .\n"

{worktree_env-0.3.0 → worktree_env-0.4.0}/tests/test_projector.py

@@ -5,18 +5,34 @@ from worktree_env.registry import load_registry
 from worktree_env.utils import WteError
 
 
-def test_projection_links_secrets_and_writes_ports(app_paths, git_worktrees, tmp_path, monkeypatch):
+@pytest.mark.parametrize(
+    ("main_key", "claims_key", "links_key", "writes_key"),
+    [
+        ("main-worktree", "port-claims", "link-files", "write-files"),
+        ("main_worktree", "ports", "secrets", "writes"),
+    ],
+)
+def test_projection_links_secrets_and_writes_ports(
+    app_paths,
+    git_worktrees,
+    tmp_path,
+    monkeypatch,
+    main_key,
+    claims_key,
+    links_key,
+    writes_key,
+):
     main, linked = git_worktrees
     secret = tmp_path / "backend.env"
     secret.write_text("TOKEN=test\n")
     (app_paths.profiles / "example.yaml").write_text(
         "name: example\n"
-        f"match:\n  main_worktree: {main}\n"
-        "ports:\n  - id: frontend\n  - id: backend\n"
-        "secrets:\n"
+        f"match:\n  {main_key}: {main}\n"
+        f"{claims_key}:\n  - id: frontend\n  - id: backend\n"
+        f"{links_key}:\n"
         f"  - source: {secret}\n"
         "    target: app/.env\n"
-        "writes:\n"
+        f"{writes_key}:\n"
         "  - path: app/.env.development\n"
         "    body: |\n"
         "      PORT=${frontend}\n"
@@ -39,17 +55,22 @@ def test_projection_links_secrets_and_writes_ports(app_paths, git_worktrees, tmp
     assert load_registry(app_paths)[str(linked)]["profile"] == "example"
 
 
+@pytest.mark.parametrize(
+    ("setup_key", "skip_key"),
+    [("setup-commands", "skip-if"), ("init", "skip_if")],
+)
 def test_initializers_execute_command_and_args_without_a_shell(
-    tmp_path, monkeypatch, capsys
+    tmp_path, monkeypatch, capsys, setup_key, skip_key
 ):
     calls = []
     profile = {
         "name": "example",
-        "init": [
+        setup_key: [
             {
                 "command": ["tool", "subcommand"],
                 "args": ["literal;value", "two words"],
                 "cwd": ".",
+                skip_key: "missing-marker",
             }
         ],
     }

{worktree_env-0.3.0 → worktree_env-0.4.0}/tests/test_reconciler.py

@@ -55,6 +55,30 @@ def test_reconciler_projects_only_unregistered_worktrees(
     assert (linked / "generated.env").exists()
 
 
+def test_reconciler_runs_initializers_for_unregistered_worktrees(
+    app_paths, git_worktrees, monkeypatch
+):
+    main, linked = git_worktrees
+    (app_paths.profiles / "example.yaml").write_text(
+        "name: example\n"
+        f"match:\n  main_worktree: {main}\n"
+        "ports:\n  - id: web\n"
+        "init:\n  - command: [tool]\n    cwd: .\n"
+    )
+    monkeypatch.setattr("worktree_env.registry.port_is_free", lambda _port: True)
+    initialized = []
+    monkeypatch.setattr(
+        "worktree_env.projector.run_initializers",
+        lambda _profile, root: initialized.append(root),
+    )
+
+    reconcile_once(app_paths)
+    reconcile_once(app_paths)
+
+    assert set(initialized) == {main.resolve(), linked.resolve()}
+    assert len(initialized) == 2
+
+
 def test_launch_agent_watches_common_git_metadata(
     app_paths, tmp_path, monkeypatch
 ):

{worktree_env-0.3.0 → worktree_env-0.4.0}/uv.lock

@@ -258,7 +258,7 @@ wheels = [
 
 [[package]]
 name = "worktree-env"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },