davinci-resolve-mcp 2.27.1 → 2.28.0

package/CHANGELOG.md

@@ -2,6 +2,96 @@
 
 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 v2.28.0
+
+This release adds a structural timeline-diff engine, a declarative project spec
+you can `apply` like infrastructure-as-code, a project health `lint`, a clip
+query DSL, and a machine-readable `state` field on error responses.
+
+**Timeline version diff — see exactly what an edit changed.** Comparing two
+archived timeline versions now reports clips that were **added, removed, moved,
+and trimmed**, plus summary counts and before/after clip totals. A new reusable
+diff engine aligns clips by a rename-stable identity (so a reordered or renamed
+clip reads as a move/change, not a delete-and-re-add).
+
+- `timeline_versioning(action="diff_versions", timeline_name, from_version, to_version)`
+  now returns `{added, removed, moved, trimmed, summary}` (the previous
+  `added`/`removed`/`moved` keys are unchanged).
+- Dashboard endpoint `GET /api/timeline_versions/diff?timeline_name=&from_version=&to_version=`
+  exposes the same diff to the control panel.
+
+**Declarative project spec + `apply` — reproducible project setup.** Describe a
+project's desired settings, color preset, timelines, and markers in a
+`project.dvr.yaml` (or `.json`), then reconcile the live project toward it. Runs
+are **idempotent** — applying twice is a no-op — and a dry run previews every
+change before anything is touched.
+
+- New MCP actions on `project_manager`:
+  - `diff_to_spec(spec_path | spec)` — preview drift without mutating.
+  - `plan_spec(spec_path | spec)` — the ordered action list (dry run).
+  - `apply_spec(spec_path | spec, dry_run?, run_hooks?, continue_on_error?)` —
+    reconcile. Color/HDR settings apply in dependency order; markers are only
+    added when absent; an explicit `color_preset` can be overridden by explicit
+    `settings`. Failures can abort on first error or accumulate.
+- New headless CLI commands: `davinci-resolve-mcp batch plan-spec SPEC` and
+  `davinci-resolve-mcp batch apply SPEC [--dry-run] [--run-hooks] [--continue-on-error]`.
+  Exit codes follow the existing convention (`0` ok, `2` partial, `3` fatal).
+- Optional before/after shell **hooks** in the spec run only when `run_hooks` is
+  passed (opt-in).
+
+**Project health `lint` — a pre-flight before editing.** `project_manager(action="lint")`
+returns a graded issue list (errors / warnings / info) covering: no project, no
+current timeline, mixed frame rates across timelines, empty timelines, unset
+render format, unmanaged color science, offline media, and unanalyzed clips.
+
+**Clip query DSL — find clips in one call.** `timeline(action="clip_where", ...)`
+returns the clips on the current timeline matching named filters (AND), instead
+of enumerating tracks by hand. Live filters: `track_type`, `track_index`,
+`name_contains`, `duration_lt`, `duration_gt`. A typo'd filter name is rejected
+rather than silently matching everything.
+
+**Machine-readable error context.** Structured error responses can now carry an
+optional `state` object — a snapshot of the relevant values at failure time
+(e.g. which filter was unknown, which spec failed and where) — so an agent can
+react without parsing prose. Existing error fields are unchanged.
+
+## What's New in v2.27.2
+
+**Control panel under-counted analyzed clips after a Media Pool rename (issue
+#51)** — with every clip analyzed (e.g. 303/303 reports on disk), the overview
+and Media tab could report something like "108 / 303 analyzed". The panel only
+recognized a report when a folder's name exactly matched the clip's *current*
+display name, so renaming clips after analysis hid their existing reports even
+though the underlying media was unchanged.
+
+Root cause and fix:
+
+- **Lookups are keyed by a rename-stable hash, not the display-name folder.**
+  Report folders are named `<display-slug>-<hash>`; the count now matches on the
+  trailing hash (and the ids inside each report), so a renamed clip still
+  resolves to its existing folder. Both the disk path and the jobs-DB fallback
+  were corrected.
+- **The hash is now anchored to the normalized file path (canonical basis).**
+  Previously the basis was a `clip_id`-first cascade, so the same media hashed
+  differently depending on which fields a record carried — Resolve inventory
+  (clip_id) vs path-based batch jobs (file path) disagreed on the same clip.
+  Anchoring to the file path removes that cross-basis mismatch. Legacy folders
+  (clip_id-based, or raw-path-based) still resolve via a migration-safe set of
+  candidate hashes, so **no on-disk migration is required**.
+- **Writes reuse an existing report folder** (matched by canonical or legacy
+  hash) instead of minting a new `<newslug>-<hash>` directory, eliminating
+  orphaned duplicate folders when a renamed clip is re-analyzed.
+- **A persisted clip index (`clips/index.json`)** maps every stable id found in
+  a report (normalized + raw file path, clip_id, media_id) to its folder, so the
+  count can still match a clip by any id it carries — including an offline clip
+  that no longer reports a file path but retains its clip_id. The index is
+  refreshed only when a report is added, removed, or rewritten (cheap signature
+  check), so the recurring poll stays inexpensive.
+
+No public MCP tool surface changed. Adds regression tests in
+`tests/test_media_analysis.py` covering rename, cross-basis, legacy-folder reuse,
+the jobs-DB fallback, and the offline/no-path case.
+
 ## What's New in v2.27.1
 
 **Faster control-panel startup with network source media (issue #50)** — on

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.27.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.28.0-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-32%20(329%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -355,6 +355,26 @@ lifecycle, settings, database, preset, and archive boundary helpers:
 - `preset_lifecycle_probe`
 - `project_boundary_report`
 
+Health check and declarative spec (v2.28.0+):
+
+- `lint` — graded project health pre-flight returning `{ok, counts, issues}`.
+  Issues (error / warning / info) cover: no project, no current timeline, mixed
+  frame rates across timelines, empty timeline, render format unset, color
+  science unmanaged, offline media, and unanalyzed clips. Composed from existing
+  probes; safe read-only.
+- `diff_to_spec(spec_path | spec)` — preview drift between a declarative spec and
+  the live project WITHOUT mutating. Returns `{actions, diff, change_count}`.
+- `plan_spec(spec_path | spec)` — the ordered action list as a dry run.
+- `apply_spec(spec_path | spec, dry_run?, run_hooks?, continue_on_error?)` —
+  reconcile the project toward the spec. Idempotent (re-runs are no-ops); color/
+  HDR settings apply in dependency order; markers added only when absent; explicit
+  `settings` override a named `color_preset`; before/after shell hooks run only
+  with `run_hooks=true`. The spec is YAML or JSON:
+  `{project, color_preset?, settings?, timelines:[{name, fps?, settings?, markers?}], hooks?}`.
+  Note: `apply_spec` reconciles the **currently open or already-existing** project;
+  creating a brand-new project from a spec depends on Resolve's `CreateProject`
+  succeeding (it can return None when an unsaved project blocks the switch).
+
 Safe project actions require `_mcp_` names and temp paths by default. Database
 switching dry-runs by default because Resolve closes open projects when
 switching databases. Archive source media/cache/proxy flags are rejected unless
@@ -584,8 +604,10 @@ Key actions:
   `initiator`, `thumbnail_path`, and `drt_export_path` (set when the version
   was retention-collapsed to disk).
 - `diff_versions(timeline_name, from_version, to_version)` — structural diff
-  between two snapshots: `{added, removed, moved}` lists of clips by
-  media_pool_item_id and timeline position.
+  between two snapshots: `{added, removed, moved, trimmed, summary}`. `trimmed`
+  lists clips kept in place but re-trimmed (carries `out_frame_before`); `summary`
+  has per-bucket counts plus `before_clip_count`/`after_clip_count`. Clips are
+  keyed by media_pool_item_id and timeline position.
 - `get_history(timeline_name?, analysis_run_id?, limit?)` — brain-edit rows
   with `edit_type`, `target_metric`, `before_value`, `after_value`, `delta`,
   `rationale`, and `initiator`. Filter by timeline or run; defaults to 50.
@@ -674,6 +696,11 @@ Key actions:
 - `get_track_count(track_type)` — track_type: `"video"`, `"audio"`, `"subtitle"`
 - `add_track(track_type, sub_type?)` / `delete_track(track_type, index)`
 - `get_items(track_type, index)` — items on a track
+- `clip_where(track_type?, track_index?, name_contains?, duration_lt?, duration_gt?)` —
+  (v2.28.0+) return clips on the current timeline matching named filters (AND),
+  instead of walking tracks by hand. Filters may be passed inline or as a
+  `filters` dict; a mistyped filter name is rejected rather than silently
+  matching everything. Returns `{clips, match_count, total_clips}`.
 - `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`
 - `duplicate_clips(clip_ids?, selected?, target_track_index?, track_offset?, placement?, record_frame?, record_frame_offset?, copy_properties?, include_linked?)` —
   duplicate existing video timeline items by re-appending the same Media Pool

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.27.1"
+VERSION = "2.28.0"
 # 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": "2.27.1",
+  "version": "2.28.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -27,7 +27,10 @@ from src.utils.media_analysis import (
     detect_capabilities,
     query_analysis_index,
     resolve_output_root,
+    clip_directory_hash,
+    load_clip_index,
     stable_clip_directory,
+    stable_clip_match_hashes,
 )
 from src.utils.media_analysis_jobs import (
     MEDIA_EXTENSIONS,
@@ -10912,11 +10915,32 @@ def _analysis_status_by_clip(project_root: str, records: List[Dict[str, Any]]) -
     status_by_key: Dict[str, Dict[str, Any]] = {}
     if not keys:
         return status_by_key
+
+    # Resolve each clip to its report via the persisted clip index, which maps
+    # every stable id found in a report (normalized + raw file path, clip_id,
+    # media_id) to its folder. This survives a Media Pool rename, a legacy hash
+    # basis, AND an offline clip that no longer reports a file path but still
+    # carries its clip_id — none of which a folder-name scan can match. See #51.
+    clips_root = os.path.join(project_root, "clips")
+    hash_to_folder = load_clip_index(project_root).get("hash_to_folder") or {}
+
     for record in records:
         clip_key = record.get("clip_key")
         if not clip_key:
             continue
         report_path = os.path.join(project_root, "clips", str(clip_key), "analysis.json")
+        if not os.path.isfile(report_path):
+            # Renamed/legacy/offline clip: the recomputed clip_key no longer
+            # matches the folder on disk. Fall back to any of the clip's stable
+            # hashes via the index.
+            for clip_hash in stable_clip_match_hashes(record):
+                folder = hash_to_folder.get(clip_hash)
+                if not folder:
+                    continue
+                candidate = os.path.join(clips_root, folder, "analysis.json")
+                if os.path.isfile(candidate):
+                    report_path = candidate
+                    break
         if os.path.isfile(report_path):
             status_by_key[str(clip_key)] = {
                 "analysis_status": "analyzed",
@@ -10926,32 +10950,24 @@ def _analysis_status_by_clip(project_root: str, records: List[Dict[str, Any]]) -
     db_path = os.path.join(project_root, "jobs.sqlite")
     if not os.path.isfile(db_path):
         return status_by_key
-    placeholders = ",".join("?" for _ in keys)
-    try:
-        conn = sqlite3.connect(db_path)
-        conn.row_factory = sqlite3.Row
-        rows = conn.execute(
-            f"""
-            SELECT jc.clip_key, jc.status, jc.cache_status, jc.report_path, jc.error,
-                   j.job_id, j.name AS job_name, j.updated_at
-            FROM job_clips jc
-            JOIN jobs j ON j.job_id = jc.job_id
-            WHERE jc.clip_key IN ({placeholders})
-            ORDER BY jc.updated_at DESC
-            """,
-            keys,
-        ).fetchall()
-    except Exception:
-        return status_by_key
-    finally:
-        try:
-            conn.close()
-        except Exception:
-            pass
-    for row in rows:
-        clip_key = str(row["clip_key"])
-        if clip_key in status_by_key and status_by_key[clip_key].get("analysis_status") == "analyzed":
+
+    # The jobs DB stores each clip under the clip_key it had when analyzed. A
+    # clip renamed afterwards produces a new clip_key, so an exact-key match
+    # misses its job row. Index unresolved records by their rename-stable hash
+    # so a DB row recorded under the old name (e.g. a reused batch report living
+    # outside the local clips/ dir) still maps back to the current clip. #51.
+    key_set = {str(k) for k in keys}
+    pending_hash_to_key: Dict[str, str] = {}
+    for record in records:
+        clip_key = record.get("clip_key")
+        if not clip_key or str(clip_key) in status_by_key:
             continue
+        for folder_hash in stable_clip_match_hashes(record):
+            pending_hash_to_key.setdefault(folder_hash, str(clip_key))
+
+    def _apply_row(row: sqlite3.Row, target_key: str) -> None:
+        if status_by_key.get(target_key, {}).get("analysis_status") == "analyzed":
+            return
         db_status = row["status"]
         report_path = row["report_path"]
         # In media_analysis_jobs, 'succeeded' = fresh analysis written this run,
@@ -10969,7 +10985,7 @@ def _analysis_status_by_clip(project_root: str, records: List[Dict[str, Any]]) -
         normalized = db_status
         if db_status in ("succeeded", "skipped") and report_resolves:
             normalized = "analyzed"
-        status_by_key[clip_key] = {
+        status_by_key[target_key] = {
             "analysis_status": normalized,
             "job_status": db_status,
             "cache_status": row["cache_status"],
@@ -10979,6 +10995,45 @@ def _analysis_status_by_clip(project_root: str, records: List[Dict[str, Any]]) -
             "job_name": row["job_name"],
             "job_updated_at": row["updated_at"],
         }
+
+    select_cols = (
+        "SELECT jc.clip_key, jc.status, jc.cache_status, jc.report_path, jc.error, "
+        "j.job_id, j.name AS job_name, j.updated_at "
+        "FROM job_clips jc JOIN jobs j ON j.job_id = jc.job_id"
+    )
+    placeholders = ",".join("?" for _ in keys)
+    try:
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            f"{select_cols} WHERE jc.clip_key IN ({placeholders}) ORDER BY jc.updated_at DESC",
+            keys,
+        ).fetchall()
+        for row in rows:
+            _apply_row(row, str(row["clip_key"]))
+        # Only pay for the unfiltered scan when a rename actually left a record
+        # unresolved by the disk pass and exact-key match above.
+        unresolved = {
+            h: k for h, k in pending_hash_to_key.items() if k not in status_by_key
+        }
+        if unresolved:
+            for row in conn.execute(
+                f"{select_cols} ORDER BY jc.updated_at DESC"
+            ).fetchall():
+                raw_key = str(row["clip_key"])
+                if raw_key in key_set:
+                    continue
+                row_hash = clip_directory_hash(raw_key)
+                target_key = unresolved.get(row_hash) if row_hash else None
+                if target_key:
+                    _apply_row(row, target_key)
+    except Exception:
+        return status_by_key
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
     return status_by_key
 
 
@@ -13426,6 +13481,25 @@ class Handler(BaseHTTPRequestHandler):
         if path == "/api/timeline_versions":
             self._json(list_timelines_with_versions(self.state.project_root))
             return
+        if path == "/api/timeline_versions/diff":
+            timeline_name = (query.get("timeline_name") or [""])[0]
+            try:
+                from_version = int((query.get("from_version") or [""])[0])
+                to_version = int((query.get("to_version") or [""])[0])
+            except (ValueError, TypeError):
+                self._json({"success": False, "error": "from_version and to_version (ints) required"},
+                           HTTPStatus.BAD_REQUEST)
+                return
+            if not timeline_name:
+                self._json({"success": False, "error": "timeline_name required"}, HTTPStatus.BAD_REQUEST)
+                return
+            self._json({"success": True, **_timeline_versioning.diff_versions(
+                project_root=self.state.project_root,
+                timeline_name=timeline_name,
+                from_version=from_version,
+                to_version=to_version,
+            )})
+            return
         if path.startswith("/api/timeline_versions/"):
             timeline_name = unquote(path[len("/api/timeline_versions/"):])
             if not timeline_name:

package/src/batch_cli.py

@@ -318,6 +318,65 @@ def _cmd_cancel(args: argparse.Namespace) -> int:
     return EXIT_OK if payload.get("success") else EXIT_FATAL
 
 
+def _run_spec_action(action: str, params: Dict[str, Any]):
+    """Connect to Resolve (auto-launch) and run a project_manager spec action.
+
+    Imported lazily so the analysis commands stay free of the MCP/Resolve import.
+    """
+    from src.server import get_resolve, _spec_action  # lazy: pulls mcp + resolve
+
+    r = get_resolve()
+    if r is None:
+        return None
+    return _spec_action(r, r.GetProjectManager(), action, params)
+
+
+def _emit_spec_result(result, *, json_mode: bool) -> int:
+    if result is None:
+        _emit("Could not connect to DaVinci Resolve.",
+              json_mode=json_mode,
+              payload={"success": False, "error": "not_connected"})
+        return EXIT_FATAL
+    if json_mode:
+        _emit("", json_mode=True, payload=result)
+    err = result.get("error")
+    if err:
+        _emit(f"Spec error: {err.get('message')}", json_mode=False)
+        return EXIT_FATAL
+    if "actions" in result:  # plan / diff
+        changed = result.get("change_count", 0)
+        _emit(f"Project   : {result.get('project')}", json_mode=False)
+        _emit(f"Changes   : {changed}", json_mode=False)
+        for a in result.get("actions", []):
+            if a.get("op") != "noop":
+                _emit(f"  [{a['op']:>6}] {a['target']}  {a.get('detail', '')}", json_mode=False)
+        return EXIT_OK
+    # apply
+    failures = result.get("failures") or []
+    _emit(f"Applied   : {result.get('applied_count', 0)}", json_mode=False)
+    if failures:
+        for f in failures:
+            _emit(f"  [failed] {f.get('target')}", json_mode=False)
+        return EXIT_PARTIAL
+    _emit("Done: spec applied", json_mode=False)
+    return EXIT_OK
+
+
+def _cmd_plan_spec(args: argparse.Namespace) -> int:
+    result = _run_spec_action("diff_to_spec", {"spec_path": args.spec})
+    return _emit_spec_result(result, json_mode=args.json)
+
+
+def _cmd_apply(args: argparse.Namespace) -> int:
+    result = _run_spec_action("apply_spec", {
+        "spec_path": args.spec,
+        "dry_run": args.dry_run,
+        "run_hooks": args.run_hooks,
+        "continue_on_error": args.continue_on_error,
+    })
+    return _emit_spec_result(result, json_mode=args.json)
+
+
 def _add_run_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("paths", nargs="+", help="Files or directories to analyze")
     parser.add_argument(
@@ -431,6 +490,26 @@ def _build_parser() -> argparse.ArgumentParser:
     p_cancel.add_argument("job_id")
     p_cancel.add_argument("--project-root", required=True)
 
+    p_plan_spec = sub.add_parser(
+        "plan-spec",
+        help="Preview drift between a declarative project spec and live Resolve",
+        parents=[common],
+    )
+    p_plan_spec.add_argument("spec", help="Path to project.dvr.yaml (or .json)")
+
+    p_apply = sub.add_parser(
+        "apply",
+        help="Reconcile the Resolve project toward a declarative spec (idempotent)",
+        parents=[common],
+    )
+    p_apply.add_argument("spec", help="Path to project.dvr.yaml (or .json)")
+    p_apply.add_argument("--dry-run", action="store_true",
+                         help="Compute the plan without mutating")
+    p_apply.add_argument("--run-hooks", action="store_true",
+                         help="Execute the spec's before/after shell hooks (opt-in)")
+    p_apply.add_argument("--continue-on-error", action="store_true",
+                         help="Accumulate failures instead of aborting on the first")
+
     return parser
 
 
@@ -441,6 +520,8 @@ _HANDLERS = {
     "list": _cmd_list,
     "resume": _cmd_resume,
     "cancel": _cmd_cancel,
+    "plan-spec": _cmd_plan_spec,
+    "apply": _cmd_apply,
 }
 
 

package/src/granular/common.py

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