davinci-resolve-mcp 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 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.1.0 — "send this as a bug": issues drafted from chat
+
+A new `resolve_control` action, `report_issue`. While working in any MCP client,
+say "send this as a bug" or "send this as a feature request" and the assistant
+drafts the GitHub issue for you.
+
+### Added
+
+- **`resolve_control(action="report_issue")`** drafts a bug report
+  (`kind="bug"`) or feature request (`kind="feature"`) from the conversation:
+  what happened, steps to reproduce, expected vs actual, and the failing
+  tool/action with its error. It attaches what a maintainer would otherwise
+  have to ask for in the thread: server version, Resolve build and edition,
+  connection mode (local scripting, network scripting or in-app bridge),
+  whether Resolve is running with a UI or headless, OS, and Python.
+- **It files nothing.** It returns the draft plus a prefilled GitHub
+  `issues/new` link. You review the draft and submit it under your own
+  account, so no GitHub credential lives in the server and nothing is
+  published that you have not seen.
+- **It never connects to or launches Resolve.** A report about a connection
+  that will not come up must not start one, so the environment is read only
+  from a handle the server already holds.
+- **Every field is redacted before it reaches the draft:** absolute paths
+  (POSIX, Windows and UNC, including paths with spaces; the file extension is
+  kept, and the Blackmagic install locations and `~/.davinci-resolve-mcp` are
+  kept because they identify nothing), the local username, full name and
+  hostname, e-mail addresses, the control panel's `#token=` fragment, and
+  key-shaped secrets. Client or project names written as ordinary prose
+  cannot be recognised, so the result tells the assistant to have you check
+  the draft before submitting.
+- Links over 8,000 characters shorten only the narrative. The environment
+  table always survives, and the full body is still returned to the chat.
+- `bug_report` and `feature_request` issue templates, carrying the `bug` and
+  `enhancement` labels.
+
+### Documentation
+
+- README: new *Reporting Bugs and Requesting Features* section (with the
+  matching section in `README.zh-CN.md`); `docs/SKILL.md` documents when to
+  call the action and that the user submits; the server instructions now
+  mention it, so any MCP client can find it.
+
+### Validation
+
+- 27 new unit tests (`tests/test_issue_report.py`) cover redaction, layout,
+  link round-trip and truncation, the no-connect guarantee, and the
+  templates. The full suite passes: 3509 passed, 0 failed.
+- Smoke-tested through the real MCP stdio protocol against `src/server.py`.
+- No Resolve behaviour changed, so no live Resolve run was needed.
+
 ## What's New in v3.0.1 — project deletion is gated, and the open project is refused by default
 
 A security fix, published as [GHSA-gmp7-qjp9-m7gm](https://github.com/samuelgursky/davinci-resolve-mcp/security/advisories/GHSA-gmp7-qjp9-m7gm).

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.0.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.1.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-36%20(377%20full)-blue.svg)](#server-modes)
@@ -410,6 +410,17 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
 
 Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+. They are live-tested on Studio 21.0.2.4 — see the [Resolve 21 delta](docs/reference/api-coverage.md#resolve-21-delta-detail). Note that `AnalyzeForIntellisearch`, `AnalyzeForSlate` and `GenerateSpeech` each require a separately-downloaded AI Extras pack, and Resolve reports a missing pack inconsistently (some return `False`, others an error string), so these actions report `success: false` with the Resolve-supplied reason rather than guessing.
 
+## Reporting Bugs and Requesting Features
+
+Tell your assistant "send this as a bug" or "send this as a feature request". It
+drafts a GitHub issue from the conversation, including the failing call and
+its error, and attaches the server version, Resolve build, connection mode and
+OS. Local paths, your username and anything that looks like a secret are
+redacted. Nothing is filed for you: you get a prefilled link, review the
+draft, and submit it on GitHub yourself. You can also
+[open an issue](https://github.com/samuelgursky/davinci-resolve-mcp/issues/new/choose)
+directly.
+
 ## Development
 
 ```bash

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-3.0.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.1.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-36%20(377%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.0.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v3.1.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -269,6 +269,10 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 Resolve 19.1.3 仍是兼容性基线。Resolve 20.x 的脚本调用是增量式的、带版本护栏的，并已在 20.3.2 上实机测试。Resolve 21.0 新增的脚本能力（音频分类、说话人检测转写、IntelliSearch、场记板分析、运动去模糊、语音生成、会话后台任务控制）通过运行时能力检测暴露，在旧构建上保持沉默，在 Resolve 21+ 上自动激活。它们已在 Studio 21.0.2.4 上实机测试——见 [Resolve 21 增量明细](docs/reference/api-coverage.md#resolve-21-delta-detail)。注意 `AnalyzeForIntellisearch`、`AnalyzeForSlate` 和 `GenerateSpeech` 各自需要单独下载的 AI Extras 包，而 Resolve 报告缺包的方式不一致（有的返回 `False`，有的返回错误字符串），所以这些 action 会带着 Resolve 给出的原因报告 `success: false`，而不是瞎猜。
 
+## 报告 Bug 与提出功能需求
+
+对你的助手说"把这个作为 bug 发送"或"把这个作为功能需求发送"。它会根据对话起草一个 GitHub issue，包含失败的调用及其错误，并附上服务器版本、Resolve 构建、连接方式和操作系统。本地路径、你的用户名以及任何看起来像密钥的内容都会被脱敏。不会替你直接提交：你会拿到一个预填好的链接，检查草稿后在 GitHub 上自己提交。你也可以直接[新建 issue](https://github.com/samuelgursky/davinci-resolve-mcp/issues/new/choose)。
+
 ## 开发
 
 ```bash

package/docs/SKILL.md

@@ -735,6 +735,16 @@ Key actions:
   Resolve API behavior (no connection needed); filter by substring
 - `verification_stats` — readback-verification tally (verified/contradicted/
   unverified) since server start (no connection needed)
+- `report_issue(kind, title, summary, …)` — when the user says "send this as a
+  bug" or "…as a feature request", draft a GitHub issue for this server. Fill
+  it from the conversation (the failing tool/action and its error verbatim,
+  expected vs actual, steps). Server version, Resolve build, connection mode
+  and OS are attached; paths, usernames, e-mails and secrets are redacted. It
+  **files nothing**: show the user the draft, then hand them the returned
+  `url` to review and submit on GitHub. Redaction cannot catch client or
+  project names written as prose, so ask the user to check. Never call it
+  unprompted; offering once after a failure that looks like a server defect
+  is fine. No connection needed, and it never launches Resolve
 - `get_page` / `open_page(page)` — read or switch the active page
 - `get_keyframe_mode` / `set_keyframe_mode(mode)`
 - `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.0.1"
+VERSION = "3.1.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": "3.0.1",
+  "version": "3.1.0",
   "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.0.1"
+VERSION = "3.1.0"
 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.0.1"
+VERSION = "3.1.0"
 
 import base64
 import os
@@ -147,6 +147,7 @@ from src.utils.media_analysis_jobs import (
 from src.utils.platform import get_resolve_paths, get_resolve_plugin_paths
 from src.utils.resolve_connection import connect_resolve
 from src.utils import resolve_runtime as _resolve_runtime
+from src.utils import issue_report as _issue_report
 from src.utils.lut_paths import master_lut_dir, ensure_lut_in_master
 from src.utils import fuse_templates, dctl_templates, script_templates
 from src.utils.timeline_title_text import (
@@ -248,7 +249,10 @@ mcp = FastMCP(
         "DAVINCI_RESOLVE_BRIDGE=1 only forces it), so a connection error does NOT mean "
         "the free edition is unsupported — on Resolve 21.0.x. Resolve 21.1 moved Python "
         "scripting to Studio and free 21.1 no longer lists Python scripts in that menu "
-        "(issue #203), so on 21.1+ a free-edition connection error may be final."
+        "(issue #203), so on 21.1+ a free-edition connection error may be final. "
+        "When the user asks to send something as a bug or feature request, draft it "
+        "with resolve_control(action='report_issue') — it returns a prefilled GitHub "
+        "issue link for the user to review and submit; nothing is filed for them."
     ),
 )
 
@@ -16619,6 +16623,23 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         Omit symbol for every recorded gate this build does not clear.
       verification_stats() -> {stats}  — readback-verification tally
         (verified/contradicted/unverified) since server start (no connection needed).
+      report_issue(kind, title, summary, steps?, expected?, actual?, error?, tool?,
+                   tool_action?, use_case?, proposal?, include_environment?)
+        -> {title, body, labels, url, url_truncated, redactions, submitted: false, next_step}
+        — Draft a GitHub bug report (kind="bug") or feature request (kind="feature")
+          for this MCP server. Call it when the user asks to send, report or file
+          something as a bug or feature request ("send this as a bug"). Do not call
+          it unprompted; you may OFFER once when a failure looks like a defect in
+          this server rather than in the user's request. Write the fields from the
+          conversation: the failing tool/action and its error verbatim, what the
+          user expected, and steps that reproduce it. Server version, Resolve
+          build, connection mode and OS are attached automatically
+          (include_environment=false to omit); nothing connects to or launches
+          Resolve. NOTHING IS FILED: show the user the title and body, then give
+          them the url — the issue is created only when they open it and press
+          Submit on GitHub. Paths, usernames, e-mails and secrets are redacted,
+          but client or project names in plain prose are not: ask the user to
+          check before submitting.
       job_status(job_id) -> {id, label, status, result?, error?, started_at, ended_at}
         — poll a background job started by a long op run with background=True
           (no connection needed). status is running, done, or error.
@@ -16751,6 +16772,48 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         stats = _verification_stats()
         return {"stats": stats, "note": "Counts since server start. A rising "
                 "'contradicted' count means the API reported success but a readback disagreed."}
+    if action == "report_issue":
+        # Drafts only — never files, never connects. See utils/issue_report.py.
+        kind = _issue_report.normalize_kind(p.get("kind") or p.get("type"))
+        if kind is None:
+            return _err(
+                "report_issue requires kind: 'bug' or 'feature'",
+                code="INVALID_KIND",
+                category="invalid_input",
+            )
+        title = str(p.get("title") or "").strip()
+        summary = str(p.get("summary") or p.get("description") or p.get("body") or "").strip()
+        if not title or not summary:
+            return _err(
+                "report_issue requires title and summary",
+                code="MISSING_FIELDS",
+                category="invalid_input",
+                remediation="Write both from the conversation: a one-line title and "
+                "a summary of what happened or what the user wants.",
+            )
+        environment = None
+        if _setup_bool(p.get("include_environment", p.get("includeEnvironment")), True):
+            environment = _issue_report.collect_environment(resolve, VERSION)
+        draft = _issue_report.build_issue(
+            kind,
+            title,
+            summary,
+            steps=p.get("steps"),
+            expected=p.get("expected"),
+            actual=p.get("actual"),
+            error=p.get("error"),
+            tool=p.get("tool"),
+            tool_action=p.get("tool_action") or p.get("failed_action"),
+            use_case=p.get("use_case"),
+            proposal=p.get("proposal"),
+            environment=environment,
+        )
+        return {
+            "success": True,
+            **draft,
+            "submitted": False,
+            "next_step": _issue_report.next_step_guidance(draft["url_truncated"]),
+        }
 
     # Background-job polling is a registry read — no Resolve connection needed.
     if action == "job_status":
@@ -17075,7 +17138,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["is_studio","get_keyboard_presets","get_current_keyboard_preset","launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["is_studio","get_keyboard_presets","get_current_keyboard_preset","launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","report_issue","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────

package/src/utils/issue_report.py

@@ -0,0 +1,456 @@
+"""Draft a GitHub issue from inside a chat — bug reports and feature requests.
+
+The user says "send this as a bug" (or "…as a feature request") and the agent
+calls `resolve_control(action="report_issue")`. The server never files
+anything. It writes the issue and returns a prefilled `issues/new` link; the
+user reads the draft, opens the link, and presses Submit on GitHub under their
+own account. That keeps three things true:
+
+  - no GitHub credential ever lives in the MCP server;
+  - nothing is published that the user has not seen;
+  - the report still carries the facts a maintainer would otherwise have to
+    ask for in the thread — server version, Resolve build and edition,
+    connection mode, OS — which is most of the value.
+
+Redaction runs over every field before it reaches the draft: absolute paths,
+the local username, full name and hostname, e-mail addresses, and anything
+shaped like a secret. It is best-effort by construction — it cannot recognise
+a client or project name typed as plain prose — so the result always tells
+the agent to show the draft to the user before handing over the link.
+
+Nothing here connects to Resolve. A report about a connection that will not
+come up must not launch Resolve or wait on one, so the environment is read
+from a handle the server already holds, or reported as "not connected".
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import platform
+import re
+import socket
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import quote, urlencode
+
+from .update_check import DEFAULT_REPO
+
+#: GitHub answers `414 URI Too Long` somewhere past 8 KB and does not document
+#: the exact limit. Stay under it; the full body is returned separately.
+MAX_URL_CHARS = 8000
+
+MAX_FIELD_CHARS = 4000
+
+KINDS: Dict[str, Dict[str, str]] = {
+    "bug": {"template": "bug_report.md", "label": "bug"},
+    "feature": {"template": "feature_request.md", "label": "enhancement"},
+}
+
+_KIND_ALIASES = {
+    "bug": "bug",
+    "bug_report": "bug",
+    "defect": "bug",
+    "issue": "bug",
+    "feature": "feature",
+    "feature_request": "feature",
+    "enhancement": "feature",
+    "request": "feature",
+    "idea": "feature",
+}
+
+#: Install and support locations that say which build is installed and where.
+#: They are the same on every machine, so keeping them costs no privacy and
+#: saves a round-trip on installer and connection bugs.
+_KEEP_PATH_PREFIXES = (
+    "/Library/Application Support/Blackmagic Design",
+    "/Applications/DaVinci Resolve",
+    "/opt/resolve",
+    "~/.davinci-resolve-mcp",
+    "c:\\program files\\blackmagic design",
+    "c:\\programdata\\blackmagic design",
+)
+
+#: Usernames that are also ordinary words. Redacting "user" or "editor" out of
+#: prose mangles the report and protects nobody.
+_COMMON_ACCOUNT_NAMES = {
+    "root", "user", "admin", "administrator", "guest", "test", "dev",
+    "editor", "video", "mac", "pc", "home", "owner", "localhost",
+}
+
+_TRUNCATION_NOTE = "\n\n_…truncated to fit the link — the full report is in the chat._"
+
+_FOOTER = (
+    "\n\n---\n"
+    "<sub>Drafted in chat with the davinci-resolve-mcp `report_issue` action. "
+    "Local paths, the username and anything secret-shaped were redacted "
+    "automatically.</sub>\n"
+    "<!-- filed-via: davinci-resolve-mcp report_issue -->"
+)
+
+# --------------------------------------------------------------------------
+# Redaction
+# --------------------------------------------------------------------------
+
+_SEGMENT = r"[^\s/\\\"'`<>|*?:]+"
+# A directory segment may contain spaces ("/Volumes/My Drive/") because it is
+# closed by the next slash. A final segment may only when it ends in a file
+# extension ("A001 take 2.mov"); otherwise it stops at the first space, so
+# "/tmp/a to /tmp/b" stays two paths. A space after a comma or before a `~`
+# ends the path too — "x.log, see ~/y" is prose between two paths, not one.
+_SPACED = r"(?<![,;]) (?!~)"
+_DIR_SEGMENT = rf"{_SEGMENT}(?:{_SPACED}{_SEGMENT})*"
+_LAST_SEGMENT = (
+    rf"(?:{_SEGMENT}(?:{_SPACED}{_SEGMENT})*\.[A-Za-z0-9]{{1,5}}(?![\w.])|{_SEGMENT})"
+)
+
+_POSIX_PATH = re.compile(rf"(?<![\w:/.~\\-])(?:~/|/)(?:{_DIR_SEGMENT}/)+{_LAST_SEGMENT}")
+_WINDOWS_PATH = re.compile(
+    rf"(?<![\w])(?:[A-Za-z]:[\\/]|\\\\{_SEGMENT}\\)(?:{_DIR_SEGMENT}[\\/])*{_LAST_SEGMENT}"
+)
+
+_SECRET_PATTERNS: Tuple[Tuple[re.Pattern, str], ...] = (
+    (re.compile(r"#token=[^\s&\"'`]+"), "#token=<redacted>"),
+    (re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/-]+=*"), "Bearer <redacted>"),
+    (re.compile(r"\bsk-[A-Za-z0-9_-]{16,}"), "<redacted-key>"),
+    (re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}"), "<redacted-key>"),
+    (re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}"), "<redacted-key>"),
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "<redacted-key>"),
+    (re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}"), "<redacted-key>"),
+    (
+        re.compile(
+            r"(?i)\b(token|api[_-]?key|secret|password|passwd|authorization)"
+            r"(\s*[=:]\s*)(?!<redacted)[^\s,;&\"'`]+"
+        ),
+        r"\1\2<redacted>",
+    ),
+)
+
+_EMAIL = re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+")
+
+
+def _trailing_punctuation(match: str) -> Tuple[str, str]:
+    stripped = match.rstrip(".,;:)]}")
+    return stripped, match[len(stripped):]
+
+
+def _path_replacement(path: str, home: str = "") -> Tuple[str, bool]:
+    """Return (replacement, redacted?) for one matched absolute path."""
+    if len(home) > 1 and path.lower().startswith(home.lower()):
+        path = "~" + path[len(home):].replace("\\", "/")
+    windows = re.match(r"^[A-Za-z]:|^\\\\", path)
+    comparable = path.lower().replace("/", "\\") if windows else path
+    for prefix in _KEEP_PATH_PREFIXES:
+        if comparable.startswith(prefix):
+            return path, False
+    last = re.split(r"[\\/]", path)[-1]
+    ext = re.search(r"\.([A-Za-z0-9]{1,5})$", last)
+    if ext and not ext.group(1).isdigit():
+        return f"<path>.{ext.group(1)}", True
+    return "<path>", True
+
+
+def local_identity() -> Dict[str, Any]:
+    """The strings that identify this machine and its user."""
+    identity: Dict[str, Any] = {"home": os.path.expanduser("~"), "names": []}
+    names: List[str] = []
+    try:
+        names.append(getpass.getuser())
+    except Exception:
+        pass
+    try:
+        import pwd  # POSIX only
+
+        gecos = pwd.getpwuid(os.getuid()).pw_gecos.split(",")[0].strip()
+        if gecos:
+            names.append(gecos)
+    except Exception:
+        pass
+    try:
+        host = socket.gethostname().split(".")[0]
+        if host:
+            names.append(host)
+    except Exception:
+        pass
+    identity["names"] = names
+    return identity
+
+
+def redact(text: Any, identity: Optional[Dict[str, Any]] = None) -> Tuple[str, Dict[str, int]]:
+    """Scrub one field. Returns (text, counts by kind)."""
+    counts = {"secrets": 0, "emails": 0, "paths": 0, "identity": 0}
+    if text is None:
+        return "", counts
+    out = str(text)
+    identity = identity if identity is not None else local_identity()
+
+    for pattern, replacement in _SECRET_PATTERNS:
+        out, n = pattern.subn(replacement, out)
+        counts["secrets"] += n
+
+    out, n = _EMAIL.subn("<email>", out)
+    counts["emails"] += n
+
+    # The home directory is folded to `~` per path, not across the text first:
+    # on Windows that would turn C:\Users\name\… into ~\…, which no longer
+    # looks like an absolute path and would slip through unredacted.
+    home = identity.get("home") or ""
+
+    def _sub_path(match: re.Match) -> str:
+        path, tail = _trailing_punctuation(match.group(0))
+        replacement, redacted = _path_replacement(path, home)
+        if redacted:
+            counts["paths"] += 1
+        return replacement + tail
+
+    out = _WINDOWS_PATH.sub(_sub_path, out)
+    out = _POSIX_PATH.sub(_sub_path, out)
+    if len(home) > 1:
+        out = out.replace(home, "~")
+
+    # Letters-only boundaries, not \b: `\bname\b` misses "name_project" and
+    # "name2", because `_` and digits are word characters.
+    for name in sorted(set(identity.get("names") or []), key=len, reverse=True):
+        if len(name) < 3 or name.lower() in _COMMON_ACCOUNT_NAMES:
+            continue
+        pattern = re.compile(rf"(?<![A-Za-z]){re.escape(name)}(?![A-Za-z])", re.IGNORECASE)
+        out, n = pattern.subn("<user>", out)
+        counts["identity"] += n
+    return out, counts
+
+
+# --------------------------------------------------------------------------
+# Environment
+# --------------------------------------------------------------------------
+
+
+def _connection_kind(handle: Any) -> str:
+    try:
+        from . import resolve_bridge_client
+
+        if isinstance(handle, resolve_bridge_client.BridgeProxy):
+            return "in-app bridge"
+    except Exception:
+        pass
+    if os.environ.get("RESOLVE_SCRIPT_HOST"):
+        return "network scripting"
+    return "local scripting"
+
+
+def _os_description() -> str:
+    system = platform.system()
+    if system == "Darwin":
+        release = platform.mac_ver()[0] or platform.release()
+        return f"macOS {release} ({platform.machine()})"
+    if system == "Windows":
+        return f"Windows {platform.release()} ({platform.version()}, {platform.machine()})"
+    return f"{system} {platform.release()} ({platform.machine()})"
+
+
+def collect_environment(resolve_handle: Any, mcp_version: str) -> Dict[str, str]:
+    """What a maintainer needs to reproduce, read without connecting."""
+    env: Dict[str, str] = {"MCP server": mcp_version}
+    if resolve_handle is not None:
+        try:
+            env["DaVinci Resolve"] = (
+                f"{resolve_handle.GetProductName()} {resolve_handle.GetVersionString()}"
+            )
+        except Exception:
+            env["DaVinci Resolve"] = "connected, version unreadable"
+        env["Connection"] = _connection_kind(resolve_handle)
+    else:
+        env["DaVinci Resolve"] = "not connected"
+        env["Connection"] = "not connected"
+    try:
+        from . import resolve_runtime
+
+        mode = resolve_runtime.runtime_mode()
+        if not mode.get("running"):
+            env["Resolve process"] = "not running"
+        elif mode.get("headless") is True:
+            env["Resolve process"] = "running, headless (-nogui)"
+        elif mode.get("headless") is False:
+            env["Resolve process"] = "running, with UI"
+        else:
+            env["Resolve process"] = "running, mode unknown"
+    except Exception:
+        pass
+    env["OS"] = _os_description()
+    env["Python"] = platform.python_version()
+    return env
+
+
+# --------------------------------------------------------------------------
+# Draft
+# --------------------------------------------------------------------------
+
+
+def normalize_kind(kind: Any) -> Optional[str]:
+    return _KIND_ALIASES.get(str(kind or "").strip().lower().replace("-", "_").replace(" ", "_"))
+
+
+def _clip(text: str, limit: int = MAX_FIELD_CHARS) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit].rstrip() + "\n…(truncated)"
+
+
+def _steps_markdown(steps: Any) -> str:
+    if isinstance(steps, (list, tuple)):
+        return "\n".join(f"{i}. {s}" for i, s in enumerate(steps, 1) if str(s).strip())
+    return str(steps)
+
+
+def _fence(text: str) -> str:
+    fence = "```"
+    while fence in text:
+        fence += "`"
+    return f"{fence}\n{text}\n{fence}"
+
+
+def _environment_markdown(environment: Dict[str, str]) -> str:
+    rows = "\n".join(
+        f"| {key} | {str(value).replace('|', '/')} |" for key, value in environment.items()
+    )
+    return f"### Environment\n\n| | |\n|---|---|\n{rows}"
+
+
+def issue_url(repo: str, kind: str, title: str, body: str) -> str:
+    query = urlencode(
+        {
+            "template": KINDS[kind]["template"],
+            "labels": KINDS[kind]["label"],
+            "title": title,
+            "body": body,
+        },
+        quote_via=quote,
+    )
+    return f"https://github.com/{repo}/issues/new?{query}"
+
+
+def _fit_url(repo: str, kind: str, title: str, narrative: str, tail: str) -> Tuple[str, bool]:
+    """Build the link, shortening only the narrative if the whole body won't fit.
+
+    The environment table and footer are the part a maintainer cannot ask the
+    reporter to reconstruct later, so they are never the part cut.
+    """
+    url = issue_url(repo, kind, title, narrative + tail)
+    if len(url) <= MAX_URL_CHARS:
+        return url, False
+    lo, hi = 0, len(narrative)
+    best = issue_url(repo, kind, title, _TRUNCATION_NOTE.lstrip() + tail)
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        candidate = issue_url(repo, kind, title, narrative[:mid].rstrip() + _TRUNCATION_NOTE + tail)
+        if len(candidate) <= MAX_URL_CHARS:
+            best, lo = candidate, mid + 1
+        else:
+            hi = mid - 1
+    return best, True
+
+
+def build_issue(
+    kind: str,
+    title: str,
+    summary: str,
+    *,
+    steps: Any = None,
+    expected: Any = None,
+    actual: Any = None,
+    error: Any = None,
+    tool: Any = None,
+    tool_action: Any = None,
+    use_case: Any = None,
+    proposal: Any = None,
+    environment: Optional[Dict[str, str]] = None,
+    identity: Optional[Dict[str, Any]] = None,
+    repo: str = DEFAULT_REPO,
+) -> Dict[str, Any]:
+    """Redact every field, lay out the issue, and build the prefilled link."""
+    identity = identity if identity is not None else local_identity()
+    totals = {"secrets": 0, "emails": 0, "paths": 0, "identity": 0}
+
+    def scrub(value: Any) -> str:
+        text, counts = redact(value, identity)
+        for key, n in counts.items():
+            totals[key] += n
+        return _clip(text.strip())
+
+    clean_title = scrub(title).replace("\n", " ")[:200]
+    sections: List[str] = []
+
+    def add(heading: str, value: Any, render=lambda s: s) -> None:
+        if value is None or (isinstance(value, (list, tuple)) and not value) or not str(value).strip():
+            return
+        if isinstance(value, (list, tuple)):
+            value = [scrub(v) for v in value]
+            sections.append(f"### {heading}\n\n{render(value)}")
+        else:
+            sections.append(f"### {heading}\n\n{render(scrub(value))}")
+
+    if kind == "bug":
+        add("What happened", summary)
+        add("Steps to reproduce", steps, _steps_markdown)
+        add("Expected", expected)
+        add("Actual", actual)
+    else:
+        add("What I'd like", summary)
+        add("What I was trying to do", use_case)
+        add("How it could work", proposal)
+
+    if tool or tool_action:
+        call = " → ".join(f"`{scrub(v)}`" for v in (tool, tool_action) if v)
+        sections.append(f"### {'Failing call' if kind == 'bug' else 'Related call'}\n\n{call}")
+    if error is not None and str(error).strip():
+        sections.append(_fence(scrub(error)))
+
+    narrative = "\n\n".join(sections)
+    tail = ""
+    if environment:
+        tail = "\n\n" + _environment_markdown(
+            {key: scrub(value) for key, value in environment.items()}
+        )
+    tail += _FOOTER
+
+    url, truncated = _fit_url(repo, kind, clean_title, narrative, tail)
+    return {
+        "kind": kind,
+        "repo": repo,
+        "title": clean_title,
+        "body": narrative + tail,
+        "labels": [KINDS[kind]["label"]],
+        "url": url,
+        "url_truncated": truncated,
+        "redactions": totals,
+    }
+
+
+def next_step_guidance(truncated: bool) -> str:
+    text = (
+        "Nothing has been filed. Show the user the title and body above, then give "
+        "them the url: the issue is created only when they open it and press Submit "
+        "on GitHub under their own account (a GitHub account is required). "
+        "Redaction is best-effort — it removes paths, the local username, e-mail "
+        "addresses and secret-shaped strings, but cannot recognise a client, "
+        "project or person named in plain prose, so ask the user to check for "
+        "those before submitting."
+    )
+    if truncated:
+        text += (
+            " The body was too long for a link and the url carries a shortened "
+            "copy; tell the user to paste the full body from the chat into the "
+            "issue before submitting."
+        )
+    return text
+
+
+__all__ = [
+    "KINDS",
+    "MAX_URL_CHARS",
+    "build_issue",
+    "collect_environment",
+    "issue_url",
+    "local_identity",
+    "next_step_guidance",
+    "normalize_kind",
+    "redact",
+]