@r1z4x/tezgah 1.0.0

package/hooks/tezgah_apps.py

@@ -0,0 +1,266 @@
+"""The browser and mobile app-analysis MCP servers tezgah wires into each host.
+
+One source of truth: one row per feature in `REGISTRY`. tezgah-setup renders the
+rows a selection enables into opencode.json, Codex config.toml, Cursor mcp.json,
+omp's mcp.json and the dsh patch, so the per-host configs cannot drift; Claude
+reads the `.mcp.json` at the plugin root, which the installer renders from the
+same rows. A row carries the vendor command and env of its server, the `default`
+state a config without a `features` key means, and the `dep` it cannot start
+without - so what is wired, what is installed and what is reported all answer
+from one key.
+
+Both servers drive the app from its accessibility / DOM / native view tree, so
+an analysis run does not need a screenshot per step; a screenshot is an
+explicit, on-demand action. The browser profile is isolated by default - the
+user's real Chrome is only reached by a deliberate attach, never automatically.
+
+Nothing here is installed by tezgah: the commands run through `npx`, which is
+present wherever node is (the dsh host and its status line already need it).
+"""
+import os
+import sys
+
+HOME = os.path.expanduser("~")
+
+# Where screenshots, traces and tree dumps land. The agent gets a path back;
+# image bytes are never inlined into the prompt.
+ARTIFACTS = os.environ.get("TEZGAH_ARTIFACTS") or os.path.join(
+    os.environ.get("XDG_CACHE_HOME") or os.path.join(HOME, ".cache"),
+    "tezgah", "apps")
+
+# Pinned on purpose. A floating tag (`@latest`) makes every session start fetch
+# whatever is current on the registry and run it with the agent's privileges -
+# a supply-chain defect a 2,660-harness study found in 9.8% of committed agent
+# configurations ("Scanning the Harness", arXiv 2609.07360). Bump these
+# deliberately, not implicitly.
+# Playwright MCP exposes core tools only unless capabilities are named, and the
+# caps are exactly what a product audit needs: `testing` turns a UX claim into a
+# re-runnable assertion (browser_verify_*), `storage` reaches a logged-in surface
+# by saving and restoring a state file instead of attaching to the user's real
+# Chrome, and `network` sets the offline state and mocks a failure - the two
+# states a mobile-first product is judged on. `devtools` (traces, video) stays
+# off: the opt-in chrome-devtools sidecar owns perf and deep network, and a
+# second copy of it would only widen the tool list.
+_PLAYWRIGHT = ["npx", "-y", "@playwright/mcp@0.0.81", "--isolated",
+               "--caps=testing,storage,network"]
+_CHROME_DEVTOOLS = ["npx", "-y", "chrome-devtools-mcp@1.9.0", "--isolated",
+                    "--no-usage-statistics"]
+_MOBILE = ["npx", "-y", "@mobilenext/mobile-mcp@1.0.4"]
+
+# The browser build the playwright row launches, installed by the same Playwright
+# version that server ships: `@playwright/mcp@0.0.81` declares
+# `playwright@1.64.0-alpha-2026-09-14` as its own dependency (read from its
+# published package.json), and a browser cache written by another version can be
+# the wrong revision for it. Bumping `_PLAYWRIGHT` means bumping this with it.
+_PW_BROWSERS = ["npx", "-y", "playwright@1.64.0-alpha-2026-09-14",
+                "install", "chromium"]
+
+
+# ------------------------------------------------------------------- probes ---
+# Each probe answers "can this feature start?", not "is it wired": the wiring is
+# tezgah's own file and the report reads that separately. They are called only
+# when a feature's state is asked for, so `shutil` and `tezgah_paths` are
+# imported here rather than at module level - this module is a leaf the
+# installer imports on every host.
+
+def _which(name):
+    import shutil
+    return shutil.which(name)
+
+
+def _tp(attr):
+    import tezgah_paths
+    return getattr(tezgah_paths, attr)
+
+
+def _browser_caches():
+    """Every directory Playwright itself would look in, in its own order.
+
+    `PLAYWRIGHT_BROWSERS_PATH=0` means "beside the package", which for an
+    npx-fetched server is inside the npx cache; the probe treats it as any other
+    miss instead of guessing a path there."""
+    local = os.environ.get("LOCALAPPDATA")
+    return tuple(p for p in (
+        os.environ.get("PLAYWRIGHT_BROWSERS_PATH"),
+        os.path.join(HOME, "Library", "Caches", "ms-playwright"),
+        os.path.join(HOME, ".cache", "ms-playwright"),
+        os.path.join(local, "ms-playwright") if local else None,
+    ) if p)
+
+
+def _playwright_browsers():
+    """A browser cache holding a build, or None.
+
+    The server launches a browser on its first tool call, so one wired without a
+    build fails there instead of at install time - which is what the probe is
+    for. Any build counts: the row's own pin decides which one."""
+    for d in _browser_caches():
+        try:
+            found = sorted(e for e in os.listdir(d)
+                           if e.startswith(("chromium", "firefox", "webkit")))
+        except OSError:
+            continue
+        if found:
+            return os.path.join(d, found[0])
+    return None
+
+
+def _probe_playwright():
+    """`npx` to start the server, and a browser build for it to launch."""
+    if not _which("npx"):
+        return None
+    return _playwright_browsers()
+
+
+def _probe_device_toolchain():
+    """`adb` (Android platform tools) or `xcrun` (macOS, whose simulator
+    services arrive with Xcode). Either one drives a device the native tree is
+    read from; no server here can start a device itself."""
+    return _which("adb") or _which("xcrun")
+
+
+def _probe_npx():
+    return _which("npx")
+
+
+def _probe_orx():
+    return _tp("orx_bin")()
+
+
+# The fetch-and-convert step of an embedding row, run by the installer as its
+# `cmd`, and the probe that answers whether the pinned file is in place.
+_EMBED = os.path.join(os.path.dirname(os.path.abspath(__file__)), "tezgah_embed.py")
+
+
+def _embed():
+    import tezgah_embed
+    return tezgah_embed
+
+
+def _embed_row(ident, name, model):
+    return {"id": ident, "name": name,
+            "why": "lessons and docs ranked by meaning as well as words (%s)" % model,
+            "command": None, "env": None, "default": False,
+            # removed by --disable: the file is tezgah's own, not a tool the
+            # user may want for something else
+            "remove": lambda: _embed().remove(ident),
+            "dep": {"name": ident, "probe": lambda: _embed().valid(ident),
+                    "needs": (sys.executable,),
+                    "cmd": [sys.executable, _EMBED, "fetch", ident],
+                    "why": "the converted model file under ~/.cache/tezgah/embed "
+                           "(missing, or not the pinned sha256)"}}
+
+
+# ----------------------------------------------------------------- registry ---
+# One row per feature id. `command`/`env` are the server spec, so a row without
+# a `command` is a feature with no host file to write (nothing iterates those
+# into a host config - `servers()` is the accessor that filters them). `dep` is
+# the runtime the feature cannot start without, in the shape the installer's own
+# `DEPS` table uses: `probe` answers whether it is there, `needs` names the
+# tools its `cmd` requires on PATH, `cmd` is the vendor's own installer, and a
+# `cmd` of None is a dependency with no unattended installer to name - the
+# probe still fails honestly instead of wiring a server whose runtime is absent.
+REGISTRY = (
+    {"id": "mcp-playwright",
+     "name": "playwright",
+     "why": "web app analysis from the accessibility tree",
+     "command": _PLAYWRIGHT,
+     "env": {"PLAYWRIGHT_MCP_OUTPUT_DIR": ARTIFACTS},
+     "default": True,
+     "dep": {"name": "playwright-browsers", "probe": _probe_playwright,
+             "needs": ("npx",), "cmd": _PW_BROWSERS,
+             "why": "the browser it launches on its first tool call"}},
+    {"id": "mcp-mobile-mcp",
+     "name": "mobile-mcp",
+     "why": "iOS Simulator / Android emulator from the native tree",
+     "command": _MOBILE,
+     "env": {"MOBILEMCP_DISABLE_TELEMETRY": "1"},
+     "default": True,
+     "dep": {"name": "device-toolchain", "probe": _probe_device_toolchain,
+             "needs": (),
+             # Neither channel is an unattended vendor installer: Xcode comes
+             # from the App Store, the Android SDK from its own manager.
+             "cmd": None,
+             "why": "adb or Xcode's simulator services, for the device it drives"}},
+    # Opt-in (`--enable mcp-chrome-devtools`, or `--devtools`): perf traces, deep
+    # network and source-mapped console. Playwright's tree snapshot is the
+    # analysis default; this is the diagnostic sidecar the second opinion
+    # recommended keeping separate.
+    {"id": "mcp-chrome-devtools",
+     "name": "chrome-devtools",
+     "why": "web perf traces, deep network and source-mapped console",
+     "command": _CHROME_DEVTOOLS,
+     "env": {},
+     "default": False,
+     "dep": {"name": "npx", "probe": _probe_npx, "needs": (),
+             # The package itself is fetched by npx on demand, and node has no
+             # unattended vendor installer to name here.
+             "cmd": None,
+             "why": "node, which npx runs the server through"}},
+    # Not a server: the OpenResearch CLI the research routing shells out to.
+    # Same dep record the installer's DEPS table carries for it.
+    {"id": "orx",
+     "name": "orx",
+     "why": "research routing (OpenResearch)",
+     "command": None,
+     "env": None,
+     "default": True,
+     "dep": {"name": "orx", "probe": _probe_orx, "needs": ("curl", "sh"),
+             "cmd": ["sh", "-c",
+                     "curl -LsSf https://openresearch.sh/install.sh | sh"],
+             "why": "research routing (OpenResearch)"}},
+    # Opt-in, not servers: a static embedding model fused with BM25 for the
+    # per-turn lessons and the docs fallback (hooks/tezgah_embed.py). Enabling
+    # one fetches and converts its pinned file; the first selected one is used.
+    _embed_row("embed-mrl", "embed-mrl",
+               "static-similarity-mrl-multilingual-v1, 128 dims, "
+               "~436 MB download, 15 MB file"),
+    _embed_row("embed-m2v", "embed-m2v",
+               "potion-multilingual-128M, PCA-128, ~531 MB download, 42 MB file"),
+)
+
+IDS = tuple(r["id"] for r in REGISTRY)
+# Every id that carries a server, i.e. every name tezgah may have written into a
+# host file. Uninstall reads this (`names(MCP_IDS)`), never a disable: a feature
+# that is off today still has to be swept from a file an older release wrote.
+MCP_IDS = tuple(r["id"] for r in REGISTRY if r["command"])
+
+
+def defaults():
+    """The ids a config with no `features` key means.
+
+    Declared per row, never inferred from what is installed or from how the
+    registry is ordered, so a config.json written before that key existed keeps
+    exactly the wiring it had."""
+    return tuple(r["id"] for r in REGISTRY if r["default"])
+
+
+def selected_ids(selected=None):
+    """`selected` normalised to registry order.
+
+    `None` means the declared defaults - an absent key is not "none". An id this
+    registry does not know is dropped rather than raising, so a selection an
+    older release wrote cannot break a host writer; `--features` is where an
+    unknown id is reported."""
+    if selected is None:
+        return defaults()
+    if isinstance(selected, (bool, str)):
+        # A bool is the `devtools` argument this signature replaced and a string
+        # is iterable, so either one left at a call site would answer with the
+        # wrong set - or, for the bool, with an unreadable "not iterable" from
+        # `set()`. Name the argument the caller has to give instead.
+        raise TypeError("selected is a list of feature ids, not %s"
+                        % type(selected).__name__)
+    wanted = set(selected)
+    return tuple(r["id"] for r in REGISTRY if r["id"] in wanted)
+
+
+def servers(selected=None):
+    """The enabled rows that carry a server, in registry order."""
+    on = set(selected_ids(selected))
+    return tuple(r for r in REGISTRY if r["id"] in on and r["command"])
+
+
+def names(selected=None):
+    """The server names of `servers(selected)`."""
+    return [r["name"] for r in servers(selected)]

package/hooks/tezgah_attest.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Runtime attestation: are tezgah's own hook entries armed and unchanged?
+
+`tezgah-setup --report` reads what an install WROTE, and `--report --live` proves
+the hooks EXECUTE, but both run only when someone asks. This is the per-session
+half: every host's session start compares the hook entries tezgah owns with what
+the install recorded, writes one `attest` row, and keeps a drift mark the status
+line and the Stop rule's claim row read.
+
+One store, not two: the install record is the per-artifact sha file the contract
+artifacts already use (`contract.sha256`, `bin/tezgah-setup::record_contract`),
+one line per entry under a `hook:<host>:<entry>` key. An entry is one hook event's
+tezgah-owned groups (Claude, dsh, Codex, Cursor - so a removed PreToolUse is named
+while PostToolUse stays), opencode's plugin links, and nothing for omp: its bridge
+is compared to a fresh render, the way `rules_current` compares a rules file. The
+code an entry runs is hashed only on a packaged install (a tree with no `.git`):
+a checkout install points into a tree its owner edits on purpose. A hook file
+any user can write (0666) is drift too; group write is left alone, because a
+umask of 002 (user-private groups) gives every file that.
+
+Drift is evidence, never integrity: the same uid that could edit a hook can edit
+the record. It is never a Stop block, and its text never tells the model what to
+run - the user reads it and decides.
+"""
+import hashlib
+import json
+import os
+
+import tezgah_paths as tp
+
+ROOT = tp.PLUGIN_ROOT
+CONTRACT_SHA = os.path.join(tp.CONFIG_DIR, "contract.sha256")
+KEY = "hook:%s:%s"
+# The scripts a host's registration runs, relative to the tree: one file each,
+# so a session start never hashes the plugin tree (about 710 files).
+CLAUDE_SCRIPTS = tuple(os.path.join("hooks", n) for n in (
+    "projects-auto-init.py", "projects-pretooluse.py", "projects-posttooluse.py",
+    "projects-stop.py"))
+CODE_TARGETS = {
+    "claude": CLAUDE_SCRIPTS, "dsh": CLAUDE_SCRIPTS,
+    "codex": (os.path.join("hosts", "codex", "hook.py"),),
+    "cursor": (os.path.join("hosts", "cursor", "hook.py"),),
+    "opencode": (os.path.join("hosts", "opencode", "plugins", "tezgah.js"),),
+    "omp": (os.path.join("hosts", "omp", "hook.py"),),
+}
+OPENCODE_DIRS = ("plugins", "plugin")
+OMP_BRIDGE = os.path.join(tp.HOST_DIRS["omp"], "agent", "hooks", "pre",
+                          "tezgah-hook.ts")
+
+
+def sha(text):
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def recorded_shas(path=CONTRACT_SHA):
+    """{key: sha} from the install record, in sha256sum's `<sha>  <key>` shape."""
+    out = {}
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                digest, _, key = line.rstrip("\n").partition("  ")
+                if key:
+                    out[key] = digest
+    except OSError:
+        pass
+    return out
+
+
+def own_groups(data, own=False):
+    """{event: canonical JSON of its tezgah-owned groups} for a `{"hooks": ...}`
+    manifest. In a shared file (Codex, Cursor) only a group naming tezgah is
+    tezgah's - the filter `install_codex`/`install_cursor` replace by; in
+    tezgah's own manifest (`own`) every group is."""
+    hooks = data.get("hooks") if isinstance(data, dict) else None
+    out = {}
+    for event, groups in (hooks if isinstance(hooks, dict) else {}).items():
+        mine = [g for g in groups if own or "tezgah" in json.dumps(g)] \
+            if isinstance(groups, list) else []
+        if mine:
+            out[event] = json.dumps(mine, sort_keys=True)
+    return out
+
+
+def _manifest(path, own):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return own_groups(json.load(fh), own)
+    except (OSError, ValueError):
+        return None
+
+
+def omp_bridge(root=ROOT):
+    """The omp extension as an install writes it: the template with this tree's
+    hook path, or "" when the template is unreadable."""
+    try:
+        with open(os.path.join(root, "hosts", "omp", "tezgah-hook.ts.in"),
+                  encoding="utf-8") as fh:
+            return fh.read().replace(
+                "@HOOK@", os.path.join(root, "hosts", "omp", "hook.py"))
+    except OSError:
+        return ""
+
+
+def registration(host, root=ROOT):
+    """({entry: text}, [files]) for the tezgah-owned hook entries this host has
+    on disk; the dict is None when the host's file cannot be read."""
+    if host in ("claude", "dsh"):
+        path = os.path.join(root, *(("hooks",) if host == "claude"
+                                    else ("hosts", "dsh")), "hooks.json")
+        return _manifest(path, own=True), [path]
+    if host in ("codex", "cursor"):
+        path = os.path.join(tp.HOST_DIRS[host], "hooks.json")
+        return _manifest(path, own=False), [path]
+    if host == "opencode":
+        links = (os.path.join(tp.HOST_DIRS["opencode"], d, "tezgah.js")
+                 for d in OPENCODE_DIRS)
+        # a keg path is read through opt/, so a `brew upgrade` is no change
+        return {os.path.basename(os.path.dirname(p)): tp.stable_root(os.path.realpath(p))
+                for p in links if os.path.lexists(p)}, []
+    if host == "omp":
+        try:
+            with open(OMP_BRIDGE, encoding="utf-8") as fh:
+                return {"bridge": fh.read()}, [OMP_BRIDGE]
+        except OSError:
+            return None, [OMP_BRIDGE]
+    return None, []
+
+
+def packaged(root=ROOT):
+    """A release tree (tarball, npm, brew) carries no `.git`."""
+    return not os.path.exists(os.path.join(root, ".git"))
+
+
+def code_text(host, root=ROOT):
+    """`<relpath> <sha>` per script the host's entries run, or None."""
+    lines = []
+    for rel in CODE_TARGETS.get(host, ()):
+        try:
+            with open(os.path.join(root, rel), "rb") as fh:
+                lines.append("%s %s" % (rel, hashlib.sha256(fh.read()).hexdigest()))
+        except OSError:
+            return None
+    return "\n".join(lines)
+
+
+def record_texts(host, root=ROOT):
+    """{key: text} an install records for one host (`bin/tezgah-setup::record_hooks`)."""
+    entries, _files = registration(host, root)
+    out = {}
+    if host != "omp":
+        out.update((KEY % (host, name), text)
+                   for name, text in (entries or {}).items())
+    code = code_text(host, root) if packaged(root) else None
+    if code is not None:
+        out[KEY % (host, "code")] = code
+    return out
+
+
+def drift(host, root=ROOT, shas=None):
+    """(drifted, unverified): what differs from the install, and what cannot be
+    judged because the install recorded nothing for it."""
+    shas = recorded_shas() if shas is None else shas
+    prefix = KEY % (host, "")
+    recorded = {k[len(prefix):]: v for k, v in shas.items() if k.startswith(prefix)}
+    entries, files = registration(host, root)
+    found, unknown = [], []
+    for path in files:
+        try:
+            mode = os.stat(path).st_mode & 0o777
+        except OSError:
+            continue
+        if mode & 0o002:
+            found.append("%s mode %04o" % (path, mode))
+    if entries is None:
+        found.append("%s unreadable or missing" % files[0])
+    elif host == "omp":
+        if entries["bridge"] != omp_bridge(root):
+            found.append("omp bridge %s differs from a fresh render" % OMP_BRIDGE)
+    else:
+        names = set(recorded) - {"code"}
+        if not names:
+            unknown.append("no install record for %s hook entries" % host)
+        for name in sorted(names | set(entries)) if names else ():
+            if name not in entries:
+                found.append("%s %s entry removed" % (host, name))
+            elif name not in recorded:
+                found.append("%s %s entry added" % (host, name))
+            elif recorded[name] != sha(entries[name]):
+                found.append("%s %s entry changed" % (host, name))
+    if "code" in recorded:
+        code = code_text(host, root)
+        if code is None or sha(code) != recorded["code"]:
+            found.append("%s hook code changed since install" % host)
+    return found, unknown
+
+
+def drift_mark(session_id, host):
+    """The mark one host's drifted session start leaves; its text is the drift
+    list. Keyed by session AND host: two hosts can share a session id (a
+    `tezgah-context attest` run by hand, a host whose ids collide), and a clean
+    start on one must not clear the other's mark."""
+    return os.path.join(tp.cache_dir(), "harness-drift", "%s.%s" % (
+        hashlib.sha256(str(session_id).encode()).hexdigest()[:16], host))
+
+
+def mark_text(session_id):
+    """The drift lists this session's starts recorded, every host's, or ""."""
+    if not session_id:
+        return ""
+    texts = []
+    for host in CODE_TARGETS:
+        try:
+            with open(drift_mark(session_id, host), encoding="utf-8") as fh:
+                text = fh.read().strip()
+        except OSError:
+            continue
+        if text and text not in texts:
+            texts.append(text)
+    return "; ".join(texts)
+
+
+def switches():
+    """The kill switches present, by name. Before the latching plan (051) lands
+    this is all the row can say about them."""
+    names = set()
+    for d in tp.OFF_DIRS:
+        try:
+            names.update(n for n in os.listdir(d) if n.endswith((".off", "-off")))
+        except OSError:
+            pass
+    return sorted(names)
+
+
+def run(host, session_id, cwd=None):
+    """One `attest` row for this session start, and the drift mark set or
+    cleared to match; the drift list. Outside a root it does nothing."""
+    if not session_id or not tp.root_for(cwd or os.getcwd()):
+        return None
+    found, unknown = drift(host)
+    detail = ("drifted: " + "; ".join(found) if found
+              else "unverified: " + "; ".join(unknown) if unknown else "ok")
+    import tezgah_integrity
+    tezgah_integrity.note(session_id, "attest", detail, host=host,
+                          switches=",".join(switches()) or None)
+    mark = drift_mark(session_id, host)
+    try:
+        if found:
+            os.makedirs(os.path.dirname(mark), exist_ok=True)
+            with open(mark, "w", encoding="utf-8") as fh:
+                fh.write("; ".join(found) + "\n")
+        elif os.path.exists(mark):
+            os.remove(mark)
+    except OSError:
+        pass
+    return found