davinci-resolve-mcp 3.2.0 → 3.2.2

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 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
+`lut` tool rather than by hitting it in use.
+
+### Fixed
+
+- **`install` reported `overwritten: true` on a fresh write.** The flag was
+  `bool(overwrite and payload is not None)`, and `payload` can never be `None`
+  where that line runs, so the field handed the caller's own `overwrite`
+  argument back instead of an observation. An install passing `overwrite=true`
+  for idempotence, landing on an empty `MCP/`, was reported as having replaced
+  existing work. `execution_lifecycle` rates `lut install` MEDIUM precisely
+  because it "can replace with overwrite=true", so this flag is what a caller
+  and the execution trace read to learn whether an install destroyed anything.
+  It is now the `os.path.exists` observation already taken one line above — the
+  measured pre-state, not the permission. (#225)
+- **`install(source_path=...)` could not copy a binary LUT.** The copy went
+  through a UTF-8 text round-trip, so the two binary extensions this server
+  advertises — `.dat` and `.olut` — raised `UnicodeDecodeError` before anything
+  was written, surfacing as `LUT_ERROR`. So did an ordinary `.cube` whose vendor
+  wrote its `TITLE` line in latin-1. The file-copy branch is now byte-exact; the
+  text branch (`source=`) is unchanged. (#226)
+- **`list` marked siblings of the writable subdir as writable.** The `writable`
+  flag used `realpath(current).startswith(writable_root)`, a string prefix with
+  no separator, so `MCP_old/` left by a hand backup or a vendor pack unpacking
+  as `MCPresets/` cleared it. The listing then contradicted the only tool that
+  consumes the flag: `remove` resolves names inside `MCP/` and refused the very
+  `set_lut_path` the listing had just handed out. It now compares by path
+  segment with `commonpath`, which is what `_is_relative_to` and `resolve_writable`
+  already use elsewhere in this repo. Nothing that worked before stops working —
+  the flag only flips for paths `remove` was already refusing. (#227)
+
 ## What's New in v3.2.0 — LUT files: find them, install them, remove them, gated
 
 Contributed by @legionsound (#223), live-validated on Studio 21.1.0.14.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.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)](#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.0 版 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.0"
+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.0",
+  "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.0"
+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.0"
+VERSION = "3.2.2"
 
 import base64
 import os

package/src/utils/lut_files.py

@@ -50,6 +50,20 @@ def writable_dir() -> str:
     return os.path.join(master_lut_dir(), WRITABLE_SUBDIR)
 
 
+def _is_within(path: str, parent: str) -> bool:
+    """Whether ``path`` is ``parent`` itself or sits under it, compared by segment.
+
+    ``commonpath`` is the comparison the rest of the repo uses for confinement
+    checks (`media_analysis._is_relative_to`), and it is the only one that is
+    correct here: a string prefix test also accepts a sibling whose name merely
+    starts with the same characters.
+    """
+    try:
+        return os.path.commonpath([path, parent]) == parent
+    except (ValueError, OSError):
+        return False
+
+
 def normalize_relative(name: str, *, default_ext: Optional[str] = None) -> str:
     """Validate a caller-supplied LUT name and return it as a POSIX relative path.
 
@@ -123,7 +137,13 @@ def list_luts(subdir: Optional[str] = None) -> Dict[str, Any]:
             except OSError:
                 size = None
             try:
-                is_writable = os.path.realpath(current).startswith(writable_root)
+                # Segment-wise, not a string prefix: a sibling of the writable
+                # subdir whose name starts with it -- MCP_old/ after a manual
+                # backup, MCPresets/ from a vendor pack -- cleared
+                # `startswith(writable_root)` and was listed as writable, while
+                # `remove` resolves names under MCP/ and refuses the very path
+                # the listing handed back.
+                is_writable = _is_within(os.path.realpath(current), writable_root)
             except OSError:
                 is_writable = False
             found.append({
@@ -154,28 +174,45 @@ def install_lut(name: str, *, source: Optional[str] = None,
     if (source is None) == (source_path is None):
         raise LutPathError("provide exactly one of source (text) or source_path (a file to copy)")
     absolute, set_lut_path = resolve_writable(name)
-    if os.path.exists(absolute) and not overwrite:
+    existed = os.path.exists(absolute)
+    if existed and not overwrite:
         raise LutPathError(
             f"{set_lut_path} already exists. Pass overwrite=true to replace it."
         )
     if source_path is not None:
         if not os.path.isfile(source_path):
             raise LutPathError(f"source_path not found: {source_path}")
-        with open(source_path, "r", encoding="utf-8", errors="strict") as handle:
+        # A copy has to be byte-exact. Two of the extensions this server
+        # advertises -- .dat and .olut -- are binary, and a .cube carries its
+        # TITLE in whatever encoding the vendor wrote it in, so decoding the
+        # source as UTF-8 turned "install the LUT I already have on disk" into
+        # a UnicodeDecodeError surfacing as LUT_ERROR.
+        with open(source_path, "rb") as handle:
             payload = handle.read()
     else:
         payload = source
     if not payload.strip():
         raise LutPathError("refusing to install an empty LUT")
     os.makedirs(os.path.dirname(absolute), exist_ok=True)
-    with open(absolute, "w", encoding="utf-8") as handle:
-        handle.write(payload)
+    if isinstance(payload, bytes):
+        with open(absolute, "wb") as handle:
+            handle.write(payload)
+    else:
+        with open(absolute, "w", encoding="utf-8") as handle:
+            handle.write(payload)
     return {
         "success": True,
         "path": absolute,
         "set_lut_path": set_lut_path,
         "bytes": os.path.getsize(absolute),
-        "overwritten": bool(overwrite and payload is not None),
+        # Whether a file was actually replaced, not whether the caller allowed
+        # it: `payload is not None` is always true here, so this reported a
+        # replacement for every overwrite=true install, including the ones that
+        # landed on an empty MCP/. This flag is the record of what an install
+        # destroyed -- execution_lifecycle rates `lut install` on the fact that
+        # it "can replace with overwrite=true" -- so it has to be the observed
+        # pre-state, not the permission.
+        "overwritten": existed,
         "note": ("Call project_settings(action='refresh_luts') so Resolve picks up "
                  "the new file before applying it."),
     }

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)