davinci-resolve-mcp 2.97.3 → 2.97.5

package/CHANGELOG.md

@@ -2,6 +2,89 @@
 
 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.97.5
+
+**`npm ci` was failing outright, and nothing in the release path noticed.**
+No server behavior changed; this is packaging and release-process hardening.
+
+### Fixed
+
+- **`package-lock.json` was seven releases stale.** It still carried
+  `2.90.0`, and — the part that actually broke things — two
+  `optionalDependencies` added since then, `js-yaml` and `pg`, were never
+  locked. `npm ci` refuses to install at all when the lockfile and
+  `package.json` disagree, so every reproducible install path failed with
+  `EUSAGE — Missing: js-yaml@4.3.1 from lock file` (plus `pg` and its nine
+  transitive deps). CI, fresh contributor clones, and container builds all hit
+  it. `npm install` and `npm publish` resolve independently of the lockfile
+  and stayed green throughout, which is why it survived seven releases.
+  Regenerated with `npm install --package-lock-only`; `npm ci` now installs
+  175 packages clean.
+
+### Added
+
+- **`tests.test_import::test_package_lock_in_sync`** — asserts both version
+  fields in the lockfile match `package.json`, and that the root
+  `dependencies` / `devDependencies` / `optionalDependencies` blocks match
+  exactly. The second half is the one that matters: the version fields being
+  right is not evidence `npm ci` works, and dependency drift is what actually
+  breaks it. Verified to fail on each drift mode independently.
+
+### Changed
+
+- `docs/process/release-process.md` lists `package-lock.json` under "Files To
+  Update" with the regeneration command, and Required Validation now
+  regenerates the lockfile before `test_import` reads it. The lockfile was
+  never on the checklist, which is why the drift was never a step anyone
+  skipped — it was a step that did not exist.
+
+## What's New in v2.97.4
+
+**Drift is caught at the edit, not at publish time.** Tooling and docs only —
+no server behavior changed, and no Resolve live run was required or performed.
+
+### Added
+
+- **Two opt-in `PostToolUse` hooks** in `.claude/hooks/`. Like the two existing
+  `PreToolUse` guards, they ship as scripts and are **not** wired up by default;
+  opt in via your own gitignored `.claude/settings.local.json` (the block is in
+  [docs/README.md](docs/README.md)).
+  - `agent_rules_drift_check.py` runs `node scripts/agent-rules/generate.mjs
+    --check` after an edit to anything the generator actually reads
+    (`docs/SKILL.md`, `docs/kernels/README.md`, `resolve-advanced/README.md`,
+    and `generate.mjs` itself, which carries the DOMAINS manifest inline) or to
+    `AGENTS.md`, which it writes. It separates the generator's two exit-1
+    paths: real staleness always prints `N agent-rule file(s) are stale`, a
+    throw never does — and telling a session to regenerate when the generator
+    is the thing that crashed sends it in a circle. Watching outputs but not
+    inputs was the original bug: bumping the compound tool count in
+    `docs/SKILL.md` left five generated files stale and the hook said nothing.
+    **A new generator input has to be added to `SOURCE_PATHS` or the hook goes
+    silent on exactly the edit it exists for.**
+  - `run_matching_test.py` runs the matching `tests/test_<module>.py` after an
+    edit under `src/`, resolving the project venv (`venv/bin/python`) before
+    `python3` so `pytest` is importable rather than reporting a false failure.
+    A fast partial net, not coverage: 72 of the 126 modules under `src/` follow
+    the convention, densely in `src/utils/` and not at all for `src/server.py`,
+    `src/granular/common.py`, or `src/control_panel.py`. Silence means "no
+    matching test file", not "this edit is fine".
+- **`drift-guard-reviewer` subagent** (`.claude/agents/`) — runs the drift-guard
+  test family plus the adjacent checks `npm-publish.yml` runs before every
+  publish, on demand and in its own context. It reports what is stale and which
+  regeneration command fixes it; it does not fix anything.
+- **`release-check` skill** (`/release-check`) — a thin wrapper that reads and
+  follows [docs/process/release-process.md](docs/process/release-process.md)
+  from disk. It deliberately does not restate the checklist: a second copy can
+  drift from the original, which `CLAUDE.md` prohibits.
+
+### Changed
+
+- `docs/README.md` documents all four hooks, all three subagents, and the new
+  skill in place, including the opt-in JSON block.
+
+Contributed by [@Grimthereapper](https://github.com/Grimthereapper) in
+[#149](https://github.com/samuelgursky/davinci-resolve-mcp/pull/149).
+
 ## What's New in v2.97.3
 
 **`source_end` no longer has the start timecode baked into it.** Reported by

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.97.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.97.5-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-35%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.97.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.97.5-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-35%20(353%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)
 
-> 本翻译对应 v2.97.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.97.5 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/README.md

@@ -69,23 +69,29 @@ skill routes, these two walk a whole job:
 - `resolve-tighten-recording` (`.claude/skills/resolve-tighten-recording/SKILL.md`)
   — **subtractive**: remove dead air from one long single-take recording.
 
-Two more sit outside the domain routing:
+Three more sit outside the domain routing:
 
 - `house-style` (`.claude/skills/house-style/SKILL.md`) — accumulated editorial
   corrections, so the same note is not given twice. Claude-only; append to it
   when an editorial decision is corrected.
 - `resolve-session` (`.claude/skills/resolve-session/SKILL.md`) — `/resolve-session`
   connects, confirms edition and bridge, and reports project/timeline/pool state.
+- `release-check` (`.claude/skills/release-check/SKILL.md`) — `/release-check`
+  walks a version bump using [docs/process/release-process.md](process/release-process.md)
+  as the sole source; the skill wraps that doc, it does not duplicate it.
 
 The offline half of every one is the advanced server; see
 [Advanced Server](../resolve-advanced/README.md).
 
 ## Claude Code Hooks and Subagents
 
-Two `PreToolUse` guards enforce rules `AGENTS.md` states in prose. They ship as
-scripts but are **not** wired up by default — the repository does not enable
-hooks on your behalf. Opt in by adding the block below to your own
-`.claude/settings.local.json` (gitignored, so it stays yours):
+Four hooks live in `.claude/hooks/` — two `PreToolUse` guards enforcing rules
+`AGENTS.md` states in prose, and two `PostToolUse` checks that surface
+engineering drift right after the edit that caused it instead of at the next
+test run. All four ship as scripts but are **not** wired up by default — the
+repository does not enable hooks on your behalf. Opt in by adding the block
+below to your own `.claude/settings.local.json` (gitignored, so it stays
+yours):
 
 ```json
 {
@@ -111,13 +117,30 @@ hooks on your behalf. Opt in by adding the block below to your own
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/agent_rules_drift_check.py",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/run_matching_test.py",
+            "timeout": 90
+          }
+        ]
+      }
     ]
   }
 }
 ```
 
 Hooks are read at session start, so restart Claude Code after adding them. The
-two guards are:
+four are:
 
 - `.claude/hooks/frame_verification_guard.py` — denies grade-applying actions on
   `timeline_item_color` until the session has actually looked at a
@@ -127,15 +150,36 @@ two guards are:
 - `.claude/hooks/source_media_guard.py` — denies shell commands that write,
   move, or delete source media outside a scratch root. Reads (`ffprobe`, and
   `ffmpeg` writing into scratch) pass.
-
-Two review subagents in `.claude/agents/` run in their own context so frame
-images stay out of the main session:
+- `.claude/hooks/agent_rules_drift_check.py` — after an edit to anything
+  `generate.mjs` reads (`docs/SKILL.md`, `docs/kernels/README.md`,
+  `resolve-advanced/README.md`, and `generate.mjs` itself, which carries the
+  DOMAINS manifest inline) or to `AGENTS.md`, which it writes, runs
+  `node scripts/agent-rules/generate.mjs --check` and surfaces the result. It
+  distinguishes real drift from a generator that threw before it could look —
+  regenerating fixes the first and not the second. Informational only; never
+  blocks. Skips quietly if `node` isn't on `PATH`. **If `generate.mjs` grows a
+  new input, add it to `SOURCE_PATHS` in the hook** — an unwatched input is a
+  silent hook on exactly the edit it exists to catch.
+- `.claude/hooks/run_matching_test.py` — after an edit to `src/<module>.py`,
+  runs the matching `tests/test_<module>.py` if one exists, using the project
+  venv (`venv/bin/python`) so `pytest` is actually importable. Informational
+  only; skips quietly if there's no matching test file or no working `pytest`.
+  A fast partial net, not coverage: 72 of the 126 modules under `src/` have a
+  matching test under this convention, densely in `src/utils/` and not at all
+  for `src/server.py` or `src/granular/common.py`. Silence means "no matching
+  test file", not "this edit is fine".
+
+Three review subagents in `.claude/agents/` run in their own context so bulky
+output (frame images, full test transcripts) stays out of the main session:
 
 - `cut-reviewer` — screens an assembled timeline from its frames and reports on
   pacing, shot order, continuity, and coverage gaps.
 - `grade-match-verifier` — measures shot match numerically from rendered frames
   against the project's R−B tolerance, and reports mask pixel counts so an empty
   skin mask cannot pass as a match.
+- `drift-guard-reviewer` — runs the doc/generated-file drift-guard test family
+  (the same checks `npm-publish.yml` runs before every release) and reports
+  which files are stale relative to their source, without fixing them.
 
 ## Authoring References
 

package/docs/process/release-process.md

@@ -26,6 +26,14 @@ Every release bump must update all version surfaces:
 - `src/granular/common.py`
 - `install.py`
 - `package.json`
+- `package-lock.json` — regenerate with `npm install --package-lock-only`, do
+  not hand-edit the version. It carries the version in two places and, more
+  importantly, the resolved dependency tree. When it disagrees with
+  `package.json`, **`npm ci` refuses to install at all** (`EUSAGE — Missing: X
+  from lock file`), which breaks CI, fresh clones, and container builds while
+  `npm install` and `npm publish` stay green and hide it. The
+  `tests.test_import` guard `test_package_lock_in_sync` fails the suite on
+  either drift.
 - README version badge
 - README current stats or latest-release summary when they changed
 - `README.zh-CN.md` — the Simplified Chinese translation. Update its version
@@ -62,6 +70,7 @@ Always run static checks before release:
 
 ```bash
 venv/bin/python tests/test_import.py
+npm install --package-lock-only --no-audit --no-fund   # re-stage package-lock.json if it moved
 venv/bin/python scripts/audit_api_parity.py
 venv/bin/python scripts/gen_api_limitations.py --check
 node scripts/agent-rules/generate.mjs --check
@@ -72,6 +81,13 @@ npm pack --dry-run
 git diff --check
 ```
 
+`test_import` carries `test_package_lock_in_sync`, which is the actual gate on the
+lockfile: it asserts both version fields and the root dependency blocks match
+`package.json`. Run the `npm install --package-lock-only` line above first so the
+regeneration is in the working tree when the test reads it — that ordering is why
+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_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 = "2.97.3"
+VERSION = "2.97.5"
 # 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.97.3",
+  "version": "2.97.5",
   "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 = "2.97.3"
+VERSION = "2.97.5"
 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 353-tool granular server instead
 """
 
-VERSION = "2.97.3"
+VERSION = "2.97.5"
 
 import base64
 import os