davinci-resolve-mcp 3.2.1 → 3.2.2

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v3.2.2 — an analysis root that is deleted is actually let go of
+
+Contributed by @Dev-next-gen (#228), generalised to the second site and to the
+connection cache underneath both.
+
+### Fixed
+
+- **`cleanup_artifacts(frames_only=false)` reported success whether or not it
+  removed anything.** The analysis root contains
+  `_soul/timeline_brain.sqlite`, which `timeline_brain_db` keeps open in a
+  process-wide cache for the life of the server. Nothing let go of it before
+  the `shutil.rmtree`, and the rmtree runs with `ignore_errors=True`, so both
+  failure modes were swallowed. On Windows the open handle makes the DB
+  undeletable: the root survives with `_soul/` and the brain-edit history still
+  in it while the tool returns `{"success": true}`. On POSIX the root is
+  removed but the stale connection stays cached, so the next write for that
+  project goes to a file with no directory entry and is lost — the dashboard,
+  which opens the path fresh, sees nothing. `timeline_brain_db.close()` now
+  releases one project's connection, and the cleanup returns `success: false`
+  if the root is still on disk afterwards. (#228)
+- **The same bug at a second site.** A `session_only` run without
+  `keep_artifacts` ingests every report into the brain DB under its output root
+  and then deletes that root, with the connection still cached. Because each
+  such run gets a fresh temp root, the cache accumulated one dead connection
+  per run. Both sites now go through one helper, and
+  `artifacts_cleaned_up` reports whether the removal happened rather than that
+  it was attempted.
+- **`close()` released nothing when the root was spelled differently.** The
+  connection cache keyed on the caller's spelling of the path, and callers
+  disagree by construction: `media_analysis` realpaths a root before using it,
+  while its own callers pass what the user typed. On macOS that alone was
+  enough — every temp root under `/var/folders` is a symlink to
+  `/private/var/folders` — so `close()` computed a key that was never in the
+  cache, popped nothing, and the fix above silently did not apply. Two
+  spellings of one root also opened two connections to one SQLite file. The
+  cache now keys on the resolved DB path.
+
+### Release process
+
+- **`tests.test_release_surface_drift` is now in the documented gate list.** It
+  asserts the README badge, the `README.zh-CN.md` badge and translation line,
+  and a `CHANGELOG.md` entry all match `package.json` — and it was the one
+  version-surface check missing from `docs/process/release-process.md`. v3.2.1
+  shipped with a zh-CN badge still reading v3.2.0 because every documented gate
+  passed while none of them looks at a version surface. That badge is corrected
+  here.
+
 ## What's New in v3.2.1 — three correctness fixes to the LUT tool
 
 Contributed by @Dev-next-gen (#225, #226, #227), each found by reading the v3.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.2.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.2.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(384%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-3.2.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.2.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(384%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v3.2.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v3.2.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/process/release-process.md

@@ -75,7 +75,7 @@ venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
 venv/bin/python scripts/audit_readwrite_symmetry.py --check
 node scripts/agent-rules/generate.mjs --check
-venv/bin/python -m unittest tests.test_static_undefined_names tests.test_duplicate_definitions tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift
+venv/bin/python -m unittest tests.test_static_undefined_names tests.test_duplicate_definitions tests.test_action_list_drift tests.test_panel_docs_drift tests.test_doc_tool_counts tests.test_agent_rules_drift tests.test_release_surface_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version
 npm pack --dry-run
@@ -89,6 +89,13 @@ regeneration is in the working tree when the test reads it — that ordering is
 the check is a regeneration followed by a test, not a `git diff --exit-code`,
 which would fire on the release bump's own legitimate change.
 
+`test_release_surface_drift` is the gate on the version bump itself: it asserts
+the README badge, the `README.zh-CN.md` badge and its `本翻译对应 vX.Y.Z` line, and
+a `CHANGELOG.md` entry all match `package.json`. It was not in this list until
+v3.2.2, and v3.2.1 shipped with a zh-CN badge still reading v3.2.0 as a direct
+result — every other gate passed, because none of them looks at a version
+surface. Run it before tagging, not after.
+
 `test_duplicate_definitions` asserts no module-level name is defined twice under
 `src/`. A second `def foo` silently replaces the first, and in a module the size
 of `src/server.py` the two can be thousands of lines apart with different

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.2.1"
+VERSION = "3.2.2"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.2.1"
+VERSION = "3.2.2"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "3.2.1"
+VERSION = "3.2.2"
 
 import base64
 import os

package/src/utils/media_analysis.py

@@ -2590,6 +2590,48 @@ def _read_json(path: str) -> Dict[str, Any]:
         return json.load(f)
 
 
+def _drop_brain_db_and_rmtree(project_root: str, cleanup_root: str) -> bool:
+    """Delete `cleanup_root`, releasing `project_root`'s brain DB first.
+
+    `<project_root>/_soul/timeline_brain.sqlite` is held open in a
+    process-wide cache for the life of the server, and nothing else lets go of
+    it. Deleting the root underneath that handle fails differently on each
+    platform and silently on both, because rmtree runs with
+    ``ignore_errors=True``:
+
+    - Windows refuses to delete the open file, so the root survives with
+      `_soul/` and the brain-edit history still in it while the caller is told
+      it is gone.
+    - POSIX unlinks it, but the cache then hands the next writer a connection
+      to a file with no directory entry, so the write lands nowhere.
+
+    Returns whether `cleanup_root` is actually gone afterwards, so callers can
+    report a removal that happened rather than one they attempted.
+    """
+    from src.utils import timeline_brain_db as _brain_db
+
+    _brain_db.close(project_root)
+    shutil.rmtree(cleanup_root, ignore_errors=True)
+    return not os.path.isdir(cleanup_root)
+
+
+def _release_session_root(manifest: Dict[str, Any], project_root: str,
+                          cleanup_root: str) -> bool:
+    """Session-only artifact cleanup: same rule as `cleanup_artifacts`.
+
+    A session-only run ingests every report into the brain DB under
+    `project_root` and then throws the root away, and each run gets a fresh
+    temp root -- so without the release the cache accumulates one dead
+    connection per run.
+    """
+    removed = _drop_brain_db_and_rmtree(project_root, cleanup_root)
+    if not removed:
+        manifest.setdefault("memory_layer_warnings", []).append(
+            f"Could not fully remove the session analysis root: {cleanup_root}"
+        )
+    return removed
+
+
 def _ingest_report_into_db(project_root: str, report: Dict[str, Any], clip_dir: Optional[str]) -> Dict[str, Any]:
     """C1 — write a report into the DB-canonical store (rows in a transaction).
 
@@ -5971,8 +6013,9 @@ async def execute_plan_async(
                     and _is_relative_to(output_root, candidate)
                 ):
                     cleanup_root = candidate
-            shutil.rmtree(cleanup_root, ignore_errors=True)
-            manifest["artifacts_cleaned_up"] = True
+            manifest["artifacts_cleaned_up"] = _release_session_root(
+                manifest, output_root, cleanup_root
+            )
             manifest["artifact_cleanup_root"] = cleanup_root
 
     return manifest
@@ -7057,7 +7100,14 @@ def cleanup_artifacts(project_root: str, *, frames_only: bool = True) -> Dict[st
                     shutil.rmtree(full, ignore_errors=True)
                     removed.append(full)
     else:
-        shutil.rmtree(root, ignore_errors=True)
+        # The whole root goes, including `_soul/timeline_brain.sqlite`.
+        if not _drop_brain_db_and_rmtree(root, root):
+            return {
+                "success": False,
+                "error": f"Could not fully remove the project analysis root: {root}",
+                "removed": removed,
+                "frames_only": frames_only,
+            }
         removed.append(root)
     return {"success": True, "removed": removed, "frames_only": frames_only}
 

package/src/utils/timeline_brain_db.py

@@ -50,6 +50,26 @@ def db_path_for_project(project_root: str) -> str:
     return os.path.join(project_root, SOUL_DIRNAME, DB_FILENAME)
 
 
+def _cache_key(project_root: str) -> str:
+    """The connection-cache key for a project root: its DB path, realpath'd.
+
+    Two spellings of one root must not become two cached connections to one
+    file. They do without this, because callers disagree about spelling by
+    construction -- `media_analysis` normalizes a root through `realpath`
+    before using it, while its own callers pass whatever the user typed. On
+    macOS that alone is enough: every temp root under `/var/folders/...` is a
+    symlink to `/private/var/folders/...`.
+
+    The damage is not just a duplicate. `close()` pops by key, so a mismatch
+    makes it silently no-op and leave the connection it was called to release
+    -- which is the whole point of calling it before deleting the root.
+
+    `realpath` on a path that does not exist yet resolves the ancestors that do
+    and leaves the rest literal, which is what a not-yet-created DB needs.
+    """
+    return os.path.realpath(db_path_for_project(project_root))
+
+
 def _ensure_parent_dir(path: str) -> None:
     os.makedirs(os.path.dirname(path), exist_ok=True)
 
@@ -224,7 +244,7 @@ def connect(project_root: str) -> sqlite3.Connection:
     """
     if not project_root:
         raise ValueError("project_root is required")
-    path = db_path_for_project(project_root)
+    path = _cache_key(project_root)
     with _CONNECTION_LOCK:
         existing = _CONNECTIONS.get(path)
         if existing is not None:
@@ -250,6 +270,25 @@ def close_all() -> None:
         _CONNECTIONS.clear()
 
 
+def close(project_root: str) -> None:
+    """Drop and close the cached connection for `project_root`, if any.
+
+    Callers that are about to delete or move a project's analysis root need
+    this. On Windows the open handle makes `_soul/timeline_brain.sqlite`
+    undeletable; on POSIX the cache would otherwise hand the next writer a
+    connection to a file that no longer has a directory entry, so the write
+    lands nowhere.
+    """
+    path = _cache_key(project_root)
+    with _CONNECTION_LOCK:
+        conn = _CONNECTIONS.pop(path, None)
+    if conn is not None:
+        try:
+            conn.close()
+        except sqlite3.Error:
+            pass
+
+
 @contextmanager
 def transaction(project_root: str) -> Iterator[sqlite3.Connection]:
     """Context manager wrapping a write transaction.
@@ -291,14 +330,8 @@ def transaction(project_root: str) -> Iterator[sqlite3.Connection]:
 
 def reset_for_test(project_root: str) -> None:
     """Drop + recreate every table. Tests only."""
-    path = db_path_for_project(project_root)
-    with _CONNECTION_LOCK:
-        conn = _CONNECTIONS.pop(path, None)
-        if conn is not None:
-            try:
-                conn.close()
-            except sqlite3.Error:
-                pass
+    path = _cache_key(project_root)
+    close(project_root)
     for suffix in ("", "-wal", "-shm"):
         try:
             os.remove(path + suffix)