py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/wl_dir_updater.py

@@ -0,0 +1,1440 @@
+#!/usr/bin/env python3
+"""
+Utility for checking and updating the .wl directory based on version compatibility.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import time
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from .logging import log_info_pair, log_warning_pair
+from .root import Root, RootKind
+from .root_fallback import current_context, current_root
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ..commands.initenv.components.project_structure.hooks_manager import (
+        HookSyncState,
+    )
+
+#: Cooldown (seconds) before the heavy .wl sync is retried after a failure.
+_UPDATE_FAILED_COOLDOWN_SECONDS = 3600
+
+
+def _project_wl_dir(project_root: Root) -> Path:
+    """The workspace/project ``.wl`` at an already-resolved project root (#160).
+
+    One of the two anchors :func:`check_and_update_wl_dir` consults to decide
+    whether a checkout is wl-managed at all. In the ``项目根 != git 根`` layouts
+    (#95 / #96) the workspace ``.wl`` lives here while the hooks leg belongs to
+    the deploy root below.
+
+    The root is a resolved value handed in -- :func:`current_root` for the
+    hot-path check, or the context's ``project`` inside the sync. This helper no
+    longer derives a root of its own, so a forgotten value cannot silently fall
+    back to the process CWD. The ``.wl`` spelling lives on
+    :meth:`~wl_cli.utils.root.Root.wl_dir` (#118).
+    """
+    return project_root.wl_dir()
+
+
+def _deploy_wl_dir(deploy_root: Root) -> Path:
+    """The ``.wl`` at an already-resolved hooks deploy root (#160).
+
+    This is where the self-sync reads/writes ``config.json`` and deploys the
+    hooks leg and config templates, so those artifacts stay inside the git work
+    tree (#95 / #96). In the regular layout -- project root == git work tree root
+    -- it is the same directory :func:`_project_wl_dir` returns.
+    """
+    return deploy_root.wl_dir()
+
+
+def _same_path(a: Path, b: Path) -> bool:
+    """Whether two paths point at the same directory (tolerating symlinks)."""
+    try:
+        return a.resolve() == b.resolve()
+    except Exception:
+        return a == b
+
+
+def _migrate_legacy_config_if_needed(
+    deploy_wl_dir: Path, legacy_wl_dir: Path | None
+) -> None:
+    """Carry a pre-#95 / #96 ``config.json`` over to the deploy root.
+
+    Before the hooks leg was anchored at the git work-tree root, ``.wl`` lived at
+    the project root. In a divergent layout (an outer workspace ``.wl``
+    above a member repo, or a project below the git root) that is *not* the
+    deploy root, so the deploy root would otherwise mint a fresh default and
+    silently abandon the user's settings. When the deploy root has no
+    ``config.json`` yet and a legacy one was located, copy it across -- once --
+    and say so.
+
+    ``legacy_wl_dir`` is resolved from the *invocation* directory by the caller
+    (through the root module's ``LEGACY`` kind) and never re-derived here: re-deriving it now
+    would resolve to the deploy root itself -- its ``.wl`` exists by this point
+    -- and silently skip the migration, which is exactly the F2 residual this
+    parameter exists to close.
+
+    The legacy ``.wl`` directory itself is deliberately **retained**: deleting a
+    user directory is never this tool's call, and nothing reads it any more --
+    its ``config.json`` was migrated above and its hook files are inert
+    (``core.hooksPath`` now points at the deploy root). Retention is not silent,
+    though: the report below names the exact legacy path and tells the user how
+    to remove it once they are satisfied nothing else there is still wanted.
+
+    That report *is* the adjudication of the retained-legacy-``.wl`` policy
+    (#111, transferred from #103 item 5): keep the directory, but make the keep
+    actionable. It is verifiable behaviour, not a comment that says "known" --
+    reverting the report to the bare inert-hooks note makes
+    ``test_retained_legacy_wl_is_reported_with_actionable_cleanup_guidance``
+    fail. Auto-cleanup is deliberately *not* the ruling: it would silently
+    delete a user directory, which the backward-compatibility contract forbids.
+    """
+    target = deploy_wl_dir / "config.json"
+    if target.exists():
+        return  # the deploy root already owns the config
+
+    if legacy_wl_dir is None or _same_path(legacy_wl_dir, deploy_wl_dir):
+        return
+
+    legacy_config = legacy_wl_dir / "config.json"
+    if not legacy_config.is_file():
+        return
+
+    try:
+        # copyfile, not copy2: the mode is applied explicitly just below, so the
+        # target can keep the source's bits *minus* the read-only trap. copy2's
+        # verbatim mode is what broke a 0444 legacy config.json: the migrated
+        # target stayed unwritable, so the version stamp could never advance --
+        # rewriting it makes _update_config_version() catch OSError and hand off
+        # to get_config_manager().set("version", ...), whose own write
+        # (ConfigSaver.save: open(..., "w") then "except OSError: pass",
+        # config/core.py) swallows the failure -- leaving the stamp stale and
+        # every `wl` re-running the full sync (#104 N2).
+        shutil.copyfile(legacy_config, target)
+    except OSError as e:
+        log_info_pair(
+            f"Warning: could not migrate {legacy_config} to {target}: {e}",
+            f"警告：无法将 {legacy_config} 迁移到 {target}：{e}",
+        )
+        return
+
+    # Carry the source's permission bits (a private 0600 legacy config stays
+    # 0600 rather than becoming 0644 under the umask) but always keep the
+    # owner-write bit: the target is ours, and _update_config_version() has to
+    # rewrite it (#104 N2).
+    try:
+        target.chmod(stat.S_IMODE(legacy_config.stat().st_mode) | stat.S_IWUSR)
+    except OSError as e:
+        # The copy above already succeeded, so the config *did* migrate -- do not
+        # claim otherwise. But the target may be unwritable, in which case the
+        # version stamp cannot advance here and will not be retried (the early
+        # return above skips a target that already exists), so name that
+        # consequence instead of leaving it to be discovered later.
+        log_info_pair(
+            f"Warning: migrated {legacy_config} to {target}, but could not make it "
+            f"writable ({e}); until {target} is writable the .wl version stamp "
+            "will not advance and the full sync will re-run on every command.",
+            f"警告：已将 {legacy_config} 迁移到 {target}，但无法使其可写（{e}）；"
+            f"在 {target} 可写之前，.wl 版本戳不会前进，每次命令都会重跑全量同步。",
+        )
+        return
+
+    log_info_pair(
+        f"✓ Migrated wl config to the repository root: {legacy_config} -> {target}",
+        f"✓ 已将 wl 配置迁移到仓库根：{legacy_config} -> {target}",
+    )
+    log_info_pair(
+        f"Note: the legacy .wl at {legacy_wl_dir} is deliberately retained: its "
+        f"config was migrated to {target} above and its hook files are inert, so "
+        "nothing reads it any more -- and wl never deletes a user directory. If "
+        f"you no longer need it, remove it yourself, e.g. `rm -rf {legacy_wl_dir}`.",
+        f"注意：旧 .wl 目录 {legacy_wl_dir} 为有意保留：其配置已迁移到上方的 "
+        f"{target}，钩子文件亦已失效，已不再被读取；wl 不会自行删除用户目录。"
+        f"若确认不再需要，可自行清理，例如：`rm -rf {legacy_wl_dir}`。",
+    )
+
+
+def check_and_update_wl_dir() -> None:
+    """
+    Check if .wl directory version is compatible with current wl version.
+    If not, update the .wl directory.
+
+    Runs on every `wl` command (hot path): short-circuits cheaply when the
+    .wl directory is current, and skips the heavy sync entirely if a previous
+    attempt failed recently (see _update_failed_marker).
+
+    The failure marker is cleared only when the sync fully succeeded; any
+    partial sub-step failure keeps it (or writes it) so the cooldown engages.
+    """
+    from wl_cli import __version__
+
+    current_version = __version__
+
+    # Hot path first (#160/F3): answer "is this a wl project at all?" with the
+    # two single-root lookups, before anything walks the legacy chain. A full
+    # ``RootContext`` also resolves LEGACY, whose walk shells out to git; paying
+    # that in every *non-wl* directory, on every ``wl`` command, would take the
+    # hot path from one ``git rev-parse`` to two. Both lookups are memoised by
+    # the root module for this start, so the context built below reuses them.
+    #
+    # A checkout is wl-managed when `.wl` exists at either anchor: the deploy
+    # root (git work-tree root, else project root) or the project root. In the
+    # regular layout they coincide; the two differ in the #95 / #96 layouts --
+    # an outer workspace `.wl` above a member repo (the project root has `.wl`,
+    # the freshly-visited deploy root does not yet) or a sub-package below the
+    # git root (the deploy root has `.wl`, the project root does not).
+    deploy_root = current_root(RootKind.DEPLOY)
+    project_root = current_root(RootKind.PROJECT)
+    if (
+        not _deploy_wl_dir(deploy_root).exists()
+        and not _project_wl_dir(project_root).exists()
+    ):
+        # No .wl at either anchor: not a wl project, nothing to update
+        return
+
+    # Managed checkout: resolve the three roots **once** (#160). The sync's
+    # deploy root and legacy point come from this one value, instead of each
+    # layer re-deriving a root from the process CWD -- the per-layer
+    # ``Root | None = None`` defaults that made a forgotten argument silently
+    # fall back to the CWD.
+    #
+    # The legacy point is resolved from the *invocation* directory, before the
+    # deploy `.wl` is created: once it exists, the PROJECT walk resolves to the
+    # deploy root itself and the old location becomes invisible. The previous
+    # code resolved it after a mid-sync chdir and skipped the migration silently
+    # (F2 residual). LEGACY's bounds (volume-root ceiling, system-scope
+    # blacklist, the explicit ``<home>/.wl`` refusal) come from the root module
+    # (#118); the context calls no legacy walk of its own.
+    context = current_context()
+
+    # The sync behaves *as if run from the deploy root* -- not the CWD and not
+    # the project root -- because that is where git resolves the relative
+    # ``core.hooksPath`` and runs hooks from, and where the whole ``.wl`` leg
+    # lives (#95 / #96). That anchoring is now delivered *as a value*:
+    # ``deploy_root`` is handed to every downstream step, which builds its ``.wl``
+    # paths from it instead of re-deriving a root from the process CWD. The
+    # process CWD is never touched (the old mid-sync ``os.chdir`` and its
+    # ``finally`` restore are gone), so every relative path in this process keeps
+    # resolving against the user's own directory.
+    _run_self_sync(current_version, context.legacy_wl_dir, context.deploy)
+
+
+def _run_self_sync(
+    current_version: str, legacy_wl_dir: Path | None, deploy_root: Root
+) -> None:
+    """Body of :func:`check_and_update_wl_dir`, anchored at *deploy_root*.
+
+    ``deploy_root`` is the value every downstream step anchors its ``.wl``
+    lookups on; the sync no longer chdirs to it, so the root has to be handed
+    down explicitly rather than re-derived from the process CWD.
+
+    ``legacy_wl_dir`` is the pre-#95 / #96 deploy point resolved from the
+    invocation directory through the root module's ``LEGACY`` kind; it is
+    threaded through untouched so the config migration never has to re-derive it.
+
+    The failure marker is cleared only when the sync fully succeeded; any
+    partial sub-step failure keeps it (or writes it) so the cooldown engages.
+    """
+    # Hot path: don't retry a failed heavy sync on every command
+    if _update_failed_recently(deploy_root):
+        log_info_pair(
+            "Skipping .wl sync (previous attempt failed recently)...",
+            "正在跳过 .wl 同步（上次尝试失败不久）...",
+        )
+        return
+
+    try:
+        ok = sync_wl_dir(current_version, legacy_wl_dir, deploy_root)
+    except Exception as e:
+        _mark_update_failed(deploy_root)
+        log_info_pair(
+            f"Warning: .wl sync failed: {e}",
+            f"警告：.wl 同步失败：{e}",
+        )
+        return
+
+    # Only a fully successful sync clears the marker. A partial failure leaves
+    # (or writes) .update_failed so the cooldown engages and the config.json
+    # version stamp stays stale, forcing a retry after the cooldown.
+    if ok:
+        _clear_update_failed(deploy_root)
+    else:
+        _mark_update_failed(deploy_root)
+
+
+def sync_wl_dir(
+    current_version: str,
+    legacy_wl_dir: Path | None = None,
+    deploy_root: Root | None = None,
+) -> bool:
+    """Single orchestration entry: decide what needs syncing and do it.
+
+    Full update (templates + hooks + version bump) runs when the stamped
+    version is missing or older than the current wl version. When the version
+    is current, only cheap staleness checks run.
+
+    ``legacy_wl_dir`` is the pre-#95 / #96 deploy point, resolved from the
+    invocation directory by :func:`check_and_update_wl_dir` and passed down to
+    the config migration; it defaults to None for direct callers (e.g. tests),
+    which therefore never migrate.
+
+    ``deploy_root`` is the root every ``.wl`` lookup below is anchored on. It is
+    passed down as a value from :func:`check_and_update_wl_dir` (which no longer
+    chdirs to it); direct callers may omit it, and this single-root entry then
+    resolves exactly the one root it needs through
+    :func:`~wl_cli.utils.root_fallback.current_root` (#160) -- never a
+    re-derivation deeper in the chain.
+
+    Returns:
+        True when every executed sub-step succeeded (or nothing needed doing);
+        False when a sub-step failed. On failure the caller is responsible for
+        keeping/writing the .update_failed marker so the cooldown engages.
+    """
+    if deploy_root is None:
+        deploy_root = current_root(RootKind.DEPLOY)
+    wl_dir = deploy_root.wl_dir()
+    config_file = wl_dir / "config.json"
+
+    if not config_file.exists():
+        log_info_pair(
+            "Updating .wl directory (missing config.json)...",
+            "正在更新 .wl 目录（缺少 config.json）...",
+        )
+        return _update_wl_directory(legacy_wl_dir, deploy_root)
+
+    try:
+        with open(config_file, encoding="utf-8") as f:
+            config = json.load(f)
+
+        wl_dir_version = config.get("version")
+        if not wl_dir_version:
+            log_info_pair(
+                "Updating .wl directory (missing version in config)...",
+                "正在更新 .wl 目录（配置中缺少版本）...",
+            )
+            return _update_wl_directory(legacy_wl_dir, deploy_root)
+
+        if compare_versions(wl_dir_version, current_version) < 0:
+            log_info_pair(
+                f"Updating .wl directory from version {wl_dir_version} to {current_version}...",
+                f"正在将 .wl 目录从版本 {wl_dir_version} 更新到 {current_version}...",
+            )
+            return _update_wl_directory(legacy_wl_dir, deploy_root)
+        else:
+            # Evaluate each stale flag EXACTLY ONCE per sync_wl_dir call. The
+            # template and hook paths are decoupled (generate_configs never
+            # re-syncs hooks), so the flags cannot change mid-update.
+            from ..commands.initenv.components.project_structure.hooks_manager import (
+                evaluate_hooks,
+            )
+
+            # Evaluated here, once, and handed to the sub-step as a value: the
+            # sync below consumes the path verdict instead of probing git again
+            # (#161).
+            hooks_state = evaluate_hooks(deploy_root)
+            templates_stale = _templates_need_sync(deploy_root)
+
+            # Light path: each stale sub-step is attempted independently, then
+            # the shared helper owns the partial-failure accounting -- which
+            # sub-step failed, the .update_failed marker, and the bilingual
+            # report -- the very same helper the full update uses.
+            return _apply_substeps(
+                partial(_refresh_templates_substep, templates_stale, deploy_root),
+                partial(_sync_hooks_substep, hooks_state, deploy_root),
+                deploy_root=deploy_root,
+            )
+    except (json.JSONDecodeError, OSError, ValueError) as e:
+        log_info_pair(
+            f"Updating .wl directory (error reading config.json: {e})...",
+            f"正在更新 .wl 目录（读取 config.json 错误：{e}）...",
+        )
+        return _update_wl_directory(legacy_wl_dir, deploy_root)
+
+
+def _update_failed_marker(deploy_root: Root) -> Path:
+    """Path of the marker written when a heavy .wl sync fails.
+
+    ``deploy_root`` is required: it is the value the public entry resolved
+    (#160), never a per-call re-derivation from the process CWD.
+    """
+    return deploy_root.wl_dir() / ".update_failed"
+
+
+def _update_failed_recently(deploy_root: Root) -> bool:
+    """Whether a sync failure marker is fresh (within the cooldown window)."""
+    marker = _update_failed_marker(deploy_root)
+    if not marker.exists():
+        return False
+    try:
+        return (time.time() - marker.stat().st_mtime) < _UPDATE_FAILED_COOLDOWN_SECONDS
+    except OSError:
+        return False
+
+
+def _mark_update_failed(deploy_root: Root) -> None:
+    """Record the cooldown marker, or say out loud that it could not be (#201 F3).
+
+    Swallowing the ``OSError`` here left the worst failure mode silent: a ``.wl``
+    directory the process cannot write (``chmod 000``) also blocks this marker,
+    so the cooldown never engages and *every* command retries the broken sync
+    with no end state. When the marker cannot be written the cooldown is
+    unavailable, so the warning is the only remaining signal -- say which
+    directory to repair instead of passing.
+    """
+    marker = _update_failed_marker(deploy_root)
+    try:
+        marker.write_text(str(int(time.time())))
+    except OSError as e:
+        log_warning_pair(
+            f"Warning: could not record the .wl sync failure marker {marker} ({e}); "
+            "the cooldown cannot engage, so the sync will be retried on every "
+            f"command until {marker.parent} is writable.",
+            f"警告：无法写入 .wl 同步失败标记 {marker}（{e}）；冷却无法生效，"
+            f"在 {marker.parent} 可写之前每次命令都会重试同步。",
+        )
+
+
+def _clear_update_failed(deploy_root: Root) -> None:
+    try:
+        _update_failed_marker(deploy_root).unlink()
+    except OSError:
+        pass
+
+
+def _apply_substeps(*substeps: Callable[[], bool], deploy_root: Root) -> bool:
+    """Run the sync sub-steps and own the partial-failure accounting.
+
+    Both the light (staleness) path of :func:`sync_wl_dir` and the full
+    :func:`_update_wl_directory` run a sequence of sub-steps that each report
+    success with a bool. This is the single place that decides whether *any* of
+    them failed, writes the ``.update_failed`` marker when one did, and emits
+    the bilingual "partially updated" report -- and it does so *after* every
+    sub-step has run (a failed step never short-circuits a later one), so the
+    cooldown engages and the next command retries (regression #45).
+
+    Args:
+        *substeps: Sub-steps to run in order. Each has already logged what it is
+            about to do and reports its own failure; it returns True on success
+            and False on failure.
+        deploy_root: The deploy root the failure marker is anchored on, threaded
+            in as a value (the caller no longer chdirs to it).
+
+    Returns:
+        True when every sub-step succeeded; False when one or more failed (the
+        failure marker has been written).
+    """
+    ok = True
+    for substep in substeps:
+        if not substep():
+            ok = False
+
+    if not ok:
+        _mark_update_failed(deploy_root)
+        log_info_pair(
+            "Warning: .wl directory partially updated; sync will retry after "
+            "the cooldown.",
+            "警告：.wl 目录部分更新失败；将在冷却后重试。",
+        )
+    return ok
+
+
+def _refresh_templates_substep(stale: bool, deploy_root: Root) -> bool:
+    """Light-path sub-step: refresh templates when the cheap check flagged them.
+
+    A flag of False means there is nothing to do, which counts as success so the
+    shared accounting in :func:`_apply_substeps` only reacts to real failures.
+    """
+    if not stale:
+        return True
+    log_info_pair(
+        "Updating .wl templates (template migration pending)...",
+        "正在更新 .wl 模板（模板迁移待处理）...",
+    )
+    return _update_templates_directory(deploy_root)
+
+
+def _sync_hooks_substep(state: HookSyncState, deploy_root: Root) -> bool:
+    """Light-path sub-step: sync hooks when the cheap check flagged them.
+
+    ``state`` is the value :func:`sync_wl_dir` already evaluated; it is handed
+    to :func:`_update_hooks_directory` rather than re-derived here, so the light
+    path probes git exactly once (#161).
+
+    A state with ``needs_sync`` False means there is nothing to do, which counts
+    as success so the shared accounting in :func:`_apply_substeps` only reacts
+    to real failures.
+    """
+    if not state.needs_sync:
+        return True
+    log_info_pair(
+        "Updating .wl hooks (stale/missing hook or bad core.hooksPath detected)...",
+        "正在更新 .wl 钩子（检测到钩子过期/缺失或 core.hooksPath 失效）...",
+    )
+    return _update_hooks_directory(state, deploy_root)
+
+
+def _generate_configs_substep(setup_handler: Any, deploy_root: Root) -> bool:
+    """Full-path sub-step: (re)generate the vendored .wl configs.
+
+    Returns:
+        True when generation succeeded -- that is, ``.wl/config.json`` exists
+        afterwards; False when it raised or produced no config. The shared
+        accounting in :func:`_apply_substeps` then writes the failure marker and
+        the caller leaves the config.json version stamp stale. Taking the
+        generator's own verdict (instead of "it did not raise") is what stops a
+        half-built ``.wl`` -- templates deployed, no config -- from being
+        reported as a successful first sync (#202).
+    """
+    try:
+        # Both regeneration paths share this preparation: set a non-object
+        # manifest aside and refuse a rebuild whose save would fail silently
+        # (#201 F1/F2/F3).
+        if not _prepare_template_manifest_for_rebuild(deploy_root):
+            return False
+        return bool(setup_handler.config_generator.generate_configs(deploy_root))
+    except Exception as e:
+        log_info_pair(
+            f"Warning: Failed to generate .wl configs: {e}",
+            f"警告：生成 .wl 配置失败：{e}",
+        )
+        return False
+
+
+def _templates_need_sync(deploy_root: Root) -> bool:
+    """Cheap check: are the tracked config templates still on disk?
+
+    A missing template manifest means a one-time migration is pending --
+    existing .wl config templates must be refreshed to the current source
+    (propagates template bug fixes to already-initialized projects).
+
+    A *present* manifest is not the same answer, though (#190). It only says
+    "these files were deployed once"; a template deleted from ``.wl`` afterwards
+    (hand cleanup, a botched checkout) stayed missing forever, so ``wl format``
+    printed "skipping pre-commit hooks" and went green while ``wl lint`` failed
+    with no way to self-heal. Once a manifest exists, every destination it tracks
+    is checked with a plain ``exists()`` -- no hashing, so the per-command hot
+    path stays cheap and a converged checkout keeps costing the same.
+
+    Destinations pinned ``user: true`` are deliberately skipped: the tool never
+    re-propagates to them, so requiring them would make this check permanently
+    true -- trading one never-converging loop for another.
+
+    A manifest that is *present but unreadable* is not evidence of freshness
+    either (#197). ``ConfigGenerator._load_template_manifest`` answers ``{}`` for
+    both "no manifest" and "manifest did not parse", so a truncated or
+    non-object ``.templates.json`` used to reach this function as an empty
+    manifest -- "zero destinations missing" -- and the refresh branch below was
+    unreachable for the very corruption it was written for. The manifest is
+    therefore classified here, before the generator sees it: a corrupt one is
+    reported (``log_warning_pair``) and answered "stale", so the next sync
+    rebuilds it through ``generate_configs`` (which rewrites the manifest).
+    """
+    from wl_cli.commands.initenv.components.project_structure.config_generator import (
+        ConfigGenerator,
+        template_manifest_path,
+    )
+
+    manifest_path = template_manifest_path(deploy_root)
+    if not manifest_path.exists():
+        # Missing is a normal migration state, deliberately not a warning.
+        return True
+
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        log_warning_pair(
+            f"Warning: template manifest {manifest_path} is unreadable ({e}); "
+            "rebuilding it",
+            f"警告：模板 manifest {manifest_path} 无法读取（{e}）；正在重建",
+        )
+        return True
+
+    if not isinstance(manifest, dict):
+        log_warning_pair(
+            f"Warning: template manifest {manifest_path} is not a JSON object; "
+            "rebuilding it",
+            f"警告：模板 manifest {manifest_path} 不是 JSON 对象；正在重建",
+        )
+        return True
+
+    try:
+        return bool(ConfigGenerator().missing_template_destinations(deploy_root))
+    except Exception as e:
+        # Any other check failure is still not evidence of freshness: refresh
+        # rather than let an error silently answer "up to date", and say so.
+        log_warning_pair(
+            f"Warning: could not check template destinations ({e}); refreshing",
+            f"警告：无法检查模板目标文件（{e}）；正在刷新",
+        )
+        return True
+
+
+def _preserve_corrupt_manifest(manifest_path: Path, raw: bytes) -> Path:
+    """Write *raw* into the first free ``.corrupt`` / ``.corrupt.N`` name (#201).
+
+    The name is claimed with ``O_CREAT | O_EXCL``, so two updaters can never
+    select the same file: whichever loses the race moves on to the next free
+    number instead of overwriting the first scene's evidence. Existence is
+    therefore never checked separately from the claim -- ``exists()`` followed
+    by a write is exactly the non-atomic pair this replaces.
+
+    The bytes written are the *snapshot that was parsed*, not whatever the
+    manifest path holds now: a concurrent updater may already have replaced the
+    corrupt file with a rebuilt valid manifest, and that manifest must never be
+    filed away as corrupt evidence.
+
+    Raises:
+        OSError: no free name could be claimed, or the bytes could not be
+            written (the claimed placeholder is removed first).
+    """
+    index = 0
+    while True:
+        suffix = ".corrupt" if index == 0 else f".corrupt.{index}"
+        candidate = manifest_path.with_name(manifest_path.name + suffix)
+        try:
+            fd = os.open(candidate, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except FileExistsError:
+            index += 1
+            continue
+        try:
+            with os.fdopen(fd, "wb") as handle:
+                handle.write(raw)
+        except OSError:
+            candidate.unlink(missing_ok=True)
+            raise
+        return candidate
+
+
+def _quarantine_unusable_template_manifest(manifest_path: Path) -> None:
+    """Set aside a manifest that a rebuild could not rewrite in place (#197).
+
+    ``ConfigGenerator`` treats an *unparsable* manifest as ``{}`` and rewrites
+    it, but valid JSON of the wrong shape (``[]``, ``"x"``) reaches it as a
+    non-mapping and every entry write raises -- so the corrupt file would make
+    every rebuild fail, one cooldown at a time, forever. Moving it aside lets
+    ``generate_configs`` start from a clean slate; the old bytes are kept next
+    to it as ``.templates.json.corrupt`` instead of being silently destroyed.
+
+    Repeated or concurrent corruption must not eat its own evidence (#201): the
+    backup name is claimed atomically by :func:`_preserve_corrupt_manifest`, and
+    the corrupt bytes are copied rather than the manifest path moved, so a
+    scene preserved by one updater cannot be replaced by another.
+    """
+    if not manifest_path.exists():
+        return
+
+    try:
+        raw = manifest_path.read_bytes()
+    except OSError:
+        # Unreadable is answered "stale" by the caller; nothing to preserve.
+        return
+
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        # The generator already handles these as "empty manifest"; no action.
+        return
+
+    if isinstance(parsed, dict):
+        return
+
+    try:
+        backup = _preserve_corrupt_manifest(manifest_path, raw)
+    except OSError as e:
+        log_warning_pair(
+            f"Warning: could not set aside unusable template manifest "
+            f"{manifest_path} ({e})",
+            f"警告：无法移走不可用的模板 manifest {manifest_path}（{e}）",
+        )
+        return
+
+    try:
+        manifest_path.unlink()
+    except FileNotFoundError:
+        # A concurrent updater already removed it; our copy is still evidence.
+        pass
+    except OSError as e:
+        backup.unlink(missing_ok=True)
+        log_warning_pair(
+            f"Warning: could not remove unusable template manifest "
+            f"{manifest_path} ({e})",
+            f"警告：无法移除不可用的模板 manifest {manifest_path}（{e}）",
+        )
+        return
+
+    log_warning_pair(
+        f"Warning: template manifest {manifest_path} was not a JSON object; "
+        f"moved to {backup} and rebuilding",
+        f"警告：模板 manifest {manifest_path} 不是 JSON 对象；已移至 {backup} 并重建",
+    )
+
+
+def _template_manifest_is_writable(manifest_path: Path) -> bool:
+    """Whether a present template manifest can be rewritten in place (#201 F3).
+
+    ``ConfigGenerator._save_template_manifest`` used to swallow the ``OSError``
+    from its write, and ``generate_configs`` only reported whether
+    ``config.json`` exists -- so a manifest the process cannot write
+    (``chmod 000``) looked like a *successful* refresh. The manifest stayed
+    stale, ``_templates_need_sync`` answered "stale" again, and every ``wl``
+    command re-ran the rebuild with no cooldown to bound it. Probing write
+    access up front turns that silent loop into a failed sync sub-step: a
+    visible warning plus the ``.update_failed`` cooldown.
+
+    A missing manifest answers "writable" here on purpose: the file is created
+    by the save that follows, and a directory probe could not answer for that
+    write reliably (root/ACL/NFS ignores or masks permission bits, and the
+    probe is TOCTOU anyway). That state is covered at the save instead --
+    ``_save_template_manifest`` now returns its outcome and
+    ``generate_configs`` propagates it (#201), so a read-only ``.wl`` with no
+    manifest fails the sub-step and engages the cooldown too. This probe never
+    raises.
+    """
+    if not manifest_path.exists():
+        return True
+    return os.access(manifest_path, os.W_OK)
+
+
+def _prepare_template_manifest_for_rebuild(deploy_root: Root) -> bool:
+    """Make the template manifest rebuildable in place.
+
+    Shared by both paths that regenerate configs -- the light staleness path
+    (:func:`_update_templates_directory`) and the full version-outdated path
+    (:func:`_generate_configs_substep`) -- because the quarantine used to run
+    only on the light one (#201 F2): a non-object manifest on an outdated
+    version made ``generate_configs`` raise, the sub-step reported failure and
+    the sync wrote ``.update_failed``, so the very corruption the quarantine
+    exists for was never set aside there.
+
+    The manifest path is resolved once here and handed to both helpers, so the
+    classification and the writability probe cannot disagree after a mid-sync
+    replace, and the manifest is not imported/probed three times.
+
+    Returns:
+        True when a rebuild may proceed; False when the manifest exists but
+        cannot be rewritten -- reported as a visible warning so the caller's
+        failed sub-step engages the cooldown instead of retrying per command.
+        A *missing* manifest proceeds, and a save that then fails is reported
+        by the generator's own verdict (#201).
+    """
+    from wl_cli.commands.initenv.components.project_structure.config_generator import (
+        template_manifest_path,
+    )
+
+    manifest_path = template_manifest_path(deploy_root)
+    _quarantine_unusable_template_manifest(manifest_path)
+    if _template_manifest_is_writable(manifest_path):
+        return True
+
+    log_warning_pair(
+        f"Warning: template manifest {manifest_path} is not writable; the .wl "
+        "templates cannot be re-synced until that is fixed (e.g. "
+        f"`chmod u+w {manifest_path}`). The sync will retry after the cooldown.",
+        f"警告：模板 manifest {manifest_path} 不可写；在修复之前无法重新同步 .wl "
+        f"模板（例如 `chmod u+w {manifest_path}`）。同步将在冷却后重试。",
+    )
+    return False
+
+
+def _update_templates_directory(deploy_root: Root) -> bool:
+    """Refresh .wl config templates from the vendored sources.
+
+    Returns:
+        True when generation succeeded (even if nothing changed); False when it
+        raised, or when it produced no ``.wl/config.json`` -- the caller treats
+        that as a failed sync sub-step (#202).
+    """
+    try:
+        from wl_cli.commands.initenv.components.project_structure.setup_handler import (
+            ProjectStructureSetup,
+        )
+
+        if not _prepare_template_manifest_for_rebuild(deploy_root):
+            return False
+        setup = ProjectStructureSetup()
+        return bool(setup.config_generator.generate_configs(deploy_root))
+    except Exception as e:
+        log_info_pair(
+            f"Warning: Failed to update .wl templates: {e}",
+            f"警告: 更新 .wl 模板失败：{e}",
+        )
+        return False
+
+
+def compare_versions(version1: str, version2: str) -> int:
+    """Public API to compare two version strings.
+
+    Thin wrapper over :class:`~wl_cli.utils.version.version_comparator.VersionComparator`:
+    the unparsable-version policy lives here (an unparsable string is treated
+    as outdated so a corrupted .wl version stamp gets healed by a full update,
+    instead of silently comparing equal and never updating).
+
+    Args:
+        version1: First version string (e.g., "0.2.24")
+        version2: Second version string (e.g., "0.3.0")
+
+    Returns:
+        int: -1 if version1 < version2, 0 if equal, 1 if version1 > version2
+    """
+    from wl_cli.utils.version.version_comparator import VersionComparator
+
+    try:
+        return cast("int", VersionComparator.compare_versions(version1, version2))
+    except ValueError:
+        return -1
+
+
+def _update_wl_directory(legacy_wl_dir: Path | None, deploy_root: Root) -> bool:
+    """
+    Update the .wl directory with the latest files from vendors.
+
+    Order matters: hooks and templates are updated first, and the config.json
+    version stamp is bumped LAST, so a failure leaves the stamp stale and the
+    next command retries the sync.
+
+    ``deploy_root`` is threaded in as a value (see :func:`sync_wl_dir`); it has
+    no default, so no layer can silently re-derive one from the process CWD
+    (#160).
+
+    Returns:
+        True only when hooks AND config generation both succeeded -- the
+        version stamp is bumped and the failure marker cleared. On any sub-step
+        failure the shared accounting in :func:`_apply_substeps` keeps the stamp
+        stale (the marker is written), so the cooldown engages and the sync is
+        retried after it.
+    """
+    from wl_cli.commands.initenv.components.project_structure.setup_handler import (
+        ProjectStructureSetup,
+    )
+
+    try:
+        setup_handler = ProjectStructureSetup()
+
+        # Create .wl directory if it doesn't exist (deploy root, not CWD)
+        wl_dir = deploy_root.wl_dir()
+        wl_dir.mkdir(parents=True, exist_ok=True)
+
+        # Migrate a pre-#95/#96 config before anything reads or writes one, so a
+        # divergent legacy `.wl` is carried over rather than silently dropped.
+        _migrate_legacy_config_if_needed(wl_dir, legacy_wl_dir)
+
+        # Evaluate the hook verdict once and hand it to the hooks sub-step: the
+        # full path must not probe core.hooksPath a second time inside the sync
+        # (#161).
+        from ..commands.initenv.components.project_structure.hooks_manager import (
+            evaluate_hooks,
+        )
+
+        hooks_state = evaluate_hooks(deploy_root)
+
+        # Update hooks (hash-aware: only re-copies changed hooks), then other
+        # .wl files (templates copied only if missing). Both always run -- the
+        # shared helper never short-circuits -- and owns the partial-failure
+        # accounting (the .update_failed marker) for the pair.
+        ok = _apply_substeps(
+            partial(_update_hooks_directory, hooks_state, deploy_root),
+            partial(_generate_configs_substep, setup_handler, deploy_root),
+            deploy_root=deploy_root,
+        )
+        if not ok:
+            # Keep the stamp stale so the cooldown engages (do NOT bump).
+            return False
+
+        # Bump version LAST so failures above leave a stale stamp → retried.
+        # A failed stamp write is itself a failed sub-step (#177): keep the
+        # marker and report False so the cooldown engages. Reporting success
+        # while the stamp stayed stale made every later command re-run the
+        # full sync on a read-only checkout.
+        if not _update_config_version(deploy_root):
+            _mark_update_failed(deploy_root)
+            log_warning_pair(
+                "Warning: failed to update the .wl version stamp; the sync will "
+                "retry after the cooldown.",
+                "警告：更新 .wl 版本戳失败；将在冷却后重试同步。",
+            )
+            return False
+
+        _clear_update_failed(deploy_root)
+
+        log_info_pair(
+            "✓ .wl directory updated successfully",
+            "✓ .wl 目录更新成功",
+        )
+        return True
+
+    except Exception as e:
+        _mark_update_failed(deploy_root)
+        log_info_pair(
+            f"Warning: Failed to update .wl directory: {e}",
+            f"警告：更新 .wl 目录失败：{e}",
+        )
+        return False
+
+
+def _update_config_version(deploy_root: Root) -> bool:
+    """
+    Update the version in config.json.
+
+    ``deploy_root`` is required (#160): the stamp lands in the very ``.wl`` the
+    caller resolved, never in one re-derived from the process CWD.
+
+    Returns:
+        True when the stamp was written (or intentionally skipped in a test
+        environment); False when the direct write failed *and* the fallback
+        could not write this very ``config.json``. The caller treats False as a
+        failed sub-step (#177) -- previously this swallowed the error and the
+        sync claimed success with a stale stamp.
+    """
+    import json
+
+    from wl_cli import __version__
+
+    wl_dir = deploy_root.wl_dir()
+    config_file = wl_dir / "config.json"
+
+    try:
+        # Read existing config
+        with open(config_file, encoding="utf-8") as f:
+            config = json.load(f)
+
+        # Update only the version field
+        config["version"] = __version__
+
+        # Save back the config
+        with open(config_file, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        return True
+    except (json.JSONDecodeError, OSError):
+        # If there's an error, fall back to using config manager
+        from .config import get_config_manager
+
+        config_manager = get_config_manager()
+        # ...but only when that manager writes THIS config.json. Its
+        # ``config_file`` is whatever its own resolution produced --
+        # ``WL_CONFIG_PATH``, or a process CWD outside the checkout -- and
+        # ``set()`` then reports a successful write into an unrelated file while
+        # ``.wl/config.json`` stays absent. Counting that as success was the
+        # proxy predicate behind #190: the next command found "missing config",
+        # re-ran the whole sync, and the sync never converged (no cooldown, no
+        # end state). Refuse to certify a write we cannot see; the caller turns
+        # False into the failure marker, so the retry is bounded by the cooldown.
+        if not _same_path(Path(config_manager.config_file), config_file):
+            log_warning_pair(
+                f"Warning: cannot update the .wl version stamp: the active config "
+                f"file is {config_manager.config_file}, not {config_file}.",
+                f"警告：无法更新 .wl 版本戳：当前生效的配置文件是 "
+                f"{config_manager.config_file}，而不是 {config_file}。",
+            )
+            return False
+        if not config_manager.set("version", __version__):
+            return False
+        # ``set`` answers True for a *deliberate* no-op in a test environment
+        # (ConfigSaver's guard). Certify the stamp from the bytes on disk, or a
+        # pytest-process sync reports a stamped ``.wl`` it never wrote (#202).
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                stamped = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return False
+        if not isinstance(stamped, dict):
+            return False
+        return bool(stamped.get("version") == __version__)
+
+
+def _update_hooks_directory(state: HookSyncState, deploy_root: Root) -> bool:
+    """
+    Update the hooks directory with the latest files from vendors.
+
+    ``state`` is the :class:`HookSyncState` the caller already evaluated (the
+    light path in :func:`sync_wl_dir`, the full path in
+    :func:`_update_wl_directory`); it is consumed by ``apply_hook_sync``, which
+    also repairs a stale ``core.hooksPath`` (unset, dangling, or pointing
+    elsewhere) even when no hook file changed -- without probing git again
+    (#161). ``deploy_root`` is threaded through as a value so the hooks leg is
+    anchored on it rather than re-derived from the process CWD.
+
+    Returns:
+        True when syncing succeeded (even if nothing changed); False when it
+        raised -- the caller treats that as a failed sync sub-step.
+    """
+    try:
+        # Use the existing hook syncing logic from hooks_manager
+        from ..commands.initenv.components.project_structure.hooks_manager import (
+            apply_hook_sync,
+        )
+
+        # Update hooks directory with the already computed verdict
+        apply_hook_sync(state, deploy_root)
+        return True
+
+    except Exception as e:
+        log_info_pair(
+            f"Warning: Failed to update hooks directory: {e}",
+            f"警告：更新钩子目录失败：{e}",
+        )
+        return False
+
+
+def _get_components_to_update(
+    component_id: str | None,
+    component_manager,
+    dry_run: bool,
+    result: dict,
+) -> list:
+    """Get list of components to update.
+
+    Args:
+        component_id: Specific component ID to update or None for all
+        component_manager: ComponentManager instance
+        dry_run: Whether this is a dry run
+        result: Result dictionary to update in case of errors
+
+    Returns:
+        List of tuples (component_id, component_info) to update, or empty list if error
+    """
+    if component_id:
+        if component_manager.component_exists(component_id):
+            return [(component_id, component_manager.get_component(component_id))]
+        else:
+            result["errors"].append(f"Component {component_id} not found")
+            result["message"] = f"Component {component_id} not found"
+            result["message_zh"] = f"组件 {component_id} 不存在"
+            return []
+    else:
+        return list(component_manager.get_all_components().items())
+
+
+def _update_vendor_files(
+    components_to_update: list,
+    package_path: Path,
+    wl_dir: Path,
+    dry_run: bool,
+) -> list:
+    """Copy vendor files for all components.
+
+    ``ComponentManager``'s ``source_path`` is package-relative
+    (``"vendors/git/"``, ``"vendors/config/"``), so the *same* relative spelling
+    is joined on both sides: ``<package>/<source_path>`` -> ``<.wl>/<source_path>``.
+    Joining the source onto a separate ``vendors`` segment produced
+    ``.wl/vendors/vendors/git/...`` while ``.wl/vendors/git/`` never appeared --
+    and the vendor stamp was written anyway, so the wrong tree was certified
+    fresh and never repaired (#190).
+
+    Args:
+        components_to_update: List of components to update
+        package_path: Path to the installed package root
+        wl_dir: Path to .wl directory
+        dry_run: Whether this is a dry run
+
+    Returns:
+        List of copied file paths
+    """
+    all_files_copied = []
+    for comp_id, comp_info in components_to_update:
+        source_path = package_path / comp_info["source_path"]
+        target_path = wl_dir / comp_info["source_path"]
+
+        if source_path.exists():
+            files = _copy_vendor_files(source_path, target_path, dry_run)
+            all_files_copied.extend(files)
+        else:
+            if dry_run:
+                log_info_pair(
+                    f"Component {comp_id} source not found: {source_path}",
+                    f"组件 {comp_id} 源文件不存在：{source_path}",
+                )
+    return all_files_copied
+
+
+def _set_vendor_result(
+    result: dict,
+    all_files_copied: list,
+    dry_run: bool,
+) -> None:
+    """Update result dictionary based on copied files.
+
+    Args:
+        result: Result dictionary to update
+        all_files_copied: List of copied file paths
+        dry_run: Whether this is a dry run
+
+    Returns:
+        None
+    """
+    if all_files_copied:
+        result["updated"] = True
+        result["success"] = True
+        if dry_run:
+            result["message"] = f"Dry run: Would copy {len(all_files_copied)} files"
+            result["message_zh"] = f"干运行：将复制 {len(all_files_copied)} 个文件"
+        else:
+            result["message"] = (
+                f"Successfully updated vendors ({len(all_files_copied)} files copied)"
+            )
+            result["message_zh"] = (
+                f"成功更新 vendors（复制了 {len(all_files_copied)} 个文件）"
+            )
+            log_info_pair(
+                "✓ Vendors updated successfully",
+                "✓ Vendors 更新成功",
+            )
+    else:
+        result["success"] = True
+        if dry_run:
+            result["message"] = "No files would be copied"
+            result["message_zh"] = "没有文件需要复制"
+        else:
+            result["message"] = "No files were copied"
+            result["message_zh"] = "没有文件被复制"
+
+
+def _vendor_relative_files(root: Path) -> set[Path]:
+    """Every file a vendor copy leg would ship, relative to *root*.
+
+    Mirrors :func:`_copy_vendor_files`' traversal (``os.walk``) so the manifest
+    side and the copied side are spelled the same way -- a comparison against a
+    differently-enumerated tree would be comparing two inventories, not the
+    source against its copy.
+    """
+    if not root.is_dir():
+        return set()
+    return {
+        Path(dirpath, name).relative_to(root)
+        for dirpath, _dirs, files in os.walk(root)
+        for name in files
+    }
+
+
+def _missing_vendor_targets(components: list, wl_dir: Path) -> list[tuple[str, Path]]:
+    """Components whose copied tree is incomplete in ``.wl`` (#190, #197).
+
+    ``.wl/vendors.version`` is a proxy predicate: it records *that* a copy leg
+    ran, not that the tree it claims to describe is still there. That proxy was
+    actively harmful here -- projects stamped by the old double-``vendors``
+    spelling hold ``.wl/vendors/vendors/...`` and no ``.wl/vendors/git/``, yet
+    answer "already up to date" forever. Verify the target of every component
+    that ships files before trusting the stamp.
+
+    A bare ``target.is_dir()`` was the second proxy of the same kind (#197): an
+    empty ``.wl/vendors/git/`` or a half-copied tree satisfied it, so a botched
+    copy stayed certified fresh forever. The manifest here is the package
+    source tree: every file it holds must be present under the target
+    (``expected <= actual``, set comparison by relative path). Extra files in
+    the target are tolerated -- the tool never prunes user additions -- and
+    content is deliberately not hashed, so the per-command hot path stays a
+    walk of two small trees.
+
+    A component whose package source is absent or holds no files is skipped:
+    there is nothing to copy, so requiring a target would never converge.
+
+    Args:
+        components: ``(component_id, component_info)`` pairs to check.
+        wl_dir: Path to the .wl directory.
+
+    Returns:
+        ``(component_id, target_path)`` for every incomplete tree, in input
+        order.
+    """
+    package_path = _get_package_path()
+    missing: list[tuple[str, Path]] = []
+    for comp_id, comp_info in components:
+        source = package_path / comp_info["source_path"]
+        expected = _vendor_relative_files(source)
+        if not expected:
+            continue
+        target = wl_dir / comp_info["source_path"]
+        if not expected <= _vendor_relative_files(target):
+            missing.append((comp_id, target))
+    return missing
+
+
+def check_and_update_vendors(
+    dry_run: bool = False, component_id: str | None = None, force: bool = False
+) -> dict:
+    """
+    Check and update vendors directory.
+
+    Freshness is tracked by the independent ``.wl/vendors.version`` stamp
+    written after the last successful copy (#177), not by
+    ``config.json.version``: the self-sync bumps the latter on every command,
+    which made the copy leg unreachable when invoked through ``wl update``.
+
+    Args:
+        dry_run: If True, only show what would be done without actually making changes.
+        component_id: Optional component ID to update only a specific component.
+        force: Copy even when the vendor stamp is already current.
+
+    Returns:
+        Dictionary with update results.
+    """
+    from wl_cli.commands.update.services.component_manager import (
+        ComponentManager,
+    )
+
+    result: dict[str, Any] = {
+        "success": False,
+        "updated": False,
+        "message": "",
+        "files_copied": [],
+        "errors": [],
+    }
+
+    # Root-anchored (#125): the deploy root's ``.wl``, resolved once here, the
+    # public entry (#160). Vendors need only the deploy root, so this is a
+    # single-root consumer and uses ``current_root`` rather than building a
+    # ``RootContext`` it would not fully use. ``_update_config_version`` (called
+    # below) stamps that very directory, so the vendor files and the version
+    # stamp land in one ``.wl``. Was a bare ``Path(".wl")`` against the process
+    # CWD, so ``wl update vendors`` from a subdirectory wrote the vendor tree
+    # into the subdirectory's ``.wl`` and stamped the wrong config.
+    deploy_root = current_root(RootKind.DEPLOY)
+    wl_dir = _deploy_wl_dir(deploy_root)
+    package_vendors_path = _get_package_vendors_path()
+
+    if not package_vendors_path.exists():
+        result["message"] = "Package vendors directory not found"
+        result["message_zh"] = "包内 vendors 目录不存在"
+        return result
+
+    component_manager = ComponentManager()
+
+    try:
+        # Resolve the requested components first: the freshness verdict below is
+        # about *them*, and a bogus component id must say "not found" rather than
+        # be masked by an up-to-date stamp.
+        components_to_update = _get_components_to_update(
+            component_id, component_manager, dry_run, result
+        )
+        if not components_to_update and result["errors"]:
+            return result
+
+        # Check if update is needed (independent vendor stamp, #177). ``force``
+        # deliberately bypasses the freshness check -- the flag was declared but
+        # never read before.
+        #
+        # A current stamp is only believed when the tree it claims to describe is
+        # actually present (#190): the old double-``vendors`` spelling stamped
+        # projects whose `.wl/vendors/git/` never existed, and "already up to
+        # date" then made the defect permanent.
+        missing_targets = (
+            [] if force else _missing_vendor_targets(components_to_update, wl_dir)
+        )
+        stamp_stale = _should_update_vendors(wl_dir)
+        if not force and not stamp_stale and not missing_targets:
+            if dry_run:
+                result["message"] = "Vendors are already up to date"
+                result["message_zh"] = "Vendors 已经是最新的"
+                log_info_pair("Vendors are already up to date", "Vendors 已经是最新的")
+            else:
+                result["success"] = True
+                result["message"] = "Vendors are already up to date"
+                result["message_zh"] = "Vendors 已经是最新的"
+            return result
+
+        if missing_targets and not stamp_stale:
+            log_info_pair(
+                f"Vendors are incomplete: {len(missing_targets)} component "
+                "tree(s) are missing even though the vendor stamp is current.",
+                f"Vendors 不完整：vendor 版本戳已是最新，但有 "
+                f"{len(missing_targets)} 个组件目录缺失。",
+            )
+
+        if dry_run:
+            log_info_pair(
+                "Dry run: Checking vendors for update...",
+                "干运行：检查 vendors 更新...",
+            )
+        else:
+            log_info_pair(
+                "Updating vendors directory...",
+                "正在更新 vendors 目录...",
+            )
+
+        # Ensure vendors directory exists
+        if not dry_run:
+            (wl_dir / "vendors").mkdir(parents=True, exist_ok=True)
+
+        # Copy vendor files
+        all_files_copied = _update_vendor_files(
+            components_to_update, _get_package_path(), wl_dir, dry_run
+        )
+
+        result["files_copied"] = all_files_copied
+
+        _set_vendor_result(result, all_files_copied, dry_run)
+
+        if dry_run and all_files_copied:
+            log_info_pair(
+                f"Dry run: would copy {len(all_files_copied)} vendor file(s)",
+                f"干运行：将复制 {len(all_files_copied)} 个 vendor 文件",
+            )
+
+        if not dry_run:
+            # Stamp only a copy leg that actually left every requested tree in
+            # place. A stamp written over a still-incomplete tree is the same
+            # "certified by a proxy" failure this ticket is about (#190).
+            still_missing = _missing_vendor_targets(components_to_update, wl_dir)
+            if still_missing:
+                result["success"] = False
+                result["errors"].append(
+                    "Vendors are still incomplete after copying: "
+                    + ", ".join(str(target) for _comp_id, target in still_missing)
+                )
+            elif all_files_copied and not _write_vendors_version(wl_dir):
+                # The files landed but the stamp did not: report it instead of
+                # leaving the caller with a plain success (#177 review).
+                result["success"] = False
+                result["errors"].append(
+                    "Vendors were copied but the vendor version stamp could not be written"
+                )
+
+    except Exception as e:
+        result["errors"].append(str(e))
+        result["message"] = f"Failed to update vendors: {e}"
+        result["message_zh"] = f"更新 vendors 失败：{e}"
+        log_info_pair(
+            f"Warning: {result['message']}",
+            f"警告：{result['message_zh']}",
+        )
+
+    return result
+
+
+def _get_package_path() -> Path:
+    """
+    Get the path to the installed package root.
+
+    Returns:
+        Path object pointing to the package directory.
+    """
+    import wl_cli
+
+    return Path(wl_cli.__file__).parent
+
+
+def _get_package_vendors_path() -> Path:
+    """
+    Get the path to the vendors directory in the package.
+
+    Returns:
+        Path object pointing to the package's vendors directory.
+    """
+    return _get_package_path() / "vendors"
+
+
+def _copy_vendor_files(
+    source_path: Path, target_path: Path, dry_run: bool = False
+) -> list[str]:
+    """
+    Copy vendor files from source to target.
+
+    Args:
+        source_path: Source directory path.
+        target_path: Target directory path.
+        dry_run: If True, only show what would be done.
+
+    Returns:
+        List of copied (or, in a dry run, would-be copied) file paths.
+    """
+    copied_files: list[str] = []
+
+    if not source_path.exists():
+        return copied_files
+
+    for root, _dirs, files in os.walk(source_path):
+        for file in files:
+            source_file = Path(root) / file
+            relative_path = source_file.relative_to(source_path)
+            target_file = target_path / relative_path
+
+            if dry_run:
+                log_info_pair(
+                    f"Would copy: {source_file} -> {target_file}",
+                    f"将复制：{source_file} -> {target_file}",
+                )
+                # Count the file in the dry run too: otherwise the caller's
+                # "nothing to copy" verdict contradicts the per-file lines above
+                # (#177 F2).
+                copied_files.append(str(target_file))
+            else:
+                target_file.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_file, target_file)
+                copied_files.append(str(target_file))
+
+    return copied_files
+
+
+#: Independent vendor freshness stamp: the ``__version__`` of the last
+#: successful vendor copy, as plain text (#177).
+VENDORS_VERSION_FILE = "vendors.version"
+
+
+def _vendors_version_path(wl_dir: Path) -> Path:
+    """Path of the independent vendor freshness stamp (#177)."""
+    return wl_dir / VENDORS_VERSION_FILE
+
+
+def _write_vendors_version(wl_dir: Path) -> bool:
+    """Record the current wl version after a successful vendor copy.
+
+    Returns:
+        True when the stamp was written; False when the write failed (logged as
+        a warning -- the next run then simply copies again).
+    """
+    from wl_cli import __version__
+
+    try:
+        _vendors_version_path(wl_dir).write_text(f"{__version__}\n", encoding="utf-8")
+        return True
+    except OSError as e:
+        log_warning_pair(
+            f"Warning: failed to write the vendor version stamp: {e}",
+            f"警告：写入 vendor 版本戳失败：{e}",
+        )
+        return False
+
+
+def _should_update_vendors(wl_dir: Path | None = None) -> bool:
+    """
+    Check if vendors directory needs to be updated.
+
+    Freshness is tracked by the independent ``.wl/vendors.version`` stamp, not
+    by ``config.json``'s ``version`` field: the self-sync advances the latter
+    whenever it runs, so reading it here reported "up to date" without ever
+    inspecting the copied vendor files (#177). A missing, unreadable, empty, or
+    older stamp means the vendors are stale.
+
+    Args:
+        wl_dir: Path to the .wl directory (defaults to the deploy root's
+            ``.wl``, via :func:`~wl_cli.utils.root_fallback.current_root`).
+
+    Returns:
+        True if update is needed, False otherwise.
+    """
+    from wl_cli import __version__
+
+    # Root-anchored default (#125): the deploy root's ``.wl`` -- see the note in
+    # `check_and_update_vendors`. A deep caller may still omit the argument, so
+    # the default resolves the one root it needs through the single policy
+    # (#160) rather than through a deleted local helper.
+    stamp_file = _vendors_version_path(wl_dir or current_root(RootKind.DEPLOY).wl_dir())
+    try:
+        stamp = stamp_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        return True
+
+    if not stamp:
+        return True
+
+    return compare_versions(stamp, __version__) < 0