davinci-resolve-mcp 2.25.0 → 2.26.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 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.26.0
+
+**Fusion group-settings helpers** — Three new `fusion_comp` actions for
+authoring and patching `GroupOperator` macros without leaving the kernel.
+`group_settings_export` writes a live group to a `.setting` file and returns a
+parsed `published_inputs` summary using a balanced-brace walker so nested
+`UserControls` / `ControlGroup` tables are bounded correctly (the original
+flat-regex parser truncated `InstanceInput` bodies at the first inner `}`).
+`group_settings_splice_inputs` replaces the `Inputs = ordered() { ... }` block
+of one `.setting` with the matching block from another, preserving the source's
+outer structure and inner `Tools`. `group_settings_load` applies a `.setting`
+to a live group with an automatic timestamped backup, wrapped in
+`StartUndo`/`Lock`/`LoadSettings`/`Unlock`/`EndUndo(True)` so Fusion's Ctrl+Z
+reverses the change — verified live via direct BMD API.
+
+**bulk_set_expressions** — Companion to the existing `bulk_set_inputs`. Batch
+attach Fusion expressions across many timeline-item comps in one call. Each op
+requires timeline scope plus `tool_name`, `input_name`, `expression`. Returns
+per-op `success`/`error` rows + `op_count`, matching the bulk-inputs contract.
+Useful for animating many controls at once (`time/30`, etc.) under a single
+chat turn.
+
+**Headless batch-runner CLI** — New
+`davinci-resolve-mcp batch <plan|run|status|list|resume|cancel>` subcommand
+drives `src/utils/media_analysis_jobs` from outside an MCP/chat client so long
+analysis batches can run via cron, CI, or terminal without holding a chat turn
+open. The orchestration loop and durable state stay in the existing jobs
+engine; the CLI only handles argv, progress streaming, and exit codes
+(`0` ok / `2` partial / `3` fatal / `130` Ctrl+C). JSON mode (`--json`)
+emits one record per progress event for log scraping. Closes #42.
+
+**Adapted from PR #40** — Group-settings work originated as a contribution
+from @RaincloudTheDragon; PR #43 retains the keepable parts (parser, exporter,
+splicer, loader, `bulk_set_expressions`) with a balanced-brace fix on the
+parser and an undo+lock wrap on `group_settings_load`. The two AMZ-specific
+templates and the static checklist from #40 were dropped as out-of-scope for a
+general kernel.
+
 ## What's New in v2.25.0
 
 **Agentic flow improvements** — A second-pass review against the Claude

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.25.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.26.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/bin/davinci-resolve-mcp.mjs

@@ -41,6 +41,7 @@ Usage:
   davinci-resolve-mcp doctor [install.py options]
   davinci-resolve-mcp server [server.py options]
   davinci-resolve-mcp control-panel [control panel options]
+  davinci-resolve-mcp batch <plan|run|status|list|resume|cancel> [options]
   davinci-resolve-mcp --version
   davinci-resolve-mcp --help
 
@@ -48,6 +49,8 @@ Examples:
   npx davinci-resolve-mcp setup
   npx davinci-resolve-mcp setup --clients cursor,claude-desktop
   npx davinci-resolve-mcp doctor
+  npx davinci-resolve-mcp batch run /path/to/footage --depth standard
+  npx davinci-resolve-mcp batch run /path/to/footage --json > progress.log
 
 Environment:
   DAVINCI_RESOLVE_MCP_INSTALL_ROOT   Override the managed install directory.
@@ -335,6 +338,13 @@ function commandControlPanel(args) {
   run(command, commandArgs, { cwd: root });
 }
 
+function commandBatch(args) {
+  const root = syncManagedInstall(installRoot());
+  const python = venvPython(root) || findSupportedPython();
+  const [command, ...commandArgs] = pythonCommandLine(python, ["-m", "src.batch_cli", ...args]);
+  run(command, commandArgs, { cwd: root });
+}
+
 function main() {
   const argv = process.argv.slice(2);
   // No args → run the MCP stdio server. Anything printed to stdout would
@@ -366,6 +376,10 @@ function main() {
       commandControlPanel(args);
       return;
     }
+    if (command === "batch") {
+      commandBatch(args);
+      return;
+    }
 
     console.error(`Unknown command: ${command}\n`);
     console.error(usage());

package/docs/SKILL.md

@@ -923,6 +923,18 @@ Key actions:
 - `start_undo(name?)` / `end_undo(keep?)`
 - `bulk_set_inputs(ops)` — batch set inputs across multiple timeline item comps in
   one call; each op requires timeline scope plus `tool_name`, `input_name`, `value`
+- `bulk_set_expressions(ops)` — batch attach expressions across multiple timeline
+  item comps in one call; each op requires timeline scope plus `tool_name`,
+  `input_name`, `expression`
+- `group_settings_export(group_name, path, include_advisory?)` — write a
+  `GroupOperator` to disk and return a parsed published-input summary
+- `group_settings_splice_inputs(source_path, template_path, dest_path?, source_group_name?, template_group_name?)` —
+  replace one `.setting` file's `Inputs = ordered() { ... }` block with the
+  matching block from another, preserving inner tools and outer structure;
+  balanced-brace parser handles nested `UserControls`
+- `group_settings_load(group_name, settings_path, backup_path?, undo_name?)` —
+  apply a `.setting` to a live group with an auto backup and an undo wrap so
+  Ctrl+Z reverses the change
 
 Fusion Composition kernel actions (v2.12.0+) add safer graph inspection and
 mutation wrappers around the raw Fusion API:

package/docs/kernels/fusion-composition-kernel.md

@@ -30,10 +30,40 @@ All actions are exposed through `fusion_comp`.
 | `safe_set_inputs` | Batch write inputs on one tool with optional readback classification. |
 | `safe_connect_tools` | Validate source/target tools before connecting a source output to a target input. |
 | `fusion_boundary_report` | Return graph capabilities plus a composition snapshot for the selected comp scope. |
+| `bulk_set_expressions` | Batch `SetExpression` across scoped timeline-item Fusion comps. Each op needs `tool_name`, `input_name`, `expression`, plus a timeline scope. Wraps each op in `StartUndo`/`EndUndo` + `comp.Lock`. |
+| `group_settings_export` | Save a named `GroupOperator`'s settings to a `.setting` file via `SaveSettings`, returning a parsed published-input summary. |
+| `group_settings_splice_inputs` | Replace the `Inputs = ordered() { ... }` block of `source_path` with the matching block from `template_path` and write `dest_path`. Read-only against Resolve; pure file operation. |
+| `group_settings_load` | Backup the current group state, then `LoadSettings` from a `.setting` file. Wrapped in `StartUndo`/`EndUndo` + `comp.Lock` so Fusion's Ctrl+Z can reverse it. Backup path is returned alongside any error. |
+| `probe_group_published_inputs` | Read live published `Input1..InputN` slots off a `GroupOperator`, optionally cross-referenced with a `.setting` file summary. |
 
 The pre-existing `bulk_set_inputs` action remains the batch path for applying
 input writes across multiple explicitly scoped timeline-item Fusion comps.
 
+### `group_settings_splice_inputs` notes
+
+The Fusion `.setting` format is a Lua-like nested structure: an InstanceInput
+commonly contains `UserControls = ordered() { Custom = { ... } }` tables, so any
+parsing that uses a flat regex will truncate bodies at the first inner `}`. This
+kernel uses balanced-brace scanning end-to-end. Practical implications:
+
+- The action only swaps the published `Inputs = ordered() { ... }` block. The
+  group's outer name, inner `Tools = ordered() { ... }` section, and surrounding
+  structure are preserved byte-for-byte.
+- You must provide the *new* layout as a real `.setting` file (typically
+  exported from a known-good group via `group_settings_export`). The kernel does
+  not ship hardcoded templates.
+- `template_group_name` is optional when the template file contains a single
+  `GroupOperator`; pass it when the template file contains multiple groups and
+  you want a specific one.
+
+### `group_settings_load` Edit-page caveat
+
+`LoadSettings` may update inner tool wiring but not refresh Edit-page
+`InstanceInput` order until the group is selected in Fusion and reloaded via UI.
+This is a Resolve quirk, not a kernel bug. The action always backs up the group
+to a timestamped sibling of `settings_path` first; the backup path is returned
+in success and in error responses.
+
 ## Scope Matrix
 
 | Scope | Probe Support | Mutation Support | Notes |

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.25.0"
+VERSION = "2.26.0"
 SUPPORTED_PYTHON_MIN = (3, 10)
 SUPPORTED_PYTHON_MAX = (3, 12)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/batch_cli.py

@@ -0,0 +1,456 @@
+"""Headless batch-runner CLI for source-safe media analysis.
+
+Drives src.utils.media_analysis_jobs from outside an MCP/chat client so users
+can run long batches via cron, CI, or terminal without holding a chat turn
+open. The orchestration loop and durable state live in the jobs engine; this
+module only handles argv, progress streaming, and exit codes.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import sys
+import time
+from typing import Any, Dict, List, Optional
+
+from src.utils.media_analysis import (
+    build_plan,
+    detect_capabilities,
+)
+from src.utils.media_analysis_jobs import (
+    batch_job_status,
+    cancel_batch_job,
+    create_batch_job_from_paths,
+    list_batch_jobs,
+    records_from_paths,
+    resume_batch_job,
+    run_batch_job_slice,
+)
+
+
+EXIT_OK = 0
+EXIT_PARTIAL = 2
+EXIT_FATAL = 3
+EXIT_CANCELED = 130
+
+_TERMINAL_STATUSES = {"completed", "completed_with_errors", "canceled"}
+
+_canceled = False
+
+
+def _on_sigint(signum, frame):  # noqa: ARG001 - signal handler signature
+    global _canceled
+    _canceled = True
+
+
+def _emit(message: str, *, json_mode: bool, payload: Optional[Dict[str, Any]] = None) -> None:
+    if json_mode:
+        sys.stdout.write(json.dumps(payload or {}, ensure_ascii=False) + "\n")
+    else:
+        sys.stdout.write(message + "\n")
+    sys.stdout.flush()
+
+
+def _build_params(args: argparse.Namespace) -> Dict[str, Any]:
+    params: Dict[str, Any] = {}
+    if getattr(args, "depth", None):
+        params["depth"] = args.depth
+    if getattr(args, "source_trust", None):
+        params["source_trust"] = args.source_trust
+    if getattr(args, "summary_style", None):
+        params["vision"] = {"summary_style": args.summary_style}
+        params["analysis_summary_style"] = args.summary_style
+    return params
+
+
+def _exit_for_status(status: Optional[str]) -> int:
+    if status == "completed":
+        return EXIT_OK
+    if status == "completed_with_errors":
+        return EXIT_PARTIAL
+    if status == "canceled":
+        return EXIT_CANCELED
+    return EXIT_FATAL
+
+
+def _drive_to_completion(
+    project_root: str,
+    job_id: str,
+    *,
+    max_clips: int,
+    max_seconds: Optional[float],
+    json_mode: bool,
+) -> int:
+    signal.signal(signal.SIGINT, _on_sigint)
+    while True:
+        if _canceled:
+            cancel_batch_job(project_root, job_id)
+            _emit(
+                "Interrupted — job canceled",
+                json_mode=json_mode,
+                payload={"event": "canceled", "job_id": job_id},
+            )
+            return EXIT_CANCELED
+        slice_result = run_batch_job_slice(
+            project_root,
+            job_id,
+            max_clips=max_clips,
+            max_seconds=max_seconds,
+        )
+        if not slice_result.get("success"):
+            _emit(
+                f"Slice failed: {slice_result.get('error')}",
+                json_mode=json_mode,
+                payload={"event": "slice_failed", **slice_result},
+            )
+            return EXIT_FATAL
+        for clip in slice_result.get("processed") or []:
+            _emit(
+                f"  [{(clip.get('status') or '?'):>9}] #{(clip.get('position') or 0) + 1}"
+                + (f" — {clip.get('error')}" if clip.get("error") else ""),
+                json_mode=json_mode,
+                payload={"event": "clip_done", **clip},
+            )
+        job_state = slice_result.get("job") or {}
+        status = job_state.get("status")
+        processed_count = int(slice_result.get("processed_count") or 0)
+        if status in _TERMINAL_STATUSES or processed_count == 0:
+            final = batch_job_status(
+                project_root, job_id, include_clips=False, include_events=False
+            )
+            counts = final.get("progress", {})
+            status = final.get("status")
+            _emit(
+                f"Done: {status} ({counts.get('done_clips', 0)}/{counts.get('total_clips', 0)})",
+                json_mode=json_mode,
+                payload={
+                    "event": "job_done",
+                    "job_id": job_id,
+                    "status": status,
+                    "progress": counts,
+                    "succeeded_clips": final.get("succeeded_clips"),
+                    "failed_clips": final.get("failed_clips"),
+                    "skipped_clips": final.get("skipped_clips"),
+                },
+            )
+            return _exit_for_status(status)
+
+
+def _cmd_plan(args: argparse.Namespace) -> int:
+    records, warnings = records_from_paths(args.paths, recursive=args.recursive)
+    if not records:
+        _emit(
+            "No analyzable media files found",
+            json_mode=args.json,
+            payload={"success": False, "error": "no_media", "warnings": warnings},
+        )
+        return EXIT_FATAL
+    params = _build_params(args)
+    if args.analysis_root:
+        params["analysis_root"] = args.analysis_root
+    target = {
+        "type": "paths",
+        "paths": [r["file_path"] for r in records],
+        "recursive": args.recursive,
+    }
+    plan = build_plan(
+        project_name=args.project_name,
+        project_id=None,
+        records=records,
+        target=target,
+        params=params,
+        capabilities=detect_capabilities(),
+    )
+    if not plan.get("success"):
+        _emit(
+            f"Plan failed: {plan.get('error')}",
+            json_mode=args.json,
+            payload=plan,
+        )
+        return EXIT_FATAL
+    if args.json:
+        plan_payload = dict(plan)
+        if warnings:
+            plan_payload["warnings"] = warnings
+        _emit("", json_mode=True, payload=plan_payload)
+    else:
+        root = (plan.get("output_root") or {}).get("project_root", "?")
+        _emit(f"Project root : {root}", json_mode=False)
+        _emit(f"Depth        : {plan.get('depth', '?')}", json_mode=False)
+        _emit(
+            f"Clips        : {plan.get('clip_count', 0)}"
+            f" ({plan.get('reusable_clip_count', 0)} reusable)",
+            json_mode=False,
+        )
+        _emit(
+            f"Est. seconds : {plan.get('estimated_seconds_after_reuse', '?')}",
+            json_mode=False,
+        )
+        if plan.get("capability_gaps"):
+            _emit(f"Missing tools: {plan['capability_gaps']}", json_mode=False)
+        for w in warnings:
+            _emit(f"  warning: {w}", json_mode=False)
+    return EXIT_OK
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    params = _build_params(args)
+    create = create_batch_job_from_paths(
+        project_name=args.project_name,
+        paths=args.paths,
+        analysis_root=args.analysis_root,
+        recursive=args.recursive,
+        params=params,
+        name=args.name,
+    )
+    if not create.get("success"):
+        _emit(
+            f"Job creation failed: {create.get('error') or create.get('status')}",
+            json_mode=args.json,
+            payload=create,
+        )
+        return EXIT_FATAL
+    job = create["job"]
+    job_id = job["job_id"]
+    project_root = job["project_root"]
+    total = (job.get("progress") or {}).get("total_clips", 0)
+    _emit(
+        f"Created job {job_id}  ({total} clips, root: {project_root})",
+        json_mode=args.json,
+        payload={
+            "event": "job_created",
+            "job_id": job_id,
+            "project_root": project_root,
+            "total_clips": total,
+        },
+    )
+    if args.no_follow:
+        return EXIT_OK
+    return _drive_to_completion(
+        project_root,
+        job_id,
+        max_clips=args.max_clips,
+        max_seconds=args.max_seconds,
+        json_mode=args.json,
+    )
+
+
+def _emit_status(payload: Dict[str, Any], *, json_mode: bool) -> None:
+    if json_mode:
+        _emit("", json_mode=True, payload=payload)
+        return
+    if not payload.get("success"):
+        _emit(f"Error: {payload.get('error')}", json_mode=False)
+        return
+    counts = payload.get("progress", {})
+    _emit(f"Job          : {payload.get('job_id')}", json_mode=False)
+    _emit(
+        f"Status       : {payload.get('status')} ({payload.get('phase')})",
+        json_mode=False,
+    )
+    _emit(
+        f"Progress     : {counts.get('done_clips', 0)}/{counts.get('total_clips', 0)} ({counts.get('percent', 0)}%)",
+        json_mode=False,
+    )
+    _emit(f"Succeeded    : {payload.get('succeeded_clips')}", json_mode=False)
+    _emit(f"Failed       : {payload.get('failed_clips')}", json_mode=False)
+    _emit(f"Skipped      : {payload.get('skipped_clips')}", json_mode=False)
+    if payload.get("last_error"):
+        _emit(f"Last error   : {payload['last_error']}", json_mode=False)
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    payload = batch_job_status(args.project_root, args.job_id)
+    _emit_status(payload, json_mode=args.json)
+    return EXIT_OK if payload.get("success") else EXIT_FATAL
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    payload = list_batch_jobs(args.project_root, limit=args.limit)
+    if args.json:
+        _emit("", json_mode=True, payload=payload)
+        return EXIT_OK if payload.get("success") else EXIT_FATAL
+    if not payload.get("success"):
+        _emit(f"Error: {payload.get('error')}", json_mode=False)
+        return EXIT_FATAL
+    jobs = payload.get("jobs") or []
+    if not jobs:
+        _emit("No jobs found", json_mode=False)
+        return EXIT_OK
+    _emit(f"{'JOB ID':<28} {'STATUS':<22} {'CLIPS':>10}  NAME", json_mode=False)
+    for job in jobs:
+        counts = job.get("progress", {})
+        clip_col = f"{counts.get('done_clips', 0)}/{counts.get('total_clips', 0)}"
+        _emit(
+            f"{job['job_id']:<28} {job['status']:<22} {clip_col:>10}  {job.get('name', '')}",
+            json_mode=False,
+        )
+    return EXIT_OK
+
+
+def _cmd_resume(args: argparse.Namespace) -> int:
+    resumed = resume_batch_job(args.project_root, args.job_id)
+    if not resumed.get("success"):
+        _emit(
+            f"Resume failed: {resumed.get('error')}",
+            json_mode=args.json,
+            payload=resumed,
+        )
+        return EXIT_FATAL
+    _emit(
+        f"Resumed {args.job_id}",
+        json_mode=args.json,
+        payload={"event": "resumed", "job_id": args.job_id},
+    )
+    return _drive_to_completion(
+        args.project_root,
+        args.job_id,
+        max_clips=args.max_clips,
+        max_seconds=args.max_seconds,
+        json_mode=args.json,
+    )
+
+
+def _cmd_cancel(args: argparse.Namespace) -> int:
+    payload = cancel_batch_job(args.project_root, args.job_id)
+    _emit_status(payload, json_mode=args.json)
+    return EXIT_OK if payload.get("success") else EXIT_FATAL
+
+
+def _add_run_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("paths", nargs="+", help="Files or directories to analyze")
+    parser.add_argument(
+        "--no-recursive",
+        dest="recursive",
+        action="store_false",
+        default=True,
+        help="Do not descend into subdirectories (default: recurse)",
+    )
+    parser.add_argument(
+        "--analysis-root",
+        help="Override analysis output root (default ~/Documents/DaVinci Resolve MCP/analysis)",
+    )
+    parser.add_argument(
+        "--project-name",
+        default=f"CLI batch {time.strftime('%Y-%m-%d')}",
+        help="Project name written into the analysis root layout",
+    )
+    parser.add_argument(
+        "--depth",
+        choices=["quick", "standard", "deep", "custom"],
+        help="Analysis depth (default: standard)",
+    )
+    parser.add_argument(
+        "--source-trust",
+        choices=["auto", "filename", "low", "medium", "high"],
+        help="Trust tier hint for the vision pass",
+    )
+    parser.add_argument(
+        "--summary-style",
+        choices=["full", "concise", "creative", "technical"],
+        help="Narrative tone for clip_summary / shot descriptions",
+    )
+    parser.add_argument("--name", help="Job display name")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    # SUPPRESS keeps the subparser from overwriting a --json passed before the
+    # subcommand (its default would otherwise win over the top-level parser).
+    # Post-processed in main() so handlers always see a real bool.
+    common.add_argument(
+        "--json",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="Emit one JSON object per progress event instead of human-readable lines",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="davinci-resolve-mcp batch",
+        description=(
+            "Headless runner for source-safe media analysis. Wraps the same engine "
+            "the MCP server uses; durable state lives in <project-root>/jobs.sqlite."
+        ),
+        parents=[common],
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_plan = sub.add_parser(
+        "plan",
+        help="Dry-run: print what would be analyzed without creating a job",
+        parents=[common],
+    )
+    _add_run_args(p_plan)
+
+    p_run = sub.add_parser(
+        "run",
+        help="Create a batch job and drive it to completion",
+        parents=[common],
+    )
+    _add_run_args(p_run)
+    p_run.add_argument(
+        "--max-clips",
+        type=int,
+        default=1,
+        help="Clips processed per slice (default 1, max 25)",
+    )
+    p_run.add_argument(
+        "--max-seconds",
+        type=float,
+        default=None,
+        help="Optional wall-clock budget per slice (seconds)",
+    )
+    p_run.add_argument(
+        "--no-follow",
+        action="store_true",
+        help="Create the job and exit immediately instead of looping until done",
+    )
+
+    p_status = sub.add_parser("status", help="Inspect a job", parents=[common])
+    p_status.add_argument("job_id")
+    p_status.add_argument("--project-root", required=True)
+
+    p_list = sub.add_parser(
+        "list", help="List jobs under a project root", parents=[common]
+    )
+    p_list.add_argument("--project-root", required=True)
+    p_list.add_argument("--limit", type=int, default=50)
+
+    p_resume = sub.add_parser(
+        "resume", help="Resume a queued / canceled job", parents=[common]
+    )
+    p_resume.add_argument("job_id")
+    p_resume.add_argument("--project-root", required=True)
+    p_resume.add_argument("--max-clips", type=int, default=1)
+    p_resume.add_argument("--max-seconds", type=float, default=None)
+
+    p_cancel = sub.add_parser(
+        "cancel", help="Cancel a running job", parents=[common]
+    )
+    p_cancel.add_argument("job_id")
+    p_cancel.add_argument("--project-root", required=True)
+
+    return parser
+
+
+_HANDLERS = {
+    "plan": _cmd_plan,
+    "run": _cmd_run,
+    "status": _cmd_status,
+    "list": _cmd_list,
+    "resume": _cmd_resume,
+    "cancel": _cmd_cancel,
+}
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "json"):
+        args.json = False
+    return _HANDLERS[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.25.0"
+VERSION = "2.26.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 329-tool granular server instead
 """
 
-VERSION = "2.25.0"
+VERSION = "2.26.0"
 
 import base64
 import os
@@ -93,6 +93,13 @@ from src.utils.timeline_title_text import (
     timeline_item_get_property_map as _timeline_item_get_property_map,
 )
 from src.utils.multicam import build_multicam_setup_plan
+from src.utils.fusion_group_settings import (
+    FUSION_COMMIT_CHECKLIST,
+    FUSION_GROUP_GUARDRAILS,
+    default_backup_path,
+    parse_setting_file,
+    splice_inputs_block,
+)
 from src.utils import analysis_runs as _analysis_runs
 from src.utils import brain_edits as _brain_edits
 from src.utils import media_pool_changes as _media_pool_changes
@@ -16864,6 +16871,304 @@ def color_group(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 # TOOL 27: fusion_comp
 # ═══════════════════════════════════════════════════════════════════════════════
 
+_FUSION_GROUP_KERNEL_ACTIONS = [
+    "group_settings_export",
+    "group_settings_splice_inputs",
+    "group_settings_load",
+    "bulk_set_expressions",
+    "probe_group_published_inputs",
+]
+
+
+def _find_fusion_group(comp, group_name: str):
+    tool = comp.FindTool(group_name)
+    if tool:
+        attrs = tool.GetAttrs() or {}
+        if attrs.get("TOOLS_RegID") == "GroupOperator":
+            return tool
+    tool_list = comp.GetToolList(False, "GroupOperator") or {}
+    for idx in tool_list:
+        candidate = tool_list[idx]
+        attrs = candidate.GetAttrs() or {}
+        if attrs.get("TOOLS_Name") == group_name:
+            return candidate
+    return None
+
+
+def _resolve_setting_path(p: Dict[str, Any], key: str = "path") -> Tuple[Optional[str], Optional[Dict[str, Any]]]:
+    raw = p.get(key)
+    if not raw or not str(raw).strip():
+        return None, _err(f"{key} is required")
+    return os.path.abspath(str(raw)), None
+
+
+def _fusion_group_advisory(include: bool) -> Dict[str, Any]:
+    if not include:
+        return {}
+    return {
+        "guardrails": list(FUSION_GROUP_GUARDRAILS),
+        "commit_checklist": list(FUSION_COMMIT_CHECKLIST),
+    }
+
+
+def _fusion_group_settings_export(comp, p: Dict[str, Any]) -> Dict[str, Any]:
+    group_name = p.get("group_name")
+    if not group_name:
+        return _err("group_name is required")
+    path, path_err = _resolve_setting_path(p)
+    if path_err:
+        return path_err
+    group = _find_fusion_group(comp, str(group_name))
+    if not group:
+        return _err(f"GroupOperator {group_name!r} not found in comp")
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    try:
+        group.SaveSettings(path)
+    except Exception as exc:
+        return _err(f"SaveSettings failed: {exc}")
+    if not os.path.isfile(path):
+        return _err(f"SaveSettings did not create file at {path!r}")
+    try:
+        parsed = parse_setting_file(path, group_name=str(group_name))
+    except Exception as exc:
+        return {
+            "success": True,
+            "path": path,
+            "group_name": group_name,
+            "parse_warning": f"saved, but summary parse failed: {exc}",
+            **_fusion_group_advisory(p.get("include_advisory", False)),
+        }
+    return {
+        "success": True,
+        "path": path,
+        "group_name": group_name,
+        "published_inputs": parsed["published_inputs"],
+        "input_count": parsed["input_count"],
+        **_fusion_group_advisory(p.get("include_advisory", False)),
+    }
+
+
+def _fusion_group_settings_splice_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
+    source_path, src_err = _resolve_setting_path(p, "source_path")
+    if src_err:
+        return src_err
+    if not os.path.isfile(source_path):
+        return _err(f"source_path not found: {source_path}")
+    template_path, tpl_err = _resolve_setting_path(p, "template_path")
+    if tpl_err:
+        return tpl_err
+    if not os.path.isfile(template_path):
+        return _err(f"template_path not found: {template_path}")
+    dest_path = p.get("dest_path")
+    if dest_path:
+        dest_path = os.path.abspath(str(dest_path))
+    else:
+        root, ext = os.path.splitext(source_path)
+        dest_path = f"{root}.patched{ext or '.setting'}"
+    try:
+        summary = splice_inputs_block(
+            source_path,
+            template_path,
+            dest_path,
+            source_group_name=p.get("source_group_name") or p.get("group_name"),
+            template_group_name=p.get("template_group_name"),
+        )
+    except Exception as exc:
+        return _err(f"splice failed: {exc}")
+    return {
+        "success": True,
+        "dest_path": summary["dest_path"],
+        "summary": summary,
+        **_fusion_group_advisory(p.get("include_advisory", False)),
+    }
+
+
+def _fusion_group_settings_load(comp, p: Dict[str, Any]) -> Dict[str, Any]:
+    group_name = p.get("group_name")
+    if not group_name:
+        return _err("group_name is required")
+    settings_path, path_err = _resolve_setting_path(p, "settings_path")
+    if path_err:
+        return path_err
+    if not os.path.isfile(settings_path):
+        return _err(f"settings_path not found: {settings_path}")
+    group = _find_fusion_group(comp, str(group_name))
+    if not group:
+        return _err(f"GroupOperator {group_name!r} not found in comp")
+    backup_path = p.get("backup_path")
+    if backup_path:
+        backup_path = os.path.abspath(str(backup_path))
+    else:
+        backup_path = default_backup_path(settings_path)
+    try:
+        os.makedirs(os.path.dirname(backup_path) or ".", exist_ok=True)
+        group.SaveSettings(backup_path)
+    except Exception as exc:
+        return _err(f"backup SaveSettings failed: {exc}")
+
+    undo_name = p.get("undo_name", f"MCP group_settings_load {group_name}")
+    undo_started = False
+    keep_undo = False
+    error_message: Optional[str] = None
+    try:
+        try:
+            comp.StartUndo(undo_name)
+            undo_started = True
+        except Exception:
+            undo_started = False
+        comp.Lock()
+        try:
+            group.LoadSettings(settings_path)
+            keep_undo = True
+        finally:
+            comp.Unlock()
+    except Exception as exc:
+        error_message = str(exc)
+    finally:
+        if undo_started:
+            try:
+                comp.EndUndo(keep_undo)
+            except Exception:
+                pass
+
+    if error_message is not None:
+        return _err(
+            f"LoadSettings failed: {error_message}",
+            remediation=f"Group state preserved by backup at {backup_path}",
+        )
+    return {
+        "success": True,
+        "group_name": group_name,
+        "settings_path": settings_path,
+        "backup_path": backup_path,
+        "warning": (
+            "Group preserved. If Edit Controls don't refresh, select the group in "
+            "Fusion and use UI Load Settings to remap InstanceInput order."
+        ),
+        **_fusion_group_advisory(p.get("include_advisory", False)),
+    }
+
+
+def _fusion_comp_bulk_set_expressions(p: Dict[str, Any]) -> Dict[str, Any]:
+    ops = p.get("ops")
+    if not isinstance(ops, list) or not ops:
+        return _err(
+            "bulk_set_expressions requires params.ops: non-empty list of objects. "
+            "Each op must include tool_name, input_name, expression, and a timeline scope: "
+            "clip_id, timeline_item_id, or timeline_item={track_type, track_index, item_index}. "
+            "Optional per-op: comp_name, comp_index, time, undo_name."
+        )
+    results: List[Dict[str, Any]] = []
+    for index, op in enumerate(ops):
+        if not isinstance(op, dict):
+            results.append({"index": index, "error": "op must be an object"})
+            continue
+        if not _has_fusion_timeline_scope(op):
+            results.append({"index": index, "error": "timeline scope is required for bulk_set_expressions"})
+            continue
+        missing = [key for key in ("tool_name", "input_name", "expression") if key not in op]
+        if missing:
+            results.append({"index": index, "error": f"missing required field(s): {', '.join(missing)}"})
+            continue
+        comp, comp_err = _resolve_fusion_comp(op, require_timeline_scope=True)
+        if comp_err:
+            results.append({"index": index, "error": comp_err.get("error", str(comp_err))})
+            continue
+        tool = comp.FindTool(op["tool_name"])
+        if not tool:
+            results.append({"index": index, "error": f"Tool {op['tool_name']!r} not found"})
+            continue
+        undo_name = op.get("undo_name", f"MCP bulk_set_expressions #{index}")
+        undo_started = False
+        keep_undo = False
+        error_message: Optional[str] = None
+        try:
+            try:
+                comp.StartUndo(undo_name)
+                undo_started = True
+            except Exception:
+                undo_started = False
+            comp.Lock()
+            try:
+                time = op.get("time", 0)
+                inp = tool[op["input_name"]]
+                if not inp:
+                    raise ValueError(f"Input {op['input_name']!r} not found on {op['tool_name']!r}")
+                inp.SetExpression(str(op["expression"]), time)
+                keep_undo = True
+            finally:
+                comp.Unlock()
+        except Exception as exc:
+            error_message = str(exc)
+        finally:
+            if undo_started:
+                try:
+                    comp.EndUndo(keep_undo)
+                except Exception:
+                    pass
+        if error_message is not None:
+            results.append({"index": index, "error": error_message})
+        elif keep_undo:
+            results.append({"index": index, "success": True, "expression": op["expression"]})
+    return {"results": results, "op_count": len(ops)}
+
+
+def _fusion_probe_group_published_inputs(comp, p: Dict[str, Any]) -> Dict[str, Any]:
+    group_name = p.get("group_name")
+    if not group_name:
+        return _err("group_name is required")
+    group = _find_fusion_group(comp, str(group_name))
+    if not group:
+        return _err(f"GroupOperator {group_name!r} not found in comp")
+    max_inputs = p.get("max_inputs", 32)
+    try:
+        max_inputs = int(max_inputs)
+    except (TypeError, ValueError):
+        max_inputs = 32
+    time = p.get("time", 0)
+    live_inputs: List[Dict[str, Any]] = []
+    for index in range(1, max_inputs + 1):
+        slot = f"Input{index}"
+        try:
+            inp = group[slot]
+        except Exception:
+            break
+        if not inp:
+            break
+        row: Dict[str, Any] = {"slot": slot}
+        try:
+            attrs = inp.GetAttrs() or {}
+            row["name"] = attrs.get("INPS_Name", "")
+            row["type"] = attrs.get("INPS_DataType", "")
+        except Exception:
+            pass
+        try:
+            row["value"] = _ser(inp[time])
+        except Exception as exc:
+            row["value_error"] = str(exc)
+        try:
+            row["expression"] = inp.GetExpression(time)
+        except Exception:
+            row["expression"] = None
+        live_inputs.append(row)
+
+    file_summary: Optional[Dict[str, Any]] = None
+    settings_path = p.get("settings_path")
+    if settings_path and os.path.isfile(str(settings_path)):
+        try:
+            file_summary = parse_setting_file(str(settings_path), group_name=str(group_name))
+        except Exception as exc:
+            file_summary = {"error": str(exc)}
+
+    return {
+        "group_name": group_name,
+        "live_inputs": live_inputs,
+        "live_input_count": len(live_inputs),
+        "file_summary": file_summary,
+        **_fusion_group_advisory(p.get("include_advisory", False)),
+    }
+
+
 def _fusion_comp_bulk_set_inputs(p: Dict[str, Any]) -> Dict[str, Any]:
     """Apply set_input across many explicitly scoped timeline-item Fusion comps."""
     ops = p.get("ops")
@@ -17177,6 +17482,14 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       start_undo(name?) -> {success}
       end_undo(keep?) -> {success}
       bulk_set_inputs(ops) -> {results, op_count} — each op requires timeline scope plus tool_name, input_name, value
+      bulk_set_expressions(ops) -> {results, op_count} — each op requires timeline scope plus tool_name, input_name, expression
+      group_settings_export(group_name, path, include_advisory?) -> {path, published_inputs, input_count}
+      group_settings_splice_inputs(source_path, template_path, dest_path?, source_group_name?, template_group_name?) -> {dest_path, summary}
+        Replace a source .setting's `Inputs = ordered() { ... }` block with the matching block from template_path.
+        Both files are read; neither GroupOperator is loaded into Resolve. Inner tools and outer structure are preserved.
+      group_settings_load(group_name, settings_path, backup_path?, undo_name?) -> {settings_path, backup_path}
+        Wraps the LoadSettings call in StartUndo/EndUndo + comp.Lock for reversibility.
+      probe_group_published_inputs(group_name, settings_path?, max_inputs?, time?) -> {live_inputs, file_summary?}
       fusion_graph_capabilities(...) -> {supported, boundaries, common_tools}
       probe_fusion_comp(include_io?, max_tools?) -> {name, tool_count, tools}
       probe_fusion_tool(tool_name, include_io?) -> {found, tool}
@@ -17193,11 +17506,22 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 
     if action == "bulk_set_inputs":
         return _fusion_comp_bulk_set_inputs(p)
+    if action == "bulk_set_expressions":
+        return _fusion_comp_bulk_set_expressions(p)
+    if action == "group_settings_splice_inputs":
+        return _fusion_group_settings_splice_inputs(p)
 
     comp, comp_err = _resolve_fusion_comp(p)
     if comp_err:
         return comp_err
 
+    if action == "group_settings_export":
+        return _fusion_group_settings_export(comp, p)
+    if action == "group_settings_load":
+        return _fusion_group_settings_load(comp, p)
+    if action == "probe_group_published_inputs":
+        return _fusion_probe_group_published_inputs(comp, p)
+
     if action == "fusion_graph_capabilities":
         return _fusion_graph_capabilities(comp)
     elif action == "probe_fusion_comp":
@@ -17449,6 +17773,8 @@ def fusion_comp(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         "get_comp_info","set_frame_range","render",
         "start_undo","end_undo",
         "bulk_set_inputs",
+        "bulk_set_expressions",
+        *_FUSION_GROUP_KERNEL_ACTIONS,
         *_FUSION_KERNEL_ACTIONS,
     ])
 

package/src/utils/fusion_group_settings.py

@@ -0,0 +1,323 @@
+"""Parse and patch Fusion GroupOperator .setting files.
+
+Fusion's .setting format is a Lua-like nested structure. Real-world group
+exports routinely contain InstanceInput blocks with nested UserControls /
+ControlGroup tables (>=2 levels of braces), so we cannot parse them with a
+flat regex. All structural scans here use balanced-brace matching.
+
+Public surface:
+  parse_setting_file(path, group_name=None) -> dict
+      Inspect a .setting file and return the published-input summary for a
+      named (or first) GroupOperator.
+
+  splice_inputs_block(source_path, template_path, dest_path,
+                      group_name=None) -> dict
+      Replace the `Inputs = ordered() { ... }` block of source_path with
+      the matching block from template_path and write to dest_path.
+      Returns a before/after diff summary.
+
+  default_backup_path(path) -> str
+      Generate a timestamped backup filename next to a target path.
+
+  FUSION_GROUP_GUARDRAILS, FUSION_COMMIT_CHECKLIST
+      Advisory text. Other modules may surface these on demand; this module
+      does not jam them into every return.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+
+FUSION_COMMIT_CHECKLIST: Tuple[str, ...] = (
+    "Open the Fusion page for the modified timeline item (or comp scope).",
+    "Select the group/macro node and nudge one published control so Resolve refreshes bindings.",
+    "Verify Edit-page controls respond (Text, Text Size, wrap, padding, corners).",
+    "Save the project (Ctrl+S / Cmd+S).",
+    "If InstanceInput order changed, confirm Edit Controls order in UI; LoadSettings may require manual UI 'Load Settings' on the group.",
+)
+
+FUSION_GROUP_GUARDRAILS: Tuple[str, ...] = (
+    "Do not call project_manager.load or switch projects mid Fusion edit — comp scope and undo stacks are lost.",
+    "Batch graph mutations: prefer bulk_set_inputs / bulk_set_expressions over many single-action calls.",
+    "InstanceInput remapping via LoadSettings may not refresh Edit-page control order until the group is selected and settings reloaded in Fusion UI.",
+    "Never delete a group via automation; group_settings_load only patches published inputs and inner settings.",
+    "After mutating a timeline-item Fusion comp, follow the commit checklist before expecting Edit-page updates.",
+)
+
+
+@dataclass
+class InstanceInputSummary:
+    slot: str
+    source_op: Optional[str] = None
+    source: Optional[str] = None
+    name: Optional[str] = None
+    max_scale: Optional[float] = None
+    default: Optional[str] = None
+    control_group: Optional[int] = None
+    raw_fields: Dict[str, Any] = field(default_factory=dict)
+
+
+# Used only to read shallow fields out of an InstanceInput body that we have
+# already isolated with balanced-brace scanning. We never use it to FIND the
+# bounds of a block.
+_FIELD_RE = re.compile(r'(\w+)\s*=\s*(?:"([^"]*)"|([\d.eE+-]+))')
+
+_INPUT_HEAD_RE = re.compile(r"(Input\d+)\s*=\s*InstanceInput\s*\{")
+
+
+def _find_balanced_brace(text: str, open_index: int) -> int:
+    """Return the index of the `}` that closes the `{` at open_index."""
+    depth = 0
+    for idx in range(open_index, len(text)):
+        ch = text[idx]
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return idx
+    raise ValueError("Unbalanced braces")
+
+
+def _iter_instance_input_blocks(inputs_inner: str) -> List[Tuple[str, str]]:
+    """Yield (slot, body) pairs by walking InstanceInput heads + balanced braces."""
+    blocks: List[Tuple[str, str]] = []
+    pos = 0
+    while True:
+        match = _INPUT_HEAD_RE.search(inputs_inner, pos)
+        if not match:
+            break
+        slot = match.group(1)
+        open_brace = match.end() - 1
+        try:
+            close_brace = _find_balanced_brace(inputs_inner, open_brace)
+        except ValueError:
+            break
+        body = inputs_inner[open_brace + 1 : close_brace]
+        blocks.append((slot, body))
+        pos = close_brace + 1
+    return blocks
+
+
+def _shallow_fields(body: str) -> Dict[str, Any]:
+    """Extract top-level `key = value` fields, skipping nested braces."""
+    fields: Dict[str, Any] = {}
+    i = 0
+    n = len(body)
+    while i < n:
+        ch = body[i]
+        if ch == "{":
+            try:
+                close = _find_balanced_brace(body, i)
+            except ValueError:
+                break
+            i = close + 1
+            continue
+        match = _FIELD_RE.match(body, i)
+        if match:
+            key, str_val, num_val = match.group(1), match.group(2), match.group(3)
+            if str_val is not None:
+                fields[key] = str_val
+            elif num_val is not None:
+                try:
+                    fields[key] = (
+                        float(num_val) if "." in num_val or "e" in num_val.lower() else int(num_val)
+                    )
+                except ValueError:
+                    fields[key] = num_val
+            i = match.end()
+        else:
+            i += 1
+    return fields
+
+
+def parse_instance_input_block(inputs_inner: str) -> List[InstanceInputSummary]:
+    summaries: List[InstanceInputSummary] = []
+    for slot, body in _iter_instance_input_blocks(inputs_inner):
+        fields = _shallow_fields(body)
+        max_scale = fields.get("MaxScale")
+        if isinstance(max_scale, (int, float)):
+            max_scale_f: Optional[float] = float(max_scale)
+        else:
+            max_scale_f = None
+        cg = fields.get("ControlGroup")
+        summaries.append(
+            InstanceInputSummary(
+                slot=slot,
+                source_op=fields.get("SourceOp"),
+                source=fields.get("Source"),
+                name=fields.get("Name"),
+                max_scale=max_scale_f,
+                default=str(fields["Default"]) if "Default" in fields else None,
+                control_group=int(cg) if isinstance(cg, int) else None,
+                raw_fields=fields,
+            )
+        )
+    summaries.sort(key=lambda row: _slot_key(row.slot))
+    return summaries
+
+
+def _slot_key(slot: str) -> int:
+    try:
+        return int(slot.replace("Input", ""))
+    except ValueError:
+        return 9999
+
+
+def _group_inputs_span(
+    content: str, group_name: Optional[str] = None
+) -> Tuple[int, int, str]:
+    """Return absolute (start, end_exclusive, inner) for the Inputs ordered block."""
+    if group_name:
+        pattern = re.compile(
+            rf"{re.escape(group_name)}\s*=\s*GroupOperator\s*\{{",
+            re.MULTILINE,
+        )
+        match = pattern.search(content)
+        if not match:
+            raise ValueError(f"GroupOperator {group_name!r} not found in .setting content")
+        group_open = match.end() - 1
+    else:
+        match = re.search(r"=\s*GroupOperator\s*\{", content)
+        if not match:
+            raise ValueError("No GroupOperator found in .setting content")
+        group_open = match.end() - 1
+
+    group_close = _find_balanced_brace(content, group_open)
+    group_body = content[group_open + 1 : group_close]
+    inputs_marker = re.search(r"Inputs\s*=\s*ordered\s*\(\s*\)\s*\{", group_body)
+    if not inputs_marker:
+        raise ValueError("GroupOperator has no Inputs = ordered() block")
+    abs_start = group_open + 1 + inputs_marker.start()
+    open_brace = group_open + 1 + inputs_marker.end() - 1
+    close_brace = _find_balanced_brace(content, open_brace)
+    replace_end = close_brace + 1
+    if replace_end < len(content) and content[replace_end] == ",":
+        replace_end += 1
+    return abs_start, replace_end, content[open_brace + 1 : close_brace]
+
+
+def parse_setting_file(path: str, group_name: Optional[str] = None) -> Dict[str, Any]:
+    with open(path, encoding="utf-8", errors="replace") as handle:
+        content = handle.read()
+    _, _, inner = _group_inputs_span(content, group_name=group_name)
+    inputs = parse_instance_input_block(inner)
+    return {
+        "path": os.path.abspath(path),
+        "published_inputs": [
+            {
+                "slot": row.slot,
+                "name": row.name,
+                "source_op": row.source_op,
+                "source": row.source,
+                "max_scale": row.max_scale,
+                "default": row.default,
+                "control_group": row.control_group,
+            }
+            for row in inputs
+        ],
+        "input_count": len(inputs),
+    }
+
+
+def _read_template_inputs_block(
+    template_path: str, group_name: Optional[str] = None
+) -> str:
+    """Pull the full `Inputs = ordered() { ... },` block from a .setting file."""
+    with open(template_path, encoding="utf-8", errors="replace") as handle:
+        content = handle.read()
+    start, end, _ = _group_inputs_span(content, group_name=group_name)
+    return content[start:end]
+
+
+def _summary_dict(row: Optional[InstanceInputSummary]) -> Optional[Dict[str, Any]]:
+    if row is None:
+        return None
+    return {
+        "source_op": row.source_op,
+        "source": row.source,
+        "name": row.name,
+        "max_scale": row.max_scale,
+        "control_group": row.control_group,
+    }
+
+
+def _diff_inputs(
+    before: List[InstanceInputSummary], after: List[InstanceInputSummary]
+) -> List[Dict[str, Any]]:
+    before_by_slot = {row.slot: row for row in before}
+    after_by_slot = {row.slot: row for row in after}
+    all_slots = sorted(set(before_by_slot) | set(after_by_slot), key=_slot_key)
+    diff: List[Dict[str, Any]] = []
+    for slot in all_slots:
+        b = before_by_slot.get(slot)
+        a = after_by_slot.get(slot)
+        if b is None:
+            diff.append({"slot": slot, "change": "added", "after": _summary_dict(a)})
+        elif a is None:
+            diff.append({"slot": slot, "change": "removed", "before": _summary_dict(b)})
+        elif _summary_dict(b) != _summary_dict(a):
+            diff.append(
+                {
+                    "slot": slot,
+                    "change": "modified",
+                    "before": _summary_dict(b),
+                    "after": _summary_dict(a),
+                }
+            )
+    return diff
+
+
+def splice_inputs_block(
+    source_path: str,
+    template_path: str,
+    dest_path: str,
+    *,
+    source_group_name: Optional[str] = None,
+    template_group_name: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Replace source's `Inputs = ordered() { ... }` with template's, write dest.
+
+    source_path: .setting whose published inputs you want to replace.
+    template_path: .setting whose Inputs block defines the desired layout.
+    dest_path: where to write the spliced result.
+
+    Returns a summary with input counts before/after and a per-slot diff.
+    """
+    with open(source_path, encoding="utf-8", errors="replace") as handle:
+        source_content = handle.read()
+    src_start, src_end, src_inner = _group_inputs_span(
+        source_content, group_name=source_group_name
+    )
+    before_inputs = parse_instance_input_block(src_inner)
+    template_block = _read_template_inputs_block(
+        template_path, group_name=template_group_name
+    )
+
+    new_content = source_content[:src_start] + template_block + source_content[src_end:]
+    _, _, new_inner = _group_inputs_span(new_content, group_name=source_group_name)
+    after_inputs = parse_instance_input_block(new_inner)
+
+    os.makedirs(os.path.dirname(os.path.abspath(dest_path)) or ".", exist_ok=True)
+    with open(dest_path, "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(new_content)
+
+    return {
+        "source_path": os.path.abspath(source_path),
+        "template_path": os.path.abspath(template_path),
+        "dest_path": os.path.abspath(dest_path),
+        "before_input_count": len(before_inputs),
+        "after_input_count": len(after_inputs),
+        "diff": _diff_inputs(before_inputs, after_inputs),
+    }
+
+
+def default_backup_path(base_path: str) -> str:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    root, ext = os.path.splitext(base_path)
+    return f"{root}.backup_{stamp}{ext or '.setting'}"