refactor(tests): derive the two duplicated test helpers into tests/helpers.py (#4276)

Derive-first, ahead of the tests shape pay-down. An AST pass over all 2628
definitions under `tests/` found exactly three helper bodies duplicated
across files. Two are real copies and are consolidated here; the third is
not, and is left alone.

`need_tools(*tools)` — byte-identical in three hook-test modules, each
skipping when `jq`/`awk`/`git` is absent from PATH. Now snippet #4277. The
`import shutil` each file carried existed only to serve it and goes with it.

`rule_row(rule_id)` — byte-identical in two integration modules, reading a
Rule back through a SEPARATE session so the assertion is about what Postgres
holds rather than what the writing session's identity map remembers. Now
snippet #4278. Its imports are lazy, because `tests/helpers.py` is imported
by unit tests that have no database, which is the same reason
`plugin_config` defers its service imports.

NOT consolidated: `_side(uid, k, d="")` in test_services_plugin_context and
test_write_path_trigger. The body is identical but it closes over a
module-local `stored` dict, so it is not self-contained and "moving" it
would mean inventing a parameter neither call site wants. That is convention
plumbing — two tests independently writing the same one-line side_effect —
and it is dismissed in the ledger rather than lifted.

Worth recording for the next pass: a repeated NAME is not a family. `_row`
is defined in five modules and only two of those share a body; the other
three (test_list_rows_brief, test_calibration_stamp, test_shape_ledger)
build entirely different objects. Grouping by name would have consolidated
three things that have nothing in common.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

tests/test_hook_json_reader.py

@@ -22,25 +22,20 @@ from __future__ import annotations
 
 import json
 import re
-import shutil
 import subprocess
 from pathlib import Path
 from urllib.parse import quote
 
 import pytest
 
+from tests.helpers import need_tools
+
 HOOKS = Path(__file__).resolve().parents[1] / "plugin" / "hooks"
 DEFS = HOOKS / "scribe_defs.sh"
 PARSER = HOOKS / "scribe_json.awk"
 TURN = HOOKS / "scribe_turn.awk"
 
 
-def _need(*tools):
-    for t in tools:
-        if shutil.which(t) is None:
-            pytest.skip(f"hook runtime tool {t!r} not installed")
-
-
 def sh(script: str, stdin: str = "") -> str:
     """Run a snippet with scribe_defs.sh sourced, under the hooks' own flags.
 
@@ -50,7 +45,7 @@ def sh(script: str, stdin: str = "") -> str:
     quietly normalise the characters it exists to check: the first version of
     this file did, and reported a round-trip failure that was entirely its own.
     """
-    _need("bash", "awk")
+    need_tools("bash", "awk")
     r = subprocess.run(
         ["bash", "-c", f'set -uo pipefail\n. "{DEFS}"\n{script}'],
         input=stdin.encode(), capture_output=True,
@@ -60,7 +55,7 @@ def sh(script: str, stdin: str = "") -> str:
 
 
 def flat(doc: str, mode: str = "whole") -> list[tuple[str, str, str]]:
-    _need("awk")
+    need_tools("awk")
     r = subprocess.run(["awk", "-v", f"mode={mode}", "-f", str(PARSER)],
                        input=doc.encode(), capture_output=True)
     assert r.returncode == 0, r.stderr.decode()
@@ -260,7 +255,7 @@ def test_urlenc_and_the_envelope_can_fail():
 # The transcript turn, which is the largest thing jq was doing here.
 
 def _turn(records: list[dict]) -> dict:
-    _need("awk")
+    need_tools("awk")
     doc = "\n".join(json.dumps(r) for r in records) + "\n"
     p1 = subprocess.run(["awk", "-v", "mode=lines", "-f", str(PARSER)],
                         input=doc, capture_output=True, text=True)