Framed transport + Claude‑friendly edit tools + live Unity NL test framework

.claude/prompts/nl-unity-claude-tests-mini.md

@@ -0,0 +1,45 @@
+# Unity NL Editing Suite — Natural Mode
+
+You are running inside CI for the **unity-mcp** repository. Your task is to demonstrate end‑to‑end **natural‑language code editing** on a representative Unity C# script using whatever capabilities and servers are already available in this session. Work autonomously. Do not ask the user for input. Do NOT spawn subagents, as they will not have access to the mcp server process on the top-level agent.
+
+## Mission
+1) **Discover capabilities.** Quietly inspect the tools and any connected servers that are available to you at session start. If the server offers a primer or capabilities resource, read it before acting.
+2) **Choose a target file.** Prefer `TestProjects/UnityMCPTests/Assets/Scripts/LongUnityScriptClaudeTest.cs` if it exists; otherwise choose a simple, safe C# script under `TestProjects/UnityMCPTests/Assets/`.
+3) **Perform a small set of realistic edits** using minimal, precise changes (not full-file rewrites). Examples of small edits you may choose from (pick 3–6 total):
+   - Insert a new, small helper method (e.g., a logger or counter) in a sensible location.
+   - Add a short anchor comment near a key method (e.g., above `Update()`), then add or modify a few lines nearby.
+   - Append an end‑of‑class utility method (e.g., formatting or clamping helper).
+   - Make a safe, localized tweak to an existing method body (e.g., add a guard or a simple accumulator).
+   - Optionally include one idempotency/no‑op check (re‑apply an edit and confirm nothing breaks).
+4) **Validate your edits.** Re‑read the modified regions and verify the changes exist, compile‑risk is low, and surrounding structure remains intact.
+5) **Report results.** Produce both:
+   - A JUnit XML at `reports/junit-nl-suite.xml` containing a single suite named `UnityMCP.NL` with one test case per sub‑test you executed (mark pass/fail and include helpful failure text).
+   - A summary markdown at `reports/junit-nl-suite.md` that explains what you attempted, what succeeded/failed, and any follow‑ups you would try.
+6) **Be gentle and reversible.** Prefer targeted, minimal edits; avoid wide refactors or non‑deterministic changes.
+
+## Assumptions & Hints (non‑prescriptive)
+- A Unity‑oriented MCP server is expected to be connected. If a server‑provided **primer/capabilities** resource exists, read it first. If no primer is available, infer capabilities from your visible tools in the session.
+- In CI/headless mode, when calling `mcp__unity__list_resources` or `mcp__unity__read_resource`, include:
+  - `ctx: {}`
+  - `project_root: "TestProjects/UnityMCPTests"` (the server will also accept the absolute path passed via env)
+  Example: `{ "ctx": {}, "under": "Assets/Scripts", "pattern": "*.cs", "project_root": "TestProjects/UnityMCPTests" }`
+- If the preferred file isn’t present, locate a fallback C# file with simple, local methods you can edit safely.
+- If a compile command is available in this environment, you may optionally trigger it; if not, rely on structural checks and localized validation.
+
+## Output Requirements (match NL suite conventions)
+- JUnit XML at `$JUNIT_OUT` if set, otherwise `reports/junit-nl-suite.xml`.
+  - Single suite named `UnityMCP.NL`, one `<testcase>` per sub‑test; include `<failure>` on errors.
+- Markdown at `$MD_OUT` if set, otherwise `reports/junit-nl-suite.md`.
+
+Constraints (for fast publishing):
+- Log allowed tools once as a single line: `AllowedTools: ...`.
+- For every edit: Read → Write (with precondition hash) → Re‑read; on `{status:"stale_file"}` retry once after re‑read.
+- Keep evidence to ±20–40 lines windows; cap unified diffs to 300 lines and note truncation.
+- End `<system-out>` with `VERDICT: PASS` or `VERDICT: FAIL`.
+
+## Guardrails
+- No destructive operations. Keep changes minimal and well‑scoped.
+- Don’t leak secrets or environment details beyond what’s needed in the reports.
+- Work without user interaction; do not prompt for approval mid‑flow.
+
+> If capabilities discovery fails, still produce the two reports that clearly explain why you could not proceed and what evidence you gathered.

.claude/prompts/nl-unity-suite-full.md

@@ -0,0 +1,133 @@
+# Unity NL/T Editing Suite — CI Agent Contract
+
+You are running inside CI for the `unity-mcp` repo. Use only the tools allowed by the workflow. Work autonomously; do not prompt the user. Do NOT spawn subagents.
+
+### Print this once, verbatim, early in the run
+AllowedTools: Write,Bash(printf:*),Bash(echo:*),Bash(scripts/nlt-revert.sh:*),mcp__unity__manage_editor,mcp__unity__list_resources,mcp__unity__read_resource,mcp__unity__apply_text_edits,mcp__unity__script_apply_edits,mcp__unity__validate_script,mcp__unity__find_in_file,mcp__unity__read_console
+
+---
+
+## Mission
+1) Pick target file (prefer):
+   - `unity://path/Assets/Scripts/LongUnityScriptClaudeTest.cs`
+2) Execute **all** NL/T tests in order using minimal, precise edits.
+3) Validate each edit with `mcp__unity__validate_script(level:"standard")`.
+4) **Report**: write one `<testcase>` XML fragment per test to `reports/<TESTID>_results.xml`. Do **not** read or edit `$JUNIT_OUT`.
+5) **Restore** the file after each test using the OS‑level helper (fast), not a full‑file text write.
+
+---
+
+## Environment & Paths (CI)
+- Always pass: `project_root: "TestProjects/UnityMCPTests"` and `ctx: {}` on list/read/edit/validate.
+- **Canonical URIs only**:
+  - Primary: `unity://path/Assets/...` (never embed `project_root` in the URI)
+  - Relative (when supported): `Assets/...`
+- File paths for the helper script are workspace‑relative:
+  - `TestProjects/UnityMCPTests/Assets/...`
+
+CI provides:
+- `$JUNIT_OUT=reports/junit-nl-suite.xml` (pre‑created; leave alone)
+- `$MD_OUT=reports/junit-nl-suite.md` (synthesized from JUnit)
+- Helper script: `scripts/nlt-revert.sh` (snapshot/restore)
+
+---
+
+## Tool Mapping
+- **Anchors/regex/structured**: `mcp__unity__script_apply_edits`
+- **Precise ranges / atomic batch**: `mcp__unity__apply_text_edits` (non‑overlapping ranges)
+- **Validation**: `mcp__unity__validate_script(level:"standard")`
+- **Reporting**: `Write` small XML fragments to `reports/*_results.xml`
+- **Snapshot/Restore**: `Bash(scripts/nlt-revert.sh:*)`
+
+> Don’t use `mcp__unity__create_script`. Avoid the header/`using` region entirely.
+
+---
+### Structured edit ops (required usage)
+- For method insertion anchored after `GetCurrentTarget`: use `script_apply_edits` with `{"op":"anchor_insert", "afterMethodName":"GetCurrentTarget", "text": "<code>"}`
+- To delete the temporary helper (T‑A/T‑E): **do not** use `anchor_replace`. Prefer:
+  1) `script_apply_edits` with `{"op":"regex_replace", "pattern":"(?s)^\\s*private\\s+int\\s+__TempHelper\\s*\\(.*?\\)\\s*=>\\s*.*?;\\s*\\r?\\n", "replacement":""}`
+  2) If that returns `missing_field` or `bad_request`, fallback to `apply_text_edits` with a single `replace_range` computed from the method’s start/end offsets (found by scanning braces).
+- If any write returns `missing_field`, `bad_request`, or `unsupported`: **write the testcase fragment anyway** with the error in `<failure>`, mark `VERDICT: FAIL`, then **restore** and proceed to the next test.
+- Never call generic Bash like `mkdir`; the revert helper creates needed directories. Do not attempt directory creation; use only `scripts/nlt-revert.sh` for snapshot/restore.
+
+
+## Output Rules (JUnit fragments only)
+- For each test, create **one** file: `reports/<TESTID>_results.xml` containing exactly a single `<testcase ...> ... </testcase>`.
+- Put human‑readable lines (PLAN/PROGRESS/evidence) **inside** `<system-out><![CDATA[ ... ]]></system-out>`.
+- Evidence windows only (±20–40 lines). If showing a unified diff, cap at 100 lines and note truncation.
+- **Never** open/patch `$JUNIT_OUT` or `$MD_OUT`; CI merges fragments and synthesizes Markdown.
+
+**Example fragment**
+```xml
+<testcase classname="UnityMCP.NL-T" name="NL-1. Method replace/insert/delete">
+  <system-out><![CDATA[
+PLAN: NL-0,NL-1,NL-2,NL-3,NL-4,T-A,T-B,T-C,T-D,T-E,T-F,T-G,T-H,T-I,T-J (len=15)
+PROGRESS: 2/15 completed
+pre_sha=<...>
+... evidence windows ...
+VERDICT: PASS
+]]></system-out>
+</testcase>
+
+```
+
+Note: Emit the PLAN line only in NL‑0 (do not repeat it for later tests or later `<system-out>` blocks).
+
+
+### Fast Restore Strategy (OS‑level)
+
+- Snapshot once at NL‑0, then restore after each test via the helper.
+- Snapshot (once after confirming the target):
+  ```bash
+  scripts/nlt-revert.sh snapshot "TestProjects/UnityMCPTests/Assets/Scripts/LongUnityScriptClaudeTest.cs" "reports/_snapshots/LongUnityScriptClaudeTest.cs.baseline"
+  ```
+- Log `snapshot_sha=...` printed by the script.
+- Restore (after each mutating test):
+  ```bash
+  scripts/nlt-revert.sh restore "TestProjects/UnityMCPTests/Assets/Scripts/LongUnityScriptClaudeTest.cs" "reports/_snapshots/LongUnityScriptClaudeTest.cs.baseline"
+  ```
+- Then `read_resource` to confirm and (optionally) `validate_script(level:"standard")`.
+- The helper creates parent directories for the snapshot path if missing.
+- If the helper fails: fall back once to a guarded full‑file restore using the baseline bytes; then continue.
+
+### Guarded Write Pattern (for edits, not restores)
+
+- Before any mutation:
+  - Call `mcp__unity__read_resource(uri, project_root, ctx)` and set `buf = res.text` and `pre_sha = res.sha256` (server‑computed over raw on‑disk bytes).
+- Write with `precondition_sha256 = pre_sha`.
+- On `{status:"stale_file"}`:
+  - Retry once using a server hash (`data.current_sha256` or `data.expected_sha256`) if present.
+  - Otherwise perform one `read_resource(...)` to refresh `pre_sha` and retry. No loops.
+- After success:
+  - Prefer not to re‑read. Update `buf` locally; refresh `pre_sha = mcp__unity__read_resource(...).sha256` only when the next step requires exact on‑disk sync (validation, anchor recompute) or before leaving the test.
+- Prefer anchors (`script_apply_edits`) for end‑of‑class / above‑method insertions. Keep edits inside method bodies. Avoid header/using.
+
+### Execution Order (fixed)
+
+- Run exactly: NL-0, NL-1, NL-2, NL-3, NL-4, T-A, T-B, T-C, T-D, T-E, T-F, T-G, T-H, T-I, T-J (15 total).
+- NL‑0 must include the PLAN line (len=15).
+- After each testcase, include `PROGRESS: <k>/15 completed`.
+
+### Test Specs (concise)
+
+- NL‑0. Sanity reads — Tail ~120; ±40 around `Update()`. Then snapshot via helper.
+- NL‑1. Replace/insert/delete — `HasTarget → return currentTarget != null;`; insert `PrintSeries()` after `GetCurrentTarget` logging "1,2,3"; verify; delete `PrintSeries()`; restore.
+- NL‑2. Anchor comment — Insert `// Build marker OK` above `public void Update(...)`; restore.
+- NL‑3. End‑of‑class — Insert `// Tail test A/B/C` (3 lines) before final brace; restore.
+- NL‑4. Compile trigger — Record INFO only.
+
+- T‑A. Anchor insert (text path) — Insert helper after `GetCurrentTarget`; verify; delete via `regex_replace`; restore.
+- T‑B. Replace body — Single `replace_range` inside `HasTarget`; restore.
+- T‑C. Header/region preservation — Edit interior of `ApplyBlend`; preserve signature/docs/regions; restore.
+- T‑D. End‑of‑class (anchor) — Insert helper before final brace; remove; restore.
+- T‑E. Lifecycle — Insert → update → delete via regex; restore.
+- T‑F. Atomic batch — One call: two small `replace_range` + one end‑of‑class comment; all‑or‑nothing; restore.
+- T‑G. Path normalization — Same edit with `unity://path/Assets/...` then `Assets/...`; second returns `{status:"no_change"}`.
+- T‑H. Validation — `standard` after edits; `basic` only for transient checks.
+- T‑I. Failure surfaces — Record INFO on `{too_large}`, `{stale_file}`, overlap rejection, validation failure, `{using_guard}`.
+- T‑J. Idempotency — Repeat `replace_range` → `{status:"no_change"}`; repeat delete → no‑op.
+
+### Status & Reporting
+
+- Safeguard statuses are non‑fatal; record and continue.
+- End each testcase `<system-out>` with `VERDICT: PASS` or `VERDICT: FAIL`.