godot-cli-control 0.2.11__tar.gz → 0.2.12__tar.gz

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.11
+Version: 0.2.12
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/addons/godot_cli_control/README.md

@@ -9,13 +9,13 @@ If you have the Python CLI installed (`pipx install godot-cli-control`), the ent
 
 ```bash
 cd your_godot_project
-godot-cli-control init        # copy plugin, patch project.godot, detect Godot
+godot-cli-control init        # copy plugin, patch project.godot, detect Godot, gitignore .cli_control/
 godot-cli-control daemon start
 godot-cli-control tree 3
 godot-cli-control daemon stop
 ```
 
-`init` automates everything described in the manual setup below — copying the addon, editing `project.godot`, and detecting your Godot binary.
+`init` automates everything described in the manual setup below — copying the addon, editing `project.godot`, and detecting your Godot binary. It also appends `.cli_control/` to the project's root `.gitignore` (the daemon's machine-local state dir: detected binary path, pid, port, log, recording intermediates), so that state never gets committed. Pass `--no-gitignore` to skip that step.
 
 ## Manual Setup (if you prefer)
 

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/python/godot_cli_control/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.11'
-__version_tuple__ = version_tuple = (0, 2, 11)
+__version__ = version = '0.2.12'
+__version_tuple__ = version_tuple = (0, 2, 12)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/python/godot_cli_control/cli.py

@@ -1264,6 +1264,7 @@ def cmd_init(ns: argparse.Namespace) -> int:
             write_skills=not ns.no_skills,
             skills_only=ns.skills_only,
             clobber_skills=not ns.skills_no_clobber,
+            write_gitignore=not ns.no_gitignore,
             output_format=fmt,
             result=result,
         )
@@ -1569,7 +1570,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="在 Godot 项目根一键接入插件",
         description=(
             "复制 addons/godot_cli_control 到目标项目、patch project.godot 启用插件、"
-            "校验 GODOT_BIN。"
+            "校验 GODOT_BIN、在 .gitignore 忽略 .cli_control/。"
         ),
         epilog=(
             "GODOT_BIN 查找顺序：\n"
@@ -1601,6 +1602,14 @@ def build_parser() -> argparse.ArgumentParser:
             "保证版本与 CLI 帮助同步）。与 --no-skills / --skills-only 都兼容。"
         ),
     )
+    init_p.add_argument(
+        "--no-gitignore",
+        action="store_true",
+        help=(
+            "跳过往项目根 .gitignore 追加 .cli_control/（默认会追加，"
+            "忽略 daemon 的机器本地状态目录）。--skills-only 模式下本就跳过。"
+        ),
+    )
     skills_group = init_p.add_mutually_exclusive_group()
     skills_group.add_argument(
         "--no-skills",

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/python/godot_cli_control/init_cmd.py

@@ -8,6 +8,8 @@
    绕过 Godot Editor GUI 启用步骤
 4. 自动检测 Godot 二进制，写入 ``.cli_control/godot_bin``，daemon 启动时
    会优先读取此文件
+5. 在项目根 ``.gitignore`` 追加 ``.cli_control/`` —— daemon 的机器本地状态
+   目录（godot_bin 绝对路径 / pid / port / log / 录制中间产物），不应提交
 
 完成后用户只需 ``godot-cli-control daemon start`` 即可。
 """
@@ -26,6 +28,12 @@ from .daemon import find_godot_binary, reimport_project
 PLUGIN_DIR_NAME = "godot_cli_control"
 ADDONS_DIRNAME = "addons"
 
+GITIGNORE_NAME = ".gitignore"
+# 需要 init 写进目标项目 .gitignore 的条目。用元组而非单值，给将来"增量加
+# 忽略项"留口子（与 method_blacklist_extra 同样的增量哲学）；目前只有 daemon
+# 的机器本地状态目录 .cli_control/。
+GITIGNORE_ENTRIES: tuple[str, ...] = (".cli_control/",)
+
 AUTOLOAD_KEY = "GameBridgeNode"
 AUTOLOAD_VALUE = '"*res://addons/godot_cli_control/bridge/game_bridge.gd"'
 PLUGIN_CFG_PATH = "res://addons/godot_cli_control/plugin.cfg"
@@ -43,6 +51,7 @@ def run_init(
     write_skills: bool = True,
     skills_only: bool = False,
     clobber_skills: bool = True,
+    write_gitignore: bool = True,
     *,
     output_format: str = "text",
     result: dict[str, Any] | None = None,
@@ -56,6 +65,9 @@ def run_init(
     ``clobber_skills=False``：写 skill 时遇到已存在文件就跳过（用户改过
     SKILL.md、希望保留本地版又允许 init 把缺失那条补上时用）。与
     ``write_skills=False`` / ``skills_only=True`` 都兼容。
+    ``write_gitignore=False``：跳过往项目根 ``.gitignore`` 追加 ``.cli_control/``
+    （不想让 init 碰 ``.gitignore`` 的用户逃生口）。该步骤属于"项目接入"阶段，
+    ``skills_only=True`` 时本就跳过。
 
     ``output_format='json'``：抑制全部人类可读 print；调用方（cli.cmd_init）
     传入 ``result`` 字典，本函数会回填结构化字段，由 cli 侧封 JSON envelope。
@@ -93,6 +105,7 @@ def run_init(
         project_godot_changes=[],
         godot_bin=None,
         skills_written=[],
+        gitignore_added=[],
     )
 
     if not (project_root / "project.godot").is_file():
@@ -157,6 +170,15 @@ def run_init(
                 "（跳过资源重新导入；首次 daemon start 会兜底重建 cache）"
             )
 
+        # .gitignore：无条件确保（不依赖 godot_bin 是否检测到——daemon 早晚
+        # 会建 .cli_control/，提前忽略最稳）。属于"项目接入"阶段，故在
+        # not skills_only 块内。
+        if write_gitignore:
+            added = _ensure_gitignore_entries(project_root)
+            if added:
+                _say(f"修改 .gitignore：忽略 {', '.join(added)}")
+            _record(gitignore_added=added)
+
     if write_skills:
         # lazy import：保持与 cli.cmd_init 那侧 `from .init_cmd import run_init`
         # 对称，两边都不在模块顶层 import，避免任一方将来改成顶层 import
@@ -319,3 +341,69 @@ def _ensure_in_packed_array(
         body.rstrip("\n") + "\n" + f'{key}=PackedStringArray("{value}")\n'
     )
     return text[:start] + new_body + text[end:], True
+
+
+# ── .gitignore 维护 ──
+
+
+def _gitignore_has_entry(text: str, entry: str) -> bool:
+    """``.gitignore`` 文本里是否已忽略 ``entry``。
+
+    宽松匹配：忽略前导 ``/`` 与尾随 ``/``、行首尾空白，所以 ``.cli_control``、
+    ``.cli_control/``、``/.cli_control/`` 视为同一条，不重复加。注释行（``#`` 开头）
+    不算数 —— 用户把它注释掉就是想让它失效，真条目仍要补。
+    """
+    target = entry.strip().strip("/")
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.strip("/") == target:
+            return True
+    return False
+
+
+def _add_gitignore_entries(
+    text: str, entries: tuple[str, ...] | list[str]
+) -> tuple[str, list[str]]:
+    """纯函数：把缺失的 ``entries`` 追加到 ``.gitignore`` 文本末尾。
+
+    返回 ``(新文本, 实际新增的条目列表)``。已存在的条目跳过。追加前确保末尾
+    有换行，避免把新条目黏到原末行后面；空文本不留前导空行。行尾统一用
+    ``\\n``，CRLF 回写交给 IO 包装层（与 ``_patch_project_godot`` 同构）。
+    """
+    added: list[str] = []
+    out = text
+    for entry in entries:
+        if _gitignore_has_entry(out, entry):
+            continue
+        if out and not out.endswith("\n"):
+            out += "\n"
+        out += entry + "\n"
+        added.append(entry)
+    return out, added
+
+
+def _ensure_gitignore_entries(
+    project_root: Path, entries: tuple[str, ...] = GITIGNORE_ENTRIES
+) -> list[str]:
+    """确保项目根 ``.gitignore`` 忽略 ``entries``；返回实际新增的条目。
+
+    文件不存在则创建（LF）。已存在则沿用 ``_patch_project_godot`` 的 bytes+CRLF
+    思路：读 bytes、探测原文是否 CRLF、解码时折成 LF 便于匹配，仅在确有新增时
+    回写并把行尾翻回原样 —— 保 Windows 上 git diff 不被整文件行尾翻转污染。
+    """
+    path = project_root / GITIGNORE_NAME
+    if path.exists():
+        raw = path.read_bytes()
+        is_crlf = b"\r\n" in raw
+        text = raw.decode("utf-8").replace("\r\n", "\n")
+    else:
+        is_crlf = False
+        text = ""
+
+    new_text, added = _add_gitignore_entries(text, entries)
+    if added:
+        out = new_text.replace("\n", "\r\n") if is_crlf else new_text
+        path.write_bytes(out.encode("utf-8"))
+    return added

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/python/godot_cli_control/templates/skill/SKILL.md

@@ -85,7 +85,7 @@ $ godot-cli-control --text exists /root/Main
 true
 
 $ godot-cli-control init
-{"ok": true, "result": {"project_root": "/path/to/proj", "plugin_copied": true, "plugin_overwritten": false, "project_godot_changes": ["autoload/GameBridgeNode", "editor_plugins/enabled"], "godot_bin": "/usr/bin/godot", "skills_written": [".../SKILL.md", ".../SKILL.md"], "skills_only": false, "write_skills": true}}
+{"ok": true, "result": {"project_root": "/path/to/proj", "plugin_copied": true, "plugin_overwritten": false, "project_godot_changes": ["autoload/GameBridgeNode", "editor_plugins/enabled"], "godot_bin": "/usr/bin/godot", "skills_written": [".../SKILL.md", ".../SKILL.md"], "gitignore_added": [".cli_control/"], "skills_only": false, "write_skills": true}}
 
 $ godot-cli-control run my_script.py
 {"ok": true, "result": {"exit_code": 0, "script": "my_script.py"}}

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/python/tests/test_cli.py

@@ -723,6 +723,7 @@ def test_cmd_init_catches_unexpected_exception_into_envelope(
         no_skills=False,
         skills_only=False,
         skills_no_clobber=False,
+        no_gitignore=False,
         output_format=OUTPUT_JSON,
     )
     rc = cmd_init(ns)

{godot_cli_control-0.2.11 → godot_cli_control-0.2.12}/python/tests/test_init.py

@@ -428,6 +428,7 @@ def test_cmd_init_emits_success_envelope_in_json_mode(
         no_skills=False,
         skills_only=False,
         skills_no_clobber=False,
+        no_gitignore=False,
         output_format=OUTPUT_JSON,
     )
     rc = cmd_init(ns)
@@ -459,6 +460,7 @@ def test_cmd_init_emits_error_envelope_on_non_godot_dir(
         no_skills=False,
         skills_only=False,
         skills_no_clobber=False,
+        no_gitignore=False,
         output_format=OUTPUT_JSON,
     )
     rc = cmd_init(ns)
@@ -469,3 +471,184 @@ def test_cmd_init_emits_error_envelope_on_non_godot_dir(
     assert payload["ok"] is False
     assert payload["error"]["code"] == -1003  # CLIENT_CODE_USAGE
     assert "project.godot" in payload["error"]["message"]
+
+
+# ── .gitignore 维护（确保 .cli_control/ 不被提交）──
+
+
+def test_gitignore_adds_entry_to_empty_text() -> None:
+    """纯函数：空文本追加条目。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    out, added = _add_gitignore_entries("", [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert out == ".cli_control/\n"
+    # 不允许出现前导空行
+    assert not out.startswith("\n")
+
+
+def test_gitignore_appends_preserving_existing_entries() -> None:
+    """已有别的忽略项时只追加、不动原内容。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    text = "*.tmp\nbuild/\n"
+    out, added = _add_gitignore_entries(text, [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert "*.tmp" in out
+    assert "build/" in out
+    assert out.endswith(".cli_control/\n")
+
+
+def test_gitignore_idempotent_when_entry_present() -> None:
+    """已含完全相同条目 → 不重复加。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    text = "build/\n.cli_control/\n"
+    out, added = _add_gitignore_entries(text, [".cli_control/"])
+    assert added == []
+    assert out == text
+
+
+@pytest.mark.parametrize(
+    "existing",
+    [".cli_control\n", "/.cli_control/\n", "/.cli_control\n", ".cli_control/  \n"],
+)
+def test_gitignore_idempotent_on_equivalent_variants(existing: str) -> None:
+    """带/不带斜杠、带前导 / 、带尾随空白都视为已忽略，不重复加。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    out, added = _add_gitignore_entries(existing, [".cli_control/"])
+    assert added == []
+    assert out == existing
+
+
+def test_gitignore_commented_line_does_not_count_as_present() -> None:
+    """被注释掉的同名行不算忽略，真条目仍要补上。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    text = "# .cli_control/\n"
+    out, added = _add_gitignore_entries(text, [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert "# .cli_control/" in out  # 注释保留
+    assert out.endswith(".cli_control/\n")
+
+
+def test_gitignore_appends_newline_when_file_lacks_trailing_one() -> None:
+    """原文件末行无换行符时，新条目必须独立成行、不黏在末行后面。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    out, added = _add_gitignore_entries("build/", [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert out == "build/\n.cli_control/\n"
+
+
+def test_ensure_gitignore_creates_file_when_missing(tmp_path: Path) -> None:
+    """项目根没有 .gitignore → 创建并写入 .cli_control/。"""
+    from godot_cli_control.init_cmd import _ensure_gitignore_entries
+
+    added = _ensure_gitignore_entries(tmp_path)
+    gi = tmp_path / ".gitignore"
+    assert gi.is_file()
+    assert ".cli_control/" in gi.read_text(encoding="utf-8")
+    assert added == [".cli_control/"]
+
+
+def test_ensure_gitignore_idempotent_across_runs(tmp_path: Path) -> None:
+    """连跑两次只写一条，不重复。"""
+    from godot_cli_control.init_cmd import _ensure_gitignore_entries
+
+    _ensure_gitignore_entries(tmp_path)
+    added2 = _ensure_gitignore_entries(tmp_path)
+    assert added2 == []
+    content = (tmp_path / ".gitignore").read_text(encoding="utf-8")
+    assert content.count(".cli_control/") == 1
+
+
+def test_ensure_gitignore_preserves_crlf(tmp_path: Path) -> None:
+    """已有 CRLF 的 .gitignore 在追加后必须仍是 CRLF，不混入裸 LF。"""
+    from godot_cli_control.init_cmd import _ensure_gitignore_entries
+
+    gi = tmp_path / ".gitignore"
+    gi.write_bytes(b"*.tmp\r\nbuild/\r\n")
+    _ensure_gitignore_entries(tmp_path)
+    after = gi.read_bytes()
+    assert b".cli_control/\r\n" in after
+    bare_lf = after.count(b"\n") - after.count(b"\r\n")
+    assert bare_lf == 0, f"出现裸 LF：{bare_lf} 处"
+
+
+def test_run_init_adds_cli_control_to_gitignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """端到端：run_init 默认在项目根 .gitignore 忽略 .cli_control/。"""
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _minimal_project(tmp_path)
+    assert run_init(proj) == 0
+    gi = (proj / ".gitignore").read_text(encoding="utf-8")
+    assert ".cli_control/" in gi
+
+
+def test_run_init_no_gitignore_skips_gitignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """write_gitignore=False → 不创建 / 不改 .gitignore。"""
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _minimal_project(tmp_path)
+    assert run_init(proj, write_gitignore=False) == 0
+    assert not (proj / ".gitignore").exists()
+
+
+def test_run_init_skills_only_skips_gitignore(tmp_path: Path) -> None:
+    """skills_only 属于纯刷 SKILL.md，不应碰 .gitignore。"""
+    proj = _make_min_godot_project(tmp_path)
+    assert run_init(proj, skills_only=True) == 0
+    assert not (proj / ".gitignore").exists()
+
+
+def test_run_init_json_records_gitignore_added(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """json 模式 result 必须回填 gitignore_added 字段。"""
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _make_min_godot_project(tmp_path)
+    result: dict[str, object] = {}
+    assert run_init(proj, output_format="json", result=result) == 0
+    assert result["gitignore_added"] == [".cli_control/"]
+
+
+def test_cmd_init_no_gitignore_flag_skips(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """CLI 层：--no-gitignore（ns.no_gitignore=True）不写 .gitignore。"""
+    import argparse
+
+    from godot_cli_control.cli import OUTPUT_JSON, cmd_init
+
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _make_min_godot_project(tmp_path)
+    ns = argparse.Namespace(
+        path=str(proj),
+        force=False,
+        no_skills=False,
+        skills_only=False,
+        skills_no_clobber=False,
+        no_gitignore=True,
+        output_format=OUTPUT_JSON,
+    )
+    assert cmd_init(ns) == 0
+    capsys.readouterr()
+    assert not (proj / ".gitignore").exists()