py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/lfs/README.md

@@ -0,0 +1,221 @@
+# LFS Lock 模块
+
+对标 `git-flow` 子系统的 **Git LFS 文件锁协作工作流**。解决二进制文件（`.sldprt`、`.dwg` 等）无法被 Git merge 的问题 —— 通过全局文件锁确保同一时刻只有一人编辑。
+
+## 架构
+
+```
+CLI (cli.py)         Pre-push Hook (hook.py)
+     │                      │
+     ▼                      ▼
+LfsLockPolicyValidator (policy.py)  ←  Pre-push fallback auto-lock (v2)
+     │
+     ├── LfsLockConfig  (config.py)   ← 读取 .wl/lfs-lock.yml (v2: auto_lock/auto_unlock)
+     └── LfsLockManager (manager.py)  ← 封装 git lfs 命令 (v2: lock_files/unlock_files)
+
+wl lfs watch (watcher.py)  ← v2: watchdog 文件监听 + auto lock/unlock
+```
+
+| 层 | 文件 | 职责 |
+|----|------|------|
+| CLI | `cli.py` | Click 命令组：`check`、`lock`、`unlock` |
+| Hook | `hook.py` | pre-push hook 集成：策略验证 + 失败格式化 |
+| Policy | `policy.py` | 策略引擎：strict/warn/off 三种模式 |
+| Config | `config.py` | 配置加载：读 `.wl/lfs-lock.yml`，合并默认值 |
+| Manager | `manager.py` | 命令封装：`git lfs lock/unlock/locks` + `git check-attr` |
+| Watcher | `watcher.py` | watchdog 文件监听：自动 lock/unlock + pre-push 检测 |
+
+## 命令
+
+```bash
+wl lfs check              # 推送前预检：变更的 LFS 文件是否全部已 lock
+wl lfs lock <file>        # 锁定文件（全局锁）
+wl lfs unlock <file>      # 解锁文件，--force 管理员强制解锁
+```
+
+## 工作流
+
+```
+                         wl lfs lock model.sldprt
+  开始编辑 ──────────────────────────────────────────► 编辑 ──► git push
+                                                               │
+                                              pre-push hook ──┤
+                                              (wl lfs check)   │
+                                                      ✓        ✗
+                                                    推送成功   被阻止
+
+  wl init lfs --with-locks   一键部署上述全部
+```
+
+## 三种模式
+
+| 模式 | 未锁文件 | 被他人锁定的文件 | 适用场景 |
+|------|---------|-----------------|---------|
+| `strict` | BLOCKED | BLOCKED | 正式团队，零容忍 |
+| `warn` | WARN（放行） | BLOCKED | 过渡期，逐步推进 |
+| `off` | OK（放行） | OK（放行） | 关闭检查 |
+
+配置在 `.wl/lfs-lock.yml` 中修改：
+
+```yaml
+lock:
+  mode: strict          # strict | warn | off
+  scope: global         # 仅支持全局锁
+checks:
+  pre_commit: false
+  pre_push: true        # 推送时自动检查
+patterns:
+  locked_by_self: false # 是否将本人锁定也视为阻断
+notify:
+  unlocked_files: true
+force_unlock_token: ""  # 管理员强制解锁令牌
+stale_lock_warning_days: 7
+exempt_patterns: []     # 豁免检查的文件模式
+```
+
+## Pre-push Hook 集成
+
+`wl init lfs --with-locks` 会自动在 pre-push hook 中注入 LFS 锁检查。推送时：
+
+1. 先执行 Git Flow 策略检查（如果已配置）
+2. 再执行 LFS Lock 检查
+3. 任一失败则阻止推送
+
+被阻止时输出示例：
+
+```
+LFS Lock check: BLOCKED
+Unlocked LFS files: models/part.sldprt
+Locked by others: drawings/design.dwg
+Config: .wl/lfs-lock.yml
+Run `wl lfs check` for details.
+```
+
+## 清理
+
+```bash
+wl clean lfs    # 移除 .wl/lfs-lock.yml
+```
+
+## 模块依赖
+
+```
+wl_cli.commands.lfs
+  ├── .config       → LfsLockConfig (YAML 配置)
+  ├── .manager      → LfsLockManager (git 命令)
+  ├── .policy       → LfsLockPolicyValidator (策略)
+  ├── .hook         → validate_lfs_locks (hook 集成)
+  ├── .cli          → Click 命令注册
+  └── .initializer  → LfsLockInitializer (写入 .wl/lfs-lock.yml 默认配置)
+
+wl_cli.commands.clean.lfs
+  └── _clean_lock_config
+```
+
+## 设计决策
+
+- **全局锁**：二进制文件不可 merge，分支级锁无意义
+- **`git check-attr`**：不依赖 `git lfs` 已安装即可检测 LFS 跟踪
+- **10 秒超时**：`git lfs locks --json` 调用设置超时，避免 LFS 服务器不可用时 hang
+- **幂等部署**：`LfsLockInitializer` 不会覆盖已有的 `.wl/lfs-lock.yml`
+
+## v2: Watch & Auto Lock/Unlock
+
+`wl lfs watch` is a foreground process that monitors your LFS-tracked files:
+
+- **Auto-lock on edit** — when you modify an LFS file, it's locked automatically
+- **Auto-unlock on push** — after a successful push, locked files are unlocked
+- **Pre-push fallback** — if watch isn't running, the pre-push hook auto-locks
+  files before allowing the push
+
+### Quick Start
+
+```bash
+# 1. Deploy lock workflow
+wl init lfs --with-locks
+
+# 2. Start the watcher in your project directory
+wl lfs watch
+
+# 3. Edit your CAD files normally — they auto-lock
+# 4. Push as usual — locked files auto-unlock after push
+# 5. Ctrl-C to stop watching
+```
+
+### wl lfs watch
+
+```
+$ wl lfs watch
+LFS Watch started. Ctrl-C to stop.
+Scanning 12 LFS-tracked files...
+  models/bracket.sldprt  → modified, locking...  locked
+  models/housing.dwg     → already locked by you
+Watch: 12 files monitored. Waiting for changes...
+  [14:32:01] models/bracket.sldprt modified → auto-locked
+  [14:35:18] push detected (branch: main) → auto-unlocked models/bracket.sldprt
+^C
+LFS Watch stopped. Session: 2 lock(s), 1 unlock(s), 0 skipped.
+```
+
+### Pre-push Fallback
+
+If `wl lfs watch` is not running, the pre-push hook still protects you:
+
+1. `git push` triggers the pre-push hook
+2. Hook detects unlocked LFS files
+3. If `auto_lock.fallback: true` (default), files are auto-locked
+4. Push proceeds if all files were locked successfully
+5. In CI environments (CI=true), auto-lock is skipped — strict validation only
+
+### Configuration (.wl/lfs-lock.yml)
+
+```yaml
+lock:
+  mode: strict          # strict | warn | off
+
+auto_lock:
+  fallback: true        # pre-push auto-lock fallback
+  skip_locked_by_others: true
+
+auto_unlock:
+  on_push: true         # auto-unlock after push
+  retry_count: 3        # unlock retry attempts
+  retry_delay: 2        # seconds between retries
+
+checks:
+  pre_push: true
+```
+
+### Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| watchdog not installed | lfs extra missing | `pip install "py_wlcli[lfs]"` or `uv pip install "py_wlcli[lfs]"` |
+| Watch doesn't detect file changes | NFS/SMB/WSL filesystem | Fallback: pre-push auto-lock still works |
+| File not auto-locked | File not in .gitattributes | Run `wl init lfs` with tracking patterns |
+| "Already running" error | Stale PID file | Delete `.wl/lfs-watch.pid` |
+
+## Windows 一键工作会话 (work.bat)
+
+在 Windows 平台上，`wl init lfs --with-locks` 或 `wl lfs init` 会在项目根目录生成 `work.bat`。
+
+双击 `work.bat` 即可启动完整的 LFS 工作会话：
+1. 自动拉取最新代码（`git pull`）
+2. 启动 `wl lfs watch`（自动 lock/unlock）
+3. 退出时提示是否 push（Y 确认后自动 add + commit + push）
+
+**使用方法：**
+```cmd
+:: 初始化项目（自动生成 work.bat）
+wl init project
+wl init lfs --with-locks
+
+:: 双击 work.bat 开始工作
+:: 保持命令行窗口打开，在 CAD 软件中编辑文件
+:: 完成后关闭窗口，按 Y 确认 push
+```
+
+**注意：**
+- 命令行窗口必须保持打开，`wl lfs watch` 才能持续工作
+- 如果上次未正常退出，脚本会自动清理残留的 PID 文件
+- 不想 push 时按任意非 Y 键跳过

wl_cli/commands/lfs/__init__.py

@@ -0,0 +1,5 @@
+"""LFS Lock command module."""
+
+from .watcher import LfsWatcher
+
+__all__ = ["LfsWatcher"]

wl_cli/commands/lfs/cli.py

@@ -0,0 +1,106 @@
+"""LFS Lock CLI commands."""
+
+from __future__ import annotations
+
+import click
+
+from ...commands.git.git_facts import get_changed_files
+from .config import LfsLockConfig
+from .manager import LfsLockManager
+from .policy import LfsLockPolicyValidator
+
+
+@click.group(name="lfs")
+def lfs_command() -> None:
+    """Git LFS lock workflow commands."""
+
+
+@lfs_command.command(name="check")
+def check_command() -> None:
+    """Check that all changed LFS files are locked before push."""
+    config = LfsLockConfig()
+    source = "main"
+    changed_files = get_changed_files(source)
+
+    if not changed_files:
+        click.echo("LFS Lock check: OK (no LFS files changed)")
+        return
+
+    validator = LfsLockPolicyValidator(config)
+    result = validator.validate(changed_files)
+
+    click.echo(f"LFS Lock check: {result.status}")
+    if result.locked_files:
+        click.echo(f"Locked: {', '.join(sorted(result.locked_files))}")
+    if result.unlocked_files:
+        click.echo(f"Unlocked: {', '.join(sorted(result.unlocked_files))}")
+    if result.locked_by_others:
+        click.echo(f"Locked by others: {', '.join(sorted(result.locked_by_others))}")
+    click.echo(f"Config: {result.config_source}")
+
+    if not result.ok:
+        raise click.ClickException("LFS Lock policy check failed")
+
+
+@lfs_command.command(name="lock")
+@click.argument("file")
+def lock_command(file: str) -> None:
+    """Lock an LFS file."""
+    manager = LfsLockManager()
+    if manager.lock(file):
+        click.echo(f"Locked: {file}")
+    else:
+        raise click.ClickException(f"Failed to lock: {file}")
+
+
+@lfs_command.command(name="unlock")
+@click.argument("file")
+@click.option("--force", is_flag=True, help="Force unlock (admin override)")
+def unlock_command(file: str, force: bool) -> None:
+    """Unlock an LFS file."""
+    manager = LfsLockManager()
+    if manager.unlock(file, force=force):
+        click.echo(f"Unlocked: {file}")
+    else:
+        raise click.ClickException(f"Failed to unlock: {file}")
+
+
+@lfs_command.command(name="init")
+def init_command() -> None:
+    """Initialize Git LFS with lock workflow and work.bat.
+
+    Equivalent to: wl init lfs --with-locks
+    """
+    from ...commands.initenv.services.git_lfs_initializer import GitLfsInitializer
+    from .initializer import LfsLockInitializer, lfs_lock_init_failure_message
+
+    lock_initializer = LfsLockInitializer()
+    # Probe before Git LFS touches the repo: that step installs filters/hooks
+    # and would otherwise leave a half-initialized project behind when the
+    # lock step then reports the missing .wl directory (#198).
+    if not lock_initializer.wl_dir_ready():
+        raise click.ClickException(
+            lfs_lock_init_failure_message(lock_initializer.project_root)
+        )
+
+    GitLfsInitializer().initialize()
+    if lock_initializer.initialize() is False:
+        raise click.ClickException(
+            lfs_lock_init_failure_message(lock_initializer.project_root)
+        )
+
+
+@lfs_command.command(name="watch")
+@click.option("--verbose", is_flag=True, help="Show detailed event output")
+def watch_command(verbose: bool) -> None:
+    """Start LFS file watcher (foreground process, Ctrl-C to exit).
+
+    Automatically locks LFS-tracked files when they are modified,
+    and unlocks them when pushed to the remote.
+    """
+    from .watcher import LfsWatcher
+
+    watcher = LfsWatcher(verbose=verbose)
+    exit_code = watcher.run()
+    if exit_code != 0:
+        raise click.ClickException("LFS watch failed")

wl_cli/commands/lfs/config.py

@@ -0,0 +1,164 @@
+"""LFS Lock configuration loading."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+try:
+    from yaml import YAMLError
+except ImportError:
+    YAMLError = ValueError
+
+from ...utils.root import RootKind
+from ...utils.root_fallback import current_root
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class LfsLockConfigError(ValueError):
+    """Raised when LFS Lock configuration is malformed."""
+
+
+class LfsLockConfig:
+    """Loads and provides access to .wl/lfs-lock.yml configuration."""
+
+    DEFAULT_CONFIG: dict = {
+        "lock": {
+            "mode": "strict",
+            "scope": "global",
+        },
+        "auto_lock": {
+            "fallback": True,
+            "skip_locked_by_others": True,
+        },
+        "auto_unlock": {
+            "on_push": True,
+            "retry_count": 3,
+            "retry_delay": 2,
+        },
+        "checks": {
+            "pre_commit": False,
+            "pre_push": True,
+        },
+        "patterns": {
+            "locked_by_self": False,
+        },
+        "notify": {
+            "unlocked_files": True,
+        },
+        "force_unlock_token": "",
+        "stale_lock_warning_days": 7,
+        "exempt_patterns": [],
+    }
+
+    def __init__(self, config_path: Path | None = None) -> None:
+        # Root-anchored (#125): the *project* root's ``.wl`` -- the kind the LFS
+        # initializer and watcher already use -- not the process CWD's, so
+        # ``wl lfs check`` from a subdirectory reads the root's policy instead
+        # of silently falling back to built-in defaults.
+        self.config_path = config_path or (
+            current_root(RootKind.PROJECT).wl_dir() / "lfs-lock.yml"
+        )
+        self._config = self._load_config()
+
+    @property
+    def config_source(self) -> str:
+        if self.config_path.exists():
+            return str(self.config_path)
+        return "built-in defaults"
+
+    @property
+    def mode(self) -> str:
+        return cast("str", self._config["lock"]["mode"])
+
+    @property
+    def pre_push(self) -> bool:
+        return cast("bool", self._config["checks"]["pre_push"])
+
+    @property
+    def locked_by_self(self) -> bool:
+        return cast("bool", self._config["patterns"]["locked_by_self"])
+
+    @property
+    def force_unlock_token(self) -> str:
+        return cast("str", self._config["force_unlock_token"])
+
+    @property
+    def stale_lock_warning_days(self) -> int:
+        return cast("int", self._config["stale_lock_warning_days"])
+
+    @property
+    def server_mode(self) -> str:
+        return cast("str", self._config.get("server_mode", "default"))
+
+    @property
+    def exempt_patterns(self) -> list[str]:
+        return list(self._config["exempt_patterns"])
+
+    @property
+    def auto_lock_fallback(self) -> bool:
+        return cast("bool", self._config["auto_lock"]["fallback"])
+
+    @property
+    def auto_lock_skip_locked_by_others(self) -> bool:
+        return cast("bool", self._config["auto_lock"]["skip_locked_by_others"])
+
+    @property
+    def auto_unlock_on_push(self) -> bool:
+        return cast("bool", self._config["auto_unlock"]["on_push"])
+
+    @property
+    def auto_unlock_retry_count(self) -> int:
+        return cast("int", self._config["auto_unlock"]["retry_count"])
+
+    @property
+    def auto_unlock_retry_delay(self) -> int:
+        return cast("int", self._config["auto_unlock"]["retry_delay"])
+
+    def _load_config(self) -> dict:
+        if not self.config_path.exists():
+            return dict(self.DEFAULT_CONFIG)
+
+        try:
+            import yaml
+
+            loaded = yaml.safe_load(self.config_path.read_text(encoding="utf-8"))
+        except ImportError:
+            # PyYAML not available — fall back to defaults
+            import logging
+
+            logging.getLogger(__name__).warning(
+                "PyYAML is not installed, using default LFS Lock config"
+            )
+            return dict(self.DEFAULT_CONFIG)
+        except YAMLError as exc:
+            raise LfsLockConfigError(
+                f"{self.config_path}: invalid YAML: {exc}"
+            ) from exc
+
+        if loaded is None:
+            return dict(self.DEFAULT_CONFIG)
+        if not isinstance(loaded, dict):
+            raise LfsLockConfigError(f"{self.config_path}: config must be a mapping")
+
+        return self._merge_config(loaded)
+
+    def _merge_config(self, loaded: dict) -> dict:
+        config = dict(self.DEFAULT_CONFIG)
+        # Merge nested sections
+        for section in (
+            "lock",
+            "auto_lock",
+            "auto_unlock",
+            "checks",
+            "patterns",
+            "notify",
+        ):
+            if section in loaded and isinstance(loaded[section], dict):
+                config[section] = {**config[section], **loaded[section]}
+        # Merge top-level keys
+        for key in ("force_unlock_token", "stale_lock_warning_days", "exempt_patterns"):
+            if key in loaded:
+                config[key] = loaded[key]
+        return config

wl_cli/commands/lfs/hook.py

@@ -0,0 +1,61 @@
+"""Pre-push hook helpers for LFS lock policy validation."""
+
+from __future__ import annotations
+
+from .config import LfsLockConfig
+from .policy import LfsLockPolicyValidator, LockCheckResult
+
+
+def validate_lfs_locks(changed_files: frozenset[str]) -> LockCheckResult | None:
+    """Run LFS lock policy validation against changed files.
+
+    Returns None if the module cannot be loaded (graceful degradation).
+    Returns LockCheckResult with ok=True/False otherwise.
+    """
+    try:
+        config = LfsLockConfig()
+    except Exception:
+        return None
+
+    if not changed_files:
+        return LockCheckResult(
+            ok=True,
+            status="OK",
+            config_source=config.config_source,
+        )
+
+    validator = LfsLockPolicyValidator(config)
+    return validator.validate(changed_files)
+
+
+def validate_lfs_locks_with_fallback(
+    changed_files: frozenset[str],
+) -> LockCheckResult | None:
+    """Run LFS lock check with auto-lock fallback.
+
+    If files are unlocked, attempt to auto-lock them before blocking.
+    Requires config.auto_lock.fallback = true (default).
+    In CI environments, falls back to strict validation (no auto-lock).
+    """
+    try:
+        config = LfsLockConfig()
+    except Exception:
+        return None
+
+    if not changed_files:
+        return LockCheckResult(ok=True, status="OK", config_source=config.config_source)
+
+    validator = LfsLockPolicyValidator(config)
+    return validator.validate_with_fallback(changed_files)
+
+
+def format_lfs_hook_failure(result: LockCheckResult) -> str:
+    """Format a LockCheckResult for pre-push hook error output."""
+    lines = [f"LFS Lock check: {result.status}"]
+    if result.unlocked_files:
+        lines.append("Unlocked LFS files: " + ", ".join(sorted(result.unlocked_files)))
+    if result.locked_by_others:
+        lines.append("Locked by others: " + ", ".join(sorted(result.locked_by_others)))
+    lines.append(f"Config: {result.config_source}")
+    lines.append("Run `wl lfs check` for details.")
+    return "\n".join(lines)