From 7f1750df0e8c96e06ee63e6d96dc020fc3568c5d Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sun, 12 Jul 2026 17:35:02 -0400 Subject: [PATCH] purge-test-data: mock pollution housekeeping as a skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit meshterm --mock writes to the real ~/.meshterm database, so simulator sessions leave fake nodes (Alice, hub-1, hopN hashes, a1b2c3d4… keys) in the history behind the atlas, dashboard, and trace suggestions. The new skill (runs on the cheap model, like commit/verify) backs the DB up, deletes exactly the MockDevice-fingerprinted rows — deliberately conservative: no short-hash matching, background run rows untouched — and verifies a clean second pass. The verify skill now names it as the mandatory last step after any mock run. Co-Authored-By: Claude Fable 5 --- .claude/skills/purge-test-data/SKILL.md | 51 +++++++++ .claude/skills/purge-test-data/purge.py | 141 ++++++++++++++++++++++++ .claude/skills/verify/SKILL.md | 3 + 3 files changed, 195 insertions(+) create mode 100644 .claude/skills/purge-test-data/SKILL.md create mode 100644 .claude/skills/purge-test-data/purge.py diff --git a/.claude/skills/purge-test-data/SKILL.md b/.claude/skills/purge-test-data/SKILL.md new file mode 100644 index 0000000..0540bea --- /dev/null +++ b/.claude/skills/purge-test-data/SKILL.md @@ -0,0 +1,51 @@ +--- +name: purge-test-data +description: Purge simulator/mock node pollution from the default MeshTerm database. Run after any --mock CLI session or simulator test drive, and whenever fake nodes (Alice, Yagi-Repeater, hub-1, hopN hashes, a1b2c3d4… keys) show up in the atlas, dashboard, or trace history. +model: haiku +--- + +# Purging test data from the MeshTerm database + +`meshterm --mock` and simulator test drives write to the **real** default +database (`~/.meshterm/meshterm.db`), polluting the history that feeds the +atlas, dashboard, and trace suggestions. This skill removes exactly the rows +carrying the simulator's fingerprints and nothing else. + +## Run + +``` +$DEV_VENV_PYTHON .claude\skills\purge-test-data\purge.py --dry-run +$DEV_VENV_PYTHON .claude\skills\purge-test-data\purge.py +``` + +- Always `--dry-run` first and sanity-check the counts (real-session tables + should mostly report 0; a huge observations count is a red flag — stop and + investigate before deleting). +- The real run writes a timestamped `meshterm.db.bak-…` next to the database + before touching anything, then VACUUMs. +- Note: `--dry-run` can under-report `runs` — run rows are only deletable once + their child traces are actually gone, so the real pass may delete more. +- Finish with a second `--dry-run`: every count should be 0. + +## What counts as test data + +The `MockDevice` identities in `meshterm/core/connection.py` — keep +`purge.py`'s `MOCK_PREFIXES` / `MOCK_NAMES` in sync if the simulator grows new +nodes: + +- key prefixes `a1b2c3d4`, `b2c3d4e5`, `c3d4e5f6`, `d4e5f6a7`, and the all-zero + mock self key +- names `Yagi-Repeater`, `Local-Repeater`, `Observer-Bot`, `Alice`, + `MockCompanion`, plus demo targets `hub-1`, `relay-1`, `relay-2` +- the `hopN` placeholder hop hashes only the simulator emits + +Deliberately conservative: short hops (e.g. a real `a1` traced at 1-byte +width) never match, and background monitor/chat run rows are left alone — a +stray narrow mock hop left behind is better than a purged real row. + +## When to run + +After **any** work that launched `meshterm --mock` (the verify skill's first +stop) or exercised `MockDevice` against the default database. Do it in the +same session, before handing back to the user — fake nodes in the atlas on +real hardware are exactly what this prevents. diff --git a/.claude/skills/purge-test-data/purge.py b/.claude/skills/purge-test-data/purge.py new file mode 100644 index 0000000..1dc40d5 --- /dev/null +++ b/.claude/skills/purge-test-data/purge.py @@ -0,0 +1,141 @@ +"""Purge simulator/test pollution from the default MeshTerm database. + +``meshterm --mock`` (and headless test drives against the simulator) write to the +same ``~/.meshterm/meshterm.db`` as real radio sessions, so mock nodes leak into +the history that powers the atlas, the dashboard, and the trace suggestions. This +script removes exactly the rows carrying the simulator's fingerprints — the +:class:`MockDevice` identities in ``meshterm/core/connection.py`` — and nothing +else. Real rows never match: the fingerprints are fixed synthetic keys, the +``hopN`` placeholder hashes only the simulator emits, and the mock contact names. + +A timestamped ``.bak`` copy of the database is written first; ``--dry-run`` only +reports what would go. +""" + +from __future__ import annotations + +import argparse +import shutil +import sqlite3 +from datetime import datetime +from pathlib import Path + +DB = Path.home() / ".meshterm" / "meshterm.db" + +#: The simulator's key prefixes: its four contacts and its all-zero self key. +#: Kept in sync with MockDevice in meshterm/core/connection.py. Eight hex digits +#: each — long enough that no real key plausibly collides. +MOCK_PREFIXES = ("a1b2c3d4", "b2c3d4e5", "c3d4e5f6", "d4e5f6a7", "00000000") + +#: The simulator's display names (contacts, its own node, and demo trace targets). +MOCK_NAMES = ( + "Yagi-Repeater", "Local-Repeater", "Observer-Bot", "Alice", "MockCompanion", + "hub-1", "relay-1", "relay-2", +) + + +def _mock_hash(value: str | None) -> bool: + """Whether a stored hash/prefix carries a simulator fingerprint. + + Matches only the unmistakable forms — the ``hopN`` placeholders and hashes + carrying a full 8-hex mock prefix. A short real hop (``a1`` traced at 1-byte + width) must never match, so no reverse-prefix matching: a stray narrow mock + hop left behind is better than a purged real one. + """ + if not value: + return False + value = value.lower().removeprefix("0x") + return value.startswith("hop") or any(value.startswith(p) for p in MOCK_PREFIXES) + + +def purge(db: Path, *, dry_run: bool) -> dict[str, int]: + """Delete every mock-fingerprinted row; returns per-table deletion counts.""" + con = sqlite3.connect(db) + con.execute("PRAGMA foreign_keys = ON") + cur = con.cursor() + counts: dict[str, int] = {} + + def delete(table: str, where: str, params: tuple = ()) -> None: + n = cur.execute( + f"SELECT COUNT(*) FROM {table} WHERE {where}", params + ).fetchone()[0] + counts[table] = counts.get(table, 0) + n + if not dry_run and n: + cur.execute(f"DELETE FROM {table} WHERE {where}", params) + + names = ",".join("?" for _ in MOCK_NAMES) + + # Traces: any trace that walked a mock hop, or targeted a mock name. + hop_rows = cur.execute("SELECT DISTINCT trace_id, node FROM trace_hops").fetchall() + mock_traces = {tid for tid, node in hop_rows if _mock_hash(node)} + target_rows = cur.execute(f"SELECT id FROM traces WHERE target IN ({names})", + MOCK_NAMES).fetchall() + mock_traces |= {tid for (tid,) in target_rows} + if mock_traces: + ids = ",".join(str(t) for t in mock_traces) + delete("trace_hops", f"trace_id IN ({ids})") + delete("traces", f"id IN ({ids})") + else: + counts.setdefault("trace_hops", 0) + counts.setdefault("traces", 0) + + # Observations and messages carrying a mock node or name. + obs = cur.execute("SELECT id, node, name FROM observations").fetchall() + mock_obs = [oid for oid, node, name in obs + if _mock_hash(node) or (name in MOCK_NAMES)] + delete("observations", f"id IN ({','.join(map(str, mock_obs)) or '0'})") + msgs = cur.execute("SELECT id, peer, peer_name FROM messages").fetchall() + mock_msgs = [mid for mid, peer, peer_name in msgs + if _mock_hash(peer) or (peer_name in MOCK_NAMES)] + delete("messages", f"id IN ({','.join(map(str, mock_msgs)) or '0'})") + + # Sweep tooling under mock targets/identities. + delete("tx_samples", f"target IN ({names})", MOCK_NAMES) + delete("path_candidates", f"target IN ({names})", MOCK_NAMES) + nbr = cur.execute("SELECT id, repeater, neighbour FROM neighbour_reports").fetchall() + mock_nbr = [nid for nid, rep, ngh in nbr if _mock_hash(rep) or _mock_hash(ngh)] + delete("neighbour_reports", f"id IN ({','.join(map(str, mock_nbr)) or '0'})") + + # Runs that now hold nothing and were mock-shaped to begin with: trace runs on + # mock targets/specs. Background monitor/chat run rows are left alone — they + # are session bookkeeping shared with real use, and empty ones are harmless. + delete( + "runs", + "tool = 'trace'" + f" AND json_extract(args_json, '$.target') IN ({names})" + " AND id NOT IN (SELECT run_id FROM traces)" + " AND id NOT IN (SELECT run_id FROM path_candidates)", + MOCK_NAMES, + ) + + if not dry_run: + con.commit() + cur.execute("VACUUM") + con.close() + return counts + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--dry-run", action="store_true", + help="report what would be deleted, touch nothing") + parser.add_argument("--db", type=Path, default=DB, help="database path") + args = parser.parse_args() + + if not args.db.exists(): + print(f"no database at {args.db} — nothing to do") + return + if not args.dry_run: + stamp = datetime.now().strftime("%Y%m%d-%H%M%S") + backup = args.db.with_name(f"{args.db.name}.bak-{stamp}") + shutil.copy2(args.db, backup) + print(f"backup: {backup}") + + counts = purge(args.db, dry_run=args.dry_run) + verb = "would delete" if args.dry_run else "deleted" + for table in sorted(counts): + print(f"{verb} {counts[table]:>5} {table}") + + +if __name__ == "__main__": + main() diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md index 39687b5..5debe7c 100644 --- a/.claude/skills/verify/SKILL.md +++ b/.claude/skills/verify/SKILL.md @@ -33,3 +33,6 @@ model: haiku the default) block until Ctrl-C — always pass an explicit `--seconds N`. - INFO log lines (event hub / monitor) print to the console in CLI mode; that's normal outside the full-screen session. +- **Housekeeping is part of verifying**: every `--mock` run pollutes the real + database with fake nodes. When the mock runs are done, run the + `purge-test-data` skill before handing back.