py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/initenv/components/project_structure/config_generator.py

@@ -0,0 +1,360 @@
+"""WL configuration generator."""
+
+from pathlib import Path
+from typing import Any, cast
+
+import tomllib
+
+from .....utils.file_copier import FileCopier
+from .....utils.logging import log_debug_pair, log_info, log_info_pair
+from .....utils.root import Root, RootKind
+from .....utils.root_fallback import current_root
+from ..config_manager import ConfigManager
+
+#: A bare relative :class:`Root`: the ``.wl`` layout has one definition, in the
+#: root module, so its *relative* spelling is derived rather than re-typed here
+#: (#118). The kind is irrelevant -- the derived-path methods only join fixed
+#: names onto ``path`` -- so PROJECT is the neutral placeholder, not a claim.
+_LAYOUT = Root(Path("."), RootKind.PROJECT)
+
+#: The manifest filename under ``.wl``: the one spelling shared by the absolute
+#: :func:`template_manifest_path` and the relative
+#: :attr:`ConfigGenerator.TEMPLATE_MANIFEST`, so the two cannot name different
+#: files.
+_MANIFEST_NAME = ".templates.json"
+
+
+def template_manifest_path(deploy_root: Root | None = None) -> Path:
+    """Path of the config-template deployment manifest under the deploy root.
+
+    ``<hooks deploy root>/.wl/.templates.json`` -- anchored exactly like the
+    templates it tracks, so the manifest and the files it describes always share
+    one ``.wl``.
+
+    ``deploy_root`` may be supplied as a value by the self-sync chain, which no
+    longer chdirs to it; when omitted this single-root entry resolves exactly
+    the one root it needs through
+    :func:`~wl_cli.utils.root_fallback.current_root` (#160).
+    """
+    root = deploy_root if deploy_root is not None else current_root(RootKind.DEPLOY)
+    return root.wl_dir() / _MANIFEST_NAME
+
+
+class ConfigGenerator:
+    """Generate configuration files in .wl directory using config-driven approach."""
+
+    #: Manifest tracking which config template source content was last deployed,
+    #: relative to the ``.wl`` at the hooks deploy root (see
+    #: :func:`template_manifest_path`). Kept a relative class constant so that
+    #: constructing a generator never shells out to git; it is anchored at use
+    #: time by :meth:`_manifest_path`. Tests override it on the instance.
+    #:
+    #: The ``.wl`` half is derived from the root module (#118) rather than
+    #: re-spelled here, so the control-directory name has a single definition;
+    #: the filename half is shared with :func:`template_manifest_path` through
+    #: :data:`_MANIFEST_NAME`, so the two can never name different files.
+    TEMPLATE_MANIFEST = _LAYOUT.wl_dir() / _MANIFEST_NAME
+
+    def __init__(self):
+        self.config_manager = ConfigManager()
+        self.file_copier = FileCopier()
+        self.config = {}
+        self._load_config()
+
+    def _load_config(self):
+        config_path = self.config_manager.get_vendor_config_path(
+            "config/template_config.toml"
+        )
+        if config_path.exists():
+            try:
+                with open(config_path, "rb") as f:
+                    self.config = tomllib.load(f)
+            except Exception as e:
+                log_info(f"Warning: Failed to load template config: {e}")
+                self.config = {}
+        else:
+            self.config = {}
+
+    def generate_configs(self, deploy_root: Root | None = None) -> bool:
+        """Generate configuration files in .wl directory.
+
+        Pure template migration: this never re-syncs git hooks. Callers that
+        need hooks synced invoke :func:`hooks_manager.sync_hooks` explicitly at
+        their orchestration site.
+
+        ``deploy_root`` is the root the ``.wl`` files are written under, threaded
+        in as a value by the self-sync chain (which no longer chdirs to it); when
+        omitted this single-root entry resolves exactly the one root it needs
+        through :func:`~wl_cli.utils.root_fallback.current_root` (#160).
+
+        Returns:
+            True when ``.wl/config.json`` exists once this returns *and* the
+            template manifest was saved. The verdict is read off the disk, not
+            off the creation attempt: under pytest the incidental-save guard
+            used to answer "written" for a file it never created, so the sync
+            deployed templates onto a ``.wl`` with no config and then failed the
+            version stamp (#202). The manifest save reports its own outcome
+            (#201), so an unwritable manifest cannot leave the sync claiming a
+            refresh it did not persist. Callers take False as a failed config
+            sub-step instead of a silently half-built ``.wl``.
+        """
+        if deploy_root is None:
+            deploy_root = current_root(RootKind.DEPLOY)
+        wl_dir = deploy_root.wl_dir()
+        log_dir = wl_dir / "log"
+        config_file = wl_dir / "config.json"
+
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_debug_pair("✓ Created .wl/log directory", "✓ 创建 .wl/log 目录")
+
+        if not config_file.exists():
+            try:
+                from .....utils.config import ConfigManager as ProjectConfigManager
+                from .....utils.config import get_config_manager
+
+                config_manager = get_config_manager()
+                if _same_file(Path(config_manager.config_file), config_file):
+                    materialised = config_manager.ensure_project_config()
+                else:
+                    # The process-wide manager writes wherever its own resolution
+                    # points -- ``WL_CONFIG_PATH``, or a CWD outside the checkout.
+                    # Asking it to "ensure the project config" then materialised
+                    # the defaults in that unrelated file while this ``.wl`` kept
+                    # no ``config.json`` at all: the self-sync read "missing
+                    # config" on every command and never converged (#190). Write
+                    # the defaults at the ``.wl`` this sync actually owns.
+                    log_info_pair(
+                        f"Creating the default config at {config_file} (the active "
+                        f"config file is {config_manager.config_file}).",
+                        f"正在 {config_file} 创建默认配置（当前生效的配置文件是 "
+                        f"{config_manager.config_file}）。",
+                    )
+                    materialised = ProjectConfigManager(
+                        config_file=str(config_file)
+                    ).ensure_project_config()
+                # ``ensure_project_config`` already answers by existence; the
+                # re-check keeps the contract honest even for a mocked or
+                # subclassed manager that only claims success (#202).
+                if not materialised or not config_file.exists():
+                    raise RuntimeError(f"no config.json was created at {config_file}")
+                log_debug_pair(
+                    f"✓ Created default config file at {config_file}",
+                    f"✓ 在 {config_file} 创建默认配置文件",
+                )
+            except Exception as e:
+                log_info_pair(
+                    f"Warning: Failed to create default config file: {e}",
+                    f"警告: 创建默认配置文件失败: {e}",
+                )
+
+        templates_saved = self._copy_config_templates(deploy_root.path)
+
+        # Report from the bytes on disk, never from "a creation was attempted":
+        # a half-built ``.wl`` (templates yes, config no) is what let the first
+        # worktree run fail its version stamp under the test-environment save
+        # guard (#202). The manifest's own save is part of the verdict too: a
+        # stale manifest forces the next command to rebuild, so claiming success
+        # for a save that failed is the silent-retry loop of #201.
+        return config_file.exists() and templates_saved
+
+    def _copy_config_templates(self, deploy_root: Path | None = None) -> bool:
+        """Copy config templates, refreshing tool-deployed ones when the source
+        template changed, while preserving files the user has modified.
+
+        Deployment is tracked in ``.wl/.templates.json``. Each entry is either a
+        legacy scalar (source sha256 last deployed, treated as tool-owned) or a
+        v2 record ``{"src": <sha>, "user": bool}``:
+
+        - ``user: true`` -> the destination is (or became) user-modified: it is
+          never refreshed (bug #44). The tool stops auto-propagating to it.
+        - ``user: false`` -> tool-owned: refreshed when the vendored source
+          changes AND the destination is still byte-identical to the last
+          deployed source; once the destination diverges (the user touched it)
+          it is re-pinned as ``user: true`` and preserved.
+
+        A pre-existing ``.wl`` without a manifest entry is migrated once:
+        destinations already matching the source are recorded as tool-owned;
+        destinations that differ may be user-modified, so they are recorded as
+        ``user: true`` and never clobbered.
+
+        Returns:
+            Whether the manifest was persisted; the template copies themselves
+            stay best-effort (their failures are already reported per file).
+        """
+        # Direct callers (tests) may omit the path; the single root this helper
+        # needs then comes from the one fallback policy. The real chain always
+        # passes ``generate_configs``' resolved root down (#160).
+        if deploy_root is None:
+            deploy_root = current_root(RootKind.DEPLOY).path
+
+        config_templates = self.config.get("config_templates", {})
+        manifest = self._load_template_manifest(deploy_root)
+
+        for name, template in config_templates.items():
+            src = self.config_manager.get_vendor_config_path(template["src"])
+            dest = deploy_root / template["dest"]
+
+            if not src.exists():
+                continue
+
+            src_hash = _sha256(src)
+            if not dest.exists():
+                if self._copy_template(name, src, dest):
+                    manifest[name] = {"src": src_hash, "user": False}
+                continue
+
+            if name not in manifest:
+                # Pre-manifest deployment: record intent; never clobber here.
+                if _sha256(dest) == src_hash:
+                    manifest[name] = {"src": src_hash, "user": False}
+                else:
+                    # Existing dest differing from source may be user-modified
+                    # (bug #44): preserve it and pin it as user-owned so the
+                    # tool never auto-propagates over it.
+                    manifest[name] = {"src": src_hash, "user": True}
+                continue
+
+            entry = self._normalize_entry(manifest[name])
+            if entry["user"]:
+                # User-owned: never refresh, never clobber (bug #44).
+                continue
+
+            dest_hash = _sha256(dest)
+            if entry["src"] == src_hash:
+                # Source unchanged since last deploy; detect a post-deploy edit.
+                if dest_hash != entry["src"]:
+                    manifest[name] = {"src": src_hash, "user": True}
+            else:
+                # Vendored source changed: refresh only a pristine tool copy.
+                if dest_hash == entry["src"]:
+                    if self._copy_template(name, src, dest):
+                        manifest[name] = {"src": src_hash, "user": False}
+                else:
+                    # Destination diverged from the last deployed source.
+                    manifest[name] = {"src": src_hash, "user": True}
+
+        return self._save_template_manifest(manifest, deploy_root)
+
+    def missing_template_destinations(self, deploy_root: Root) -> list[Path]:
+        """Destinations the manifest tracks as tool-owned that are now missing (#190).
+
+        The manifest's *presence* used to be the whole freshness answer, so a
+        template deleted from ``.wl`` was never copied back: ``wl format`` then
+        silently skipped its hooks and ``wl lint`` failed with no way to heal
+        itself. A per-entry ``exists()`` is what the manifest can actually be
+        held to here.
+
+        Deliberately **not** a content/hash check: an existing destination stays
+        untouched, so the "a manifest means do not overwrite user edits" policy
+        is preserved. Entries pinned as ``user: true`` are skipped -- the tool
+        never re-propagates to them, and recreating them would make the check
+        permanently true (a fresh never-converging loop).
+
+        Args:
+            deploy_root: The root the destinations were deployed under.
+
+        Returns:
+            The missing destination paths, in manifest order.
+        """
+        deploy_path = deploy_root.path
+        manifest = self._load_template_manifest(deploy_path)
+        templates = self.config.get("config_templates", {})
+
+        missing: list[Path] = []
+        for name, value in manifest.items():
+            if self._normalize_entry(value)["user"]:
+                continue
+            template = templates.get(name)
+            if template is None:
+                # The template is no longer shipped; a missing dest is expected.
+                continue
+            dest = deploy_path / template["dest"]
+            if not dest.exists():
+                missing.append(dest)
+        return missing
+
+    @staticmethod
+    def _normalize_entry(value):
+        """Normalize a manifest entry (legacy scalar or v2 record) to v2."""
+        if isinstance(value, dict):
+            return {"src": value.get("src", ""), "user": bool(value.get("user", False))}
+        if isinstance(value, str):
+            return {"src": value, "user": False}
+        return {"src": "", "user": False}
+
+    def _copy_template(self, name: str, src: Path, dest: Path) -> bool:
+        # Refreshing a template intentionally overwrites the destination; the
+        # caller has already decided (see _copy_config_templates) that the
+        # destination is a pristine tool copy, not user-modified.
+        result = self.file_copier.copy_file(src, dest, overwrite=True)
+        if result.success:
+            log_debug_pair(f"✓ Copied {name} from template", f"✓ 从模板复制 {name}")
+            return True
+        log_info(f"Warning: Failed to copy {name}: {result.message}")
+        return False
+
+    def _manifest_path(self, deploy_root: Path) -> Path:
+        """The manifest path resolved under ``deploy_root`` when it is relative.
+
+        ``TEMPLATE_MANIFEST`` stays a relative class constant so constructors
+        never run git; an absolute override -- as the tests supply -- is used
+        unchanged.
+        """
+        manifest = self.TEMPLATE_MANIFEST
+        return manifest if manifest.is_absolute() else deploy_root / manifest
+
+    def _load_template_manifest(self, deploy_root: Path) -> dict[str, Any]:
+        import json
+
+        try:
+            return cast(
+                "dict[str, Any]",
+                json.loads(
+                    self._manifest_path(deploy_root).read_text(encoding="utf-8")
+                ),
+            )
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def _save_template_manifest(self, manifest: dict, deploy_root: Path) -> bool:
+        """Persist the manifest; report (not swallow) a save that failed.
+
+        The save is the only place that knows whether the manifest actually
+        landed, so its verdict is returned instead of logged and dropped (#201):
+        a caller that answers "refreshed" from ``config.json`` alone reports
+        success for a manifest the process could not write, and every later
+        command re-runs the rebuild. Returning False lets :meth:`generate_configs`
+        fail the sub-step and engage the cooldown -- including the
+        *missing-manifest-in-a-read-only-``.wl``* state, where no path probe can
+        answer for the write that will actually be attempted.
+        """
+        import json
+
+        path = self._manifest_path(deploy_root)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+        except OSError as e:
+            log_info_pair(
+                f"Warning: Failed to save template manifest: {e}",
+                f"警告: 保存模板 manifest 失败: {e}",
+            )
+            return False
+        return True
+
+
+def _same_file(a: Path, b: Path) -> bool:
+    """Whether two paths name the same file (tolerating symlinks)."""
+    try:
+        return a.resolve() == b.resolve()
+    except OSError:
+        return a == b
+
+
+def _sha256(path: Path) -> str:
+    import hashlib
+
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return ""

wl_cli/commands/initenv/components/project_structure/directory_creator.py

@@ -0,0 +1,184 @@
+"""Project directory structure creator."""
+
+import re
+from pathlib import Path
+
+from .....utils.logging import log_debug_pair, log_info_pair
+from ..config_manager import ConfigManager
+
+
+def normalize_project_name(project_name: str) -> str:
+    """Normalize a project name into a valid Python package identifier.
+
+    This is the single public implementation (#175) shared by directory
+    creation, template rendering and pyproject generation. It merges the
+    former ``_normalize_project_name`` and ``clean_python_package_name``
+    semantics: hyphens, dots, spaces and any other invalid characters
+    collapse to one underscore, leading/trailing underscores are stripped,
+    a leading digit is prefixed with ``_``, and an empty result falls back
+    to ``python_package``.
+    """
+    cleaned = re.sub(r"[^a-zA-Z0-9_]+", "_", project_name).strip("_")
+    if not cleaned:
+        return "python_package"
+    if cleaned[0].isdigit():
+        return f"_{cleaned}"
+    return cleaned
+
+
+# Backwards-compatible private spelling: one implementation behind both names.
+_normalize_project_name = normalize_project_name
+
+
+def _create_required_directories(project_name: str) -> None:
+    """Create required project directories."""
+    normalized_name = _normalize_project_name(project_name)
+    directories = [
+        "src",
+        f"src/{normalized_name}",
+        f"src/{normalized_name}/lib",  # 添加lib目录以支持Rust扩展
+        "tests",
+        "docs",
+        "examples",
+        "rust",
+        "dist",
+    ]
+
+    for directory in directories:
+        Path(directory).mkdir(parents=True, exist_ok=True)
+
+
+def _create_init_files(project_name: str) -> None:
+    """Create __init__.py files for Python packages."""
+    normalized_name = normalize_project_name(project_name)
+    directories = [
+        "src",
+        f"src/{normalized_name}",
+        f"src/{normalized_name}/lib",
+        "tests",
+        "docs",
+        "examples",
+    ]
+
+    for directory in directories:
+        if Path(directory).exists():
+            init_file = Path(directory) / "__init__.py"
+            if not init_file.exists():
+                init_file.touch()
+
+
+def _create_readme(project_name: str) -> None:
+    """Create README.md file if it doesn't exist or is empty."""
+    readme_file = Path("README.md")
+
+    # Only create README if it doesn't exist or is empty
+    should_create = (
+        not readme_file.exists()
+        or readme_file.read_text(encoding="utf-8").strip() == ""
+    )
+
+    if should_create:
+        # Try to get project description from config
+        try:
+            config_manager = ConfigManager()
+            description = config_manager.get(
+                "project_description", f"A Python project: {project_name}"
+            )
+        except Exception:
+            # Fallback to default description if config fails
+            description = f"A Python project: {project_name}"
+
+        readme_content = f"""# {project_name}
+
+{description}
+
+## Installation
+
+```bash
+pip install {project_name}
+```
+
+## Usage
+
+```python
+import {project_name}
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT
+"""
+
+        readme_file.write_text(readme_content, encoding="utf-8")
+        log_debug_pair("✓ README.md created successfully", "✓ README.md 创建成功")
+
+
+def setup_project_structure(project_name: str) -> None:
+    """Setup complete project structure by calling all required functions."""
+    _create_required_directories(project_name)
+    _create_init_files(project_name)
+    _create_readme(project_name)
+
+    # Copy and configure git hooks
+    from .hooks_manager import sync_hooks
+
+    sync_hooks()
+
+
+class DirectoryCreator:
+    """Create project directory structure."""
+
+    def create_structure(self, project_name: str, workspace_mode: bool = False) -> None:
+        """Create main project directory structure.
+
+        Args:
+            project_name: Name of the project
+            workspace_mode: If True, create workspace layout (packages/{name}/)
+                            If False, create flat layout (src/{name}/)
+        """
+        if workspace_mode:
+            _create_workspace_directories(project_name)
+        else:
+            _create_required_directories(project_name)
+            _create_init_files(project_name)
+
+        log_info_pair("✓ Project structure created successfully", "✓ 项目结构创建成功")
+
+
+def _create_workspace_directories(project_name: str) -> None:
+    """Create workspace-style project directories under packages/{name}/."""
+    normalized_name = normalize_project_name(project_name)
+    package_dir = f"packages/{normalized_name}"
+    directories = [
+        package_dir,
+        f"{package_dir}/src",
+        f"{package_dir}/src/{normalized_name}",
+        f"{package_dir}/src/{normalized_name}/lib",
+        f"{package_dir}/rust",
+        f"{package_dir}/rust/src",
+        f"{package_dir}/tests",
+        "docs",
+    ]
+
+    for directory in directories:
+        Path(directory).mkdir(parents=True, exist_ok=True)
+
+    # Create __init__.py files for package
+    init_dirs = [
+        f"{package_dir}/src",
+        f"{package_dir}/src/{normalized_name}",
+        f"{package_dir}/src/{normalized_name}/lib",
+        f"{package_dir}/tests",
+    ]
+    for directory in init_dirs:
+        init_file = Path(directory) / "__init__.py"
+        if not init_file.exists():
+            init_file.touch()

wl_cli/commands/initenv/components/project_structure/hook_source.py

@@ -0,0 +1,110 @@
+"""The one place that says where the git-hook templates live (#162).
+
+Three spellings of "the vendored hooks template directory" used to coexist --
+the deployment call, the staleness gate's private accessor, and a CWD-relative
+literal in ``clean lfs`` -- so a layout change could be made in one place and
+silently missed in another. :func:`locate_hook_source` is now the only
+definition; every consumer takes its directories from the value it returns.
+
+**Platform policy, made explicit.** All platforms deploy the ``unix`` templates
+(Git Bash executes them on Windows). That used to be expressed only by passing
+the already platform-qualified key ``hooks/unix`` to
+:meth:`ConfigManager.get_vendor_config_path`, whose platform substitution fires
+only for keys *without* a ``/win`` or ``/unix`` segment -- i.e. the decision was
+encoded in the shape of a string, and the one place that *did* pass the bare
+``hooks`` key silently resolved to ``hooks/win`` on Windows. Here the policy is
+the point of the module: the key is ``hooks/unix`` on every platform, and a
+missing unix directory is reported as :attr:`HookSource.template_missing` -- it
+never falls back to the bare key, which would put a different template set
+behind the same locator.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .....utils.root import Root
+from ..config_manager import ConfigManager
+
+#: The vendored template subtree every platform deploys from. Explicitly
+#: unix-qualified so ``get_vendor_config_path``'s platform substitution -- which
+#: only fires for keys without a ``/win`` or ``/unix`` segment -- never rewrites
+#: it. See the module docstring for why that is the policy, not an accident.
+_HOOK_TEMPLATE_KEY = "hooks/unix"
+
+#: There is no shared-config literal any more (ADR-0009 supersedes ADR-0005):
+#: ``wl`` writes a **worktree-scoped** ``core.hooksPath``, and that value is
+#: derived from the deploy root by :func:`locate_hook_source` -- see
+#: :attr:`HookSource.worktree_hooks_path`. Keeping one derived value for both
+#: the write side and the comparison side is what stops them drifting apart.
+
+
+@dataclass(frozen=True)
+class HookSource:
+    """Where hooks come from and where they go, in one value (#162).
+
+    Frozen because it is a snapshot: fields are read once at construction and
+    every later read returns that same answer, so one consumer cannot observe
+    the filesystem changing underneath it. That is why
+    :attr:`template_missing` is an ordinary field -- probed **once**, here at
+    construction -- rather than a property that re-stats the filesystem on
+    every access. ``apply_hook_sync`` branches on the flag and then warns on it;
+    a property would let a template directory that appeared or vanished in
+    between flip one read and not the other, producing either a silently
+    skipped copy/prune pass (branch saw "missing", warning saw "present") or a
+    prune pass off a template it then reports as missing (the reverse).
+    ``evaluate_hooks`` and ``apply_hook_sync`` call :func:`locate_hook_source`
+    independently, so each gets its own snapshot; the guarantee here is
+    consistency *within* one call, not sameness across the two.
+    """
+
+    #: Vendored template directory (``hooks/unix``) -- the same on every
+    #: platform, because Git Bash runs the unix hooks on Windows too.
+    template_dir: Path
+    #: The deploy root's ``.wl/hooks`` -- the directory ``core.hooksPath``
+    #: resolves to in the checkout being deployed into.
+    deploy_dir: Path
+    #: The **absolute** path written to the worktree-scoped ``core.hooksPath``
+    #: and compared against it (ADR-0009). Derived from the same deploy root as
+    #: :attr:`deploy_dir`, so "where the hooks were deployed" and "where the
+    #: pointer says they are" cannot disagree. Consumed by ``hooks_manager`` on
+    #: both the write side (``_configure_git_hooks_path``) and the comparison
+    #: side (``hooks_path_is_stale``), so this object really is the value's only
+    #: source.
+    #:
+    #: Absolute on purpose: the value no longer lives in the repository's shared
+    #: ``.git/config`` (where one checkout's absolute path would be invalid in
+    #: every other checkout) but in the *per-worktree* config, which is removed
+    #: together with the worktree it describes. ``as_posix()`` keeps the
+    #: forward-slash spelling git accepts on every platform.
+    worktree_hooks_path: str
+    #: Whether :attr:`template_dir` was absent when this snapshot was taken.
+    #: The explicit "template missing" result (#162): it exists so callers can
+    #: warn (or skip) instead of :func:`locate_hook_source` silently
+    #: re-resolving to another platform's directory -- the ``hooks/win``
+    #: fallback the bare ``hooks`` key used to produce on Windows.
+    template_missing: bool
+
+
+def locate_hook_source(deploy_root: Root) -> HookSource:
+    """Locate the hook source and deployment target for *deploy_root*.
+
+    ``deploy_root`` is the root the hooks deploy under, supplied as a value by
+    the caller (the root module's ``DEPLOY`` kind, resolved once at the public
+    entry) rather than re-derived here -- a default would let a forgotten
+    argument silently fall back to the process CWD (#160).
+
+    A missing template directory is *not* an error: the result carries
+    :attr:`HookSource.template_missing`, so the read-only staleness gate can
+    keep a "cannot tell, do not force a sync" verdict and the applier can warn
+    (and must not read the missing directory as "the template no longer ships
+    these hooks"). The flag is probed here, once, for the same reason every
+    other field is: the result is a snapshot. Nothing is created or written
+    here.
+    """
+    template_dir = ConfigManager().get_vendor_config_path(_HOOK_TEMPLATE_KEY)
+    return HookSource(
+        template_dir=template_dir,
+        deploy_dir=deploy_root.hooks_dir(),
+        worktree_hooks_path=deploy_root.hooks_dir().as_posix(),
+        template_missing=not template_dir.is_dir(),
+    )