@hybridlabor-api/aos 4.4.1 → 4.4.2-beta.1

package/mcps/davinci-resolve-mcp/scripts/doctor.py

@@ -1,227 +0,0 @@
-#!/usr/bin/env python3
-"""Read-only diagnostics for a local DaVinci Resolve MCP setup.
-
-Checks the checkout, Python interpreter, Resolve app and scripting-API paths,
-MCP client configs, and probes the DaVinciResolveScript bridge without
-mutating anything. Prints OK/WARN/FAIL lines (or JSON with --json) and exits
-nonzero only when a FAIL is present.
-
-Run: `python3 scripts/doctor.py`
-
-Overridable via environment: DAVINCI_MCP_REPO, DAVINCI_MCP_PYTHON,
-CODEX_HOME, CLAUDE_DESKTOP_CONFIG, RESOLVE_APP, RESOLVE_SCRIPT_API,
-RESOLVE_SCRIPT_MODULES, RESOLVE_SCRIPT_LIB.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-from pathlib import Path
-from typing import Any
-
-
-def find_repo_root() -> Path:
-    env_repo = os.environ.get("DAVINCI_MCP_REPO")
-    if env_repo:
-        return Path(env_repo).expanduser().resolve()
-    current = Path(__file__).resolve()
-    for candidate in [current, *current.parents]:
-        if (candidate / "src" / "server.py").exists():
-            return candidate
-    return current.parents[1]
-
-
-REPO = find_repo_root()
-PYTHON = Path(os.environ.get("DAVINCI_MCP_PYTHON", REPO / "venv" / "bin" / "python")).expanduser()
-if not PYTHON.exists():
-    PYTHON = REPO / ".venv" / "bin" / "python"
-if not PYTHON.exists():
-    PYTHON = Path(sys.executable)
-SERVER = REPO / "src" / "server.py"
-CODEX_HOME = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
-CODEX_CONFIG = CODEX_HOME / "config.toml"
-CLAUDE_CONFIG = Path(
-    os.environ.get(
-        "CLAUDE_DESKTOP_CONFIG",
-        "~/Library/Application Support/Claude/claude_desktop_config.json",
-    )
-).expanduser()
-RESOLVE_APP = Path(os.environ.get("RESOLVE_APP", "/Applications/DaVinci Resolve/DaVinci Resolve.app"))
-RESOLVE_API = Path(
-    os.environ.get(
-        "RESOLVE_SCRIPT_API",
-        "/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting",
-    )
-)
-RESOLVE_MODULES = Path(os.environ.get("RESOLVE_SCRIPT_MODULES", RESOLVE_API / "Modules"))
-RESOLVE_LIB = Path(
-    os.environ.get(
-        "RESOLVE_SCRIPT_LIB",
-        "/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so",
-    )
-)
-
-
-def run(cmd: list[str], timeout: int = 12) -> dict[str, Any]:
-    try:
-        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
-        return {
-            "ok": proc.returncode == 0,
-            "returncode": proc.returncode,
-            "stdout": proc.stdout.strip(),
-            "stderr": proc.stderr.strip(),
-        }
-    except Exception as exc:
-        return {"ok": False, "returncode": None, "stdout": "", "stderr": str(exc)}
-
-
-def run_in_repo(cmd: list[str], timeout: int = 12) -> dict[str, Any]:
-    try:
-        proc = subprocess.run(cmd, cwd=REPO, capture_output=True, text=True, timeout=timeout)
-        return {
-            "ok": proc.returncode == 0,
-            "returncode": proc.returncode,
-            "stdout": proc.stdout.strip(),
-            "stderr": proc.stderr.strip(),
-        }
-    except Exception as exc:
-        return {"ok": False, "returncode": None, "stdout": "", "stderr": str(exc)}
-
-
-def check(results: list[dict[str, str]], status: str, name: str, detail: str) -> None:
-    results.append({"status": status, "name": name, "detail": detail})
-
-
-def file_contains(path: Path, needles: list[str]) -> tuple[bool, str]:
-    if not path.exists():
-        return False, "missing"
-    text = path.read_text(errors="replace")
-    missing = [needle for needle in needles if needle not in text]
-    if missing:
-        return False, "missing: " + ", ".join(missing)
-    return True, "contains davinci-resolve MCP entry"
-
-
-def version_from_server() -> str:
-    if not SERVER.exists():
-        return "unknown"
-    match = re.search(r'^VERSION\s*=\s*"([^"]+)"', SERVER.read_text(errors="replace"), re.M)
-    return match.group(1) if match else "unknown"
-
-
-def git_summary() -> str:
-    if not (REPO / ".git").exists():
-        return "not a git checkout"
-    status = run_in_repo(["git", "status", "--short", "--branch"], timeout=8)
-    return status["stdout"] or status["stderr"] or "git status produced no output"
-
-
-def git_head() -> str:
-    if not (REPO / ".git").exists():
-        return "not a git checkout"
-    head = run_in_repo(["git", "describe", "--tags", "--always", "--dirty"], timeout=8)
-    return head["stdout"] or head["stderr"] or "git describe produced no output"
-
-
-def resolve_probe() -> dict[str, Any]:
-    if not PYTHON.exists():
-        return {"import_ok": False, "error": f"{PYTHON} is missing"}
-
-    code = f"""
-import json
-import sys
-sys.path.insert(0, {str(RESOLVE_MODULES)!r})
-try:
-    import DaVinciResolveScript as dvr
-    resolve = dvr.scriptapp("Resolve")
-    payload = {{
-        "import_ok": True,
-        "module": getattr(dvr, "__file__", None),
-        "resolve_connected": bool(resolve),
-        "product": resolve.GetProductName() if resolve else None,
-        "version": resolve.GetVersionString() if resolve else None,
-    }}
-except Exception as exc:
-    payload = {{"import_ok": False, "error": repr(exc)}}
-print(json.dumps(payload))
-"""
-    env = {
-        **os.environ,
-        "RESOLVE_SCRIPT_API": str(RESOLVE_API),
-        "RESOLVE_SCRIPT_LIB": str(RESOLVE_LIB),
-        "PYTHONPATH": str(RESOLVE_MODULES),
-    }
-    proc = subprocess.run([str(PYTHON), "-c", code], capture_output=True, text=True, timeout=12, env=env)
-    output = (proc.stdout or proc.stderr).strip()
-    try:
-        payload = json.loads(output)
-    except json.JSONDecodeError:
-        payload = {"import_ok": False, "error": output or f"probe exited {proc.returncode}"}
-    payload["returncode"] = proc.returncode
-    return payload
-
-
-def collect() -> list[dict[str, str]]:
-    results: list[dict[str, str]] = []
-
-    check(results, "OK" if REPO.exists() else "FAIL", "MCP checkout", str(REPO))
-    check(results, "OK" if SERVER.exists() else "FAIL", "Server entrypoint", str(SERVER))
-    check(results, "OK" if PYTHON.exists() else "FAIL", "Python", str(PYTHON))
-    check(results, "OK" if RESOLVE_APP.exists() else "FAIL", "Resolve app", str(RESOLVE_APP))
-    check(results, "OK" if RESOLVE_API.exists() else "FAIL", "Resolve scripting API", str(RESOLVE_API))
-    check(results, "OK" if RESOLVE_MODULES.exists() else "FAIL", "Resolve scripting modules", str(RESOLVE_MODULES))
-    check(results, "OK" if RESOLVE_LIB.exists() else "FAIL", "Resolve scripting library", str(RESOLVE_LIB))
-
-    needles = [str(SERVER)]
-    ok, detail = file_contains(CODEX_CONFIG, needles)
-    check(results, "OK" if ok else "WARN", "Codex MCP config", f"{CODEX_CONFIG}: {detail}")
-    ok, detail = file_contains(CLAUDE_CONFIG, needles)
-    check(results, "OK" if ok else "WARN", "Claude Desktop MCP config", f"{CLAUDE_CONFIG}: {detail}")
-
-    pyver = run([str(PYTHON), "--version"]) if PYTHON.exists() else {"ok": False, "stdout": "", "stderr": "missing"}
-    check(results, "OK" if pyver["ok"] else "FAIL", "Python version", pyver["stdout"] or pyver["stderr"])
-
-    probe = resolve_probe()
-    if probe.get("import_ok"):
-        check(results, "OK", "DaVinciResolveScript import", str(probe.get("module")))
-        if probe.get("resolve_connected"):
-            detail = f"{probe.get('product')} {probe.get('version')}"
-            check(results, "OK", "Resolve scripting connection", detail)
-        else:
-            check(
-                results,
-                "WARN",
-                "Resolve scripting connection",
-                'Module import worked, but scriptapp("Resolve") returned no object. Open DaVinci Resolve Studio, set Preferences > General > External scripting using = Local, and restart Resolve.',
-            )
-    else:
-        check(results, "FAIL", "DaVinciResolveScript import", str(probe.get("error")))
-
-    check(results, "OK", "MCP server version", version_from_server())
-    check(results, "OK", "MCP git head", git_head())
-    check(results, "OK", "Git status", git_summary())
-    return results
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--json", action="store_true", help="Print machine-readable JSON")
-    args = parser.parse_args()
-
-    results = collect()
-    if args.json:
-        print(json.dumps({"checks": results}, indent=2))
-    else:
-        for item in results:
-            print(f"[{item['status']}] {item['name']}: {item['detail']}")
-
-    return 1 if any(item["status"] == "FAIL" for item in results) else 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/mcps/davinci-resolve-mcp/scripts/gen_api_limitations.py

@@ -1,144 +0,0 @@
-#!/usr/bin/env python3
-"""Generate the Blackmagic-facing DaVinci Resolve API limitations report.
-
-The single source of truth is the ``submit``-tagged entries in
-``src/utils/api_truth.py`` (see ``submittable_limitations``). This script renders
-them into ``docs/reference/api-limitations.md`` — a curated, behaviorally-verified
-list that can be submitted to Blackmagic Design's developer feedback, split into
-capabilities they should *add* and behaviors they should *fix*.
-
-The output is deterministic (no timestamps) so ``tests.test_api_limitations_doc``
-can assert the committed file matches. Regenerate after editing any ``submit``
-entry:
-
-    venv/bin/python scripts/gen_api_limitations.py
-
-Run with ``--check`` to fail (exit 1) when the committed doc is stale.
-"""
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-if str(REPO_ROOT) not in sys.path:
-    sys.path.insert(0, str(REPO_ROOT))
-
-from src.utils.api_truth import (  # noqa: E402
-    VERIFIED_ON,
-    submittable_limitations,
-)
-
-DOC_PATH = REPO_ROOT / "docs" / "reference" / "api-limitations.md"
-ISSUE_URL = "https://github.com/samuelgursky/davinci-resolve-mcp/issues"
-
-
-def _render_entry(entry: dict) -> str:
-    lines = [f"### {entry['symbol']}", ""]
-    obj = entry.get("object")
-    if obj:
-        lines.append(f"- **Object:** `{obj}`")
-    sig = entry.get("signature")
-    if sig:
-        lines.append(f"- **Signature:** `{sig}`")
-    lines.append(f"- **Behavior:** {entry['reality']}")
-    rec = entry.get("recommended")
-    if rec:
-        lines.append(f"- **Workaround / current handling:** {rec}")
-    issue = entry.get("issue")
-    if issue is not None:
-        lines.append(f"- **Reference:** [issue #{issue}]({ISSUE_URL}/{issue})")
-    tags = entry.get("tags")
-    if tags:
-        lines.append(f"- **Tags:** {', '.join(tags)}")
-    lines.append("")
-    return "\n".join(lines)
-
-
-def render() -> str:
-    groups = submittable_limitations()
-    missing = groups["missing"]
-    bugs = groups["bug"]
-
-    out = [
-        "# DaVinci Resolve Scripting API — Limitations & Feedback",
-        "",
-        "<!-- GENERATED FILE — do not edit by hand.",
-        "     Source: src/utils/api_truth.py (entries tagged `submit`).",
-        "     Regenerate: venv/bin/python scripts/gen_api_limitations.py -->",
-        "",
-        "This is a curated, behaviorally-verified list of DaVinci Resolve scripting",
-        "API gaps and bugs encountered while building this MCP server, intended for",
-        "submission to Blackmagic Design's developer feedback. Every item was",
-        "observed against live Resolve; each entry notes the current workaround (or",
-        "that none exists).",
-        "",
-        f"**Verified on:** {VERIFIED_ON}",
-        "",
-        f"**Totals:** {len(missing)} missing capabilities, {len(bugs)} bugs / "
-        "unreliable behaviors.",
-        "",
-        "The authoritative source is the runtime-queryable `api_truth` ledger",
-        "(`resolve_control api_truth \"<query>\"`); this document is generated from",
-        "it and stays in sync via a drift guard.",
-        "",
-        "### Scope & completeness",
-        "",
-        "This list is **not guaranteed exhaustive.** It combines (a) issues hit",
-        "while building this MCP server, (b) a `dir()` surface audit of the live",
-        "Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,",
-        "Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set,",
-        "and (c) a live mutating harness (`tests/live_api_gap_verification.py`)",
-        "that attempts each operation against a disposable project built from",
-        "synthetic media and confirms it fails while a related control succeeds.",
-        "That catches absent methods and documented constraints, but not subtler",
-        "issues: parameters that exist yet misbehave, version-specific regressions,",
-        "or capabilities we simply never exercised. New findings are added as",
-        "`submit`-tagged `api_truth` entries and this document is regenerated.",
-        "",
-        "Note: `hasattr()`/`getattr()` cannot be used to probe this API — the",
-        "Python bridge fabricates a callable for any attribute name (see the",
-        "`hasattr` bug below). Method existence here was checked with `dir()`.",
-        "",
-        "## Missing Capabilities (please add)",
-        "",
-        "Functionality that exists in the Resolve UI but has no scripting API",
-        "equivalent, blocking full automation.",
-        "",
-    ]
-    for entry in missing:
-        out.append(_render_entry(entry))
-
-    out += [
-        "## Bugs / Unreliable Behavior (please fix)",
-        "",
-        "Methods that exist but misbehave — silent failures, unreliable return",
-        "values, or automation-hostile modal prompts.",
-        "",
-    ]
-    for entry in bugs:
-        out.append(_render_entry(entry))
-
-    return "\n".join(out).rstrip() + "\n"
-
-
-def main(argv: list[str]) -> int:
-    content = render()
-    if "--check" in argv:
-        current = DOC_PATH.read_text() if DOC_PATH.exists() else ""
-        if current != content:
-            print(
-                f"STALE: {DOC_PATH.relative_to(REPO_ROOT)} is out of date.\n"
-                "Run: venv/bin/python scripts/gen_api_limitations.py",
-                file=sys.stderr,
-            )
-            return 1
-        print(f"OK: {DOC_PATH.relative_to(REPO_ROOT)} is up to date.")
-        return 0
-    DOC_PATH.write_text(content)
-    print(f"Wrote {DOC_PATH.relative_to(REPO_ROOT)}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main(sys.argv[1:]))

package/mcps/davinci-resolve-mcp/scripts/live_media_analysis_polish_probe.py

@@ -1,65 +0,0 @@
-#!/usr/bin/env python3
-"""Opt-in live probe for media-analysis polish.
-
-This script connects to the currently open Resolve project and exercises only
-source-safe planning/review surfaces. It may write analysis artifacts under the
-project analysis root, but it does not import, transcode, proxy, move, rename,
-or write beside source media.
-"""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import json
-import os
-import sys
-from pathlib import Path
-
-
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-if str(PROJECT_ROOT) not in sys.path:
-    sys.path.insert(0, str(PROJECT_ROOT))
-
-from src.server import media_analysis  # noqa: E402
-
-
-async def main() -> int:
-    parser = argparse.ArgumentParser(description="Run a source-safe live media-analysis polish probe.")
-    parser.add_argument("--target", default="project", help="project, selected, bin:<path>, or absolute file path")
-    parser.add_argument("--depth", default="standard", choices=["quick", "standard", "deep", "custom"])
-    parser.add_argument("--analysis-root", default=None, help="Optional base analysis root; project subdir is still added")
-    parser.add_argument("--max-samples", type=int, default=8, help="Marker thumbnail samples for review")
-    parser.add_argument("--execute", action="store_true", help="Execute analysis instead of dry-run planning")
-    parser.add_argument("--persist", action="store_true", help="Keep executed analysis artifacts under the project root")
-    args = parser.parse_args()
-
-    common = {
-        "target": args.target,
-        "depth": args.depth,
-        "analysis_root": args.analysis_root,
-        "dry_run": not args.execute,
-        "persist": args.persist,
-        "session_only": bool(args.execute and not args.persist),
-        "reuse_existing": True,
-        "max_analysis_frames": 8,
-        "vision": {"enabled": False},
-        "transcription": {"enabled": False},
-    }
-    plan = await media_analysis("plan", common)
-    review = await media_analysis("review_timeline_markers", {
-        "analysis_root": args.analysis_root,
-        "max_samples": args.max_samples,
-        "vision": {"enabled": False},
-    })
-    print(json.dumps({
-        "success": bool(plan.get("success")),
-        "cwd": os.getcwd(),
-        "plan": plan,
-        "marker_review": review,
-    }, indent=2, ensure_ascii=False))
-    return 0 if plan.get("success") else 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(asyncio.run(main()))

package/mcps/davinci-resolve-mcp/scripts/measure_bridge_cost.py

@@ -1,65 +0,0 @@
-#!/usr/bin/env python3
-"""Measure DaVinci Resolve bridge round-trips for representative operations.
-
-Wraps the live project in a counting proxy and runs a few common traversals,
-reporting how many attribute accesses + method calls (each a bridge round-trip)
-they cost. This is the measurement that gates whether a property cache is worth
-building. Run against an OPEN project; it only reads.
-
-    PYTHONPATH=. venv/bin/python scripts/measure_bridge_cost.py
-"""
-import sys
-
-import src.server as s
-from src.utils.bridge_metrics import measure
-
-
-def _walk_media_pool(project_proxy):
-    """A typical media-pool traversal: every folder, every clip, name + a property."""
-    mp = project_proxy.GetMediaPool()
-    root = mp.GetRootFolder()
-    clips_seen = 0
-
-    def walk(folder):
-        nonlocal clips_seen
-        for clip in (folder.GetClipList() or []):
-            clip.GetName()
-            clip.GetClipProperty("Type")
-            clips_seen += 1
-        for sub in (folder.GetSubFolderList() or []):
-            walk(sub)
-
-    walk(root)
-    return clips_seen
-
-
-def main():
-    r = s.get_resolve()
-    if not r:
-        print("Not connected to Resolve.")
-        return 1
-    proj = r.GetProjectManager().GetCurrentProject()
-    if not proj:
-        print("No project open.")
-        return 1
-
-    clips_holder = {}
-
-    def op(proj_proxy):
-        clips_holder["n"] = _walk_media_pool(proj_proxy)
-
-    counts = measure(op, proj)
-    n = clips_holder.get("n", 0)
-    total = counts["attr_access"] + counts["calls"]
-    print(f"project: {proj.GetName()!r}")
-    print(f"clips walked: {n}")
-    print(f"bridge attr-accesses: {counts['attr_access']}")
-    print(f"bridge method-calls:  {counts['calls']}")
-    print(f"total round-trips:    {total}")
-    if n:
-        print(f"round-trips per clip: {total / n:.1f}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/mcps/davinci-resolve-mcp/scripts/regen_panel_screenshots.py

@@ -1,76 +0,0 @@
-#!/usr/bin/env python3
-"""Regenerate the control-panel doc screenshots from a live panel.
-
-Drives the panel's hash deep links headlessly and writes 1280x800 captures
-into docs/images/control-panel/. Run whenever the panel UI changes visibly.
-
-Setup:
-  1. venv/bin/pip install playwright  (chromium is fetched on first run if absent)
-  2. Start the panel bound to a project that HAS an analyzed clip, e.g.:
-       venv/bin/python -m src.control_panel --no-open
-     (Bind to a rich analysis context if the live Resolve project is empty.)
-  3. venv/bin/python scripts/regen_panel_screenshots.py [--clip-id <id>] [--port 8765]
-
-The clip id defaults to the first analyzed clip reported by /api/clips.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import pathlib
-import sys
-import urllib.request
-
-OUT_DIR = pathlib.Path(__file__).resolve().parent.parent / "docs" / "images" / "control-panel"
-
-
-def first_clip_id(base: str) -> str:
-    with urllib.request.urlopen(f"{base}/api/clips", timeout=10) as resp:
-        payload = json.load(resp)
-    clips = payload.get("clips") or []
-    if not clips:
-        sys.exit("No analyzed clips in the panel's project — bind the panel to a project with analysis data first.")
-    return clips[0]["clip_id"]
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--port", type=int, default=8765)
-    parser.add_argument("--clip-id", default=None)
-    args = parser.parse_args()
-    base = f"http://127.0.0.1:{args.port}"
-
-    try:
-        from playwright.sync_api import sync_playwright
-    except ImportError:
-        sys.exit("playwright not installed: venv/bin/pip install playwright")
-
-    clip = args.clip_id or first_clip_id(base)
-    shots = [
-        ("#overview", "01-overview.png", 3000),
-        ("#analysis/review", "02-review-bin-grid.png", 3500),
-        (f"#analysis/review/clip/{clip}", "03-clip-detail.png", 4000),
-        (f"#analysis/review/clip/{clip}/transcript", "04-transcript.png", 4000),
-        (f"#analysis/review/clip/{clip}/shot/3", "05-shot-detail.png", 4500),
-        ("#analysis/media", "06-inventory.png", 3500),
-        ("#diagnostics/resolve", "07-diagnostics-resolve.png", 3000),
-        ("#preferences/analysis", "08-preferences-analysis.png", 3000),
-        ("#aiconsole", "09-ai-console.png", 3000),
-        ("#analysis/review/history", "10-history.png", 3500),
-        ("#analysis/review/plans", "11-edit-plans.png", 3500),
-    ]
-    with sync_playwright() as pw:
-        browser = pw.chromium.launch()
-        page = browser.new_page(viewport={"width": 1280, "height": 800})
-        for hash_, name, wait in shots:
-            page.goto(f"{base}/{hash_}")
-            page.wait_for_timeout(wait)
-            page.screenshot(path=str(OUT_DIR / name))
-            print("shot:", name)
-        browser.close()
-    print(f"done — {len(shots)} screenshots in {OUT_DIR}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/mcps/davinci-resolve-mcp/src/__init__.py

@@ -1,3 +0,0 @@
-"""
-DaVinci Resolve MCP Server Package
-"""