@allansantos-dev/smart-tool 0.0.0-stage → 0.9.0

package/install.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+import argparse
+import filecmp
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+import venv
+from pathlib import Path
+
+import paths
+
+SOURCE = Path(__file__).resolve().parent
+DEFAULT_TARGET = Path(os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local"))) / "Programs" / "SmartTool"
+MANIFEST = ".install-manifest.json"
+REGISTRY = Path(paths.DATA_DIR) / "daemon.json"
+BLOCKED = {"__pycache__", ".token-guard", ".git", ".pytest_cache", ".data", ".artifacts", ".claude", ".vscode",
+           ".impeccable", "tests", "sessions", "results", "dist", "node_modules", ".node-runtime", ".venv",
+           ".scratch", ".memory", "docs", "reports", "site", "design", "release", "npm", ".github", "AGENTS.md", "CLAUDE.md", "DESIGN.md", "PRODUCT.md", "install.py", ".gitignore", ".gitattributes", MANIFEST}
+PACKAGE_ONLY = {"bin", "package.json", ".npmignore"}
+REQUIRED_TOOLS = {"smart_search", "smart_search_result", "web_search", "project_manage"}
+_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+_FIND = ("$tray = $env:SMART_TRAY.ToLowerInvariant(); $daemon = $env:SMART_DAEMON.ToLowerInvariant(); "
+         "Get-CimInstance Win32_Process -Filter \"Name = 'pythonw.exe' OR Name = 'python.exe'\" | "
+         "Where-Object { $_.CommandLine -and ($_.CommandLine.ToLowerInvariant().Contains($tray) -or "
+         "$_.CommandLine.ToLowerInvariant().Contains($daemon)) }")
+
+
+def ships(rel):
+    parts = Path(rel).parts
+    *folders, name = parts
+    return (parts[0] not in PACKAGE_ONLY
+            and not any(part in BLOCKED or part.startswith("_cdp_") for part in folders)
+            and name not in BLOCKED and not name.endswith((".log", ".pyc", ".png")))
+
+
+def source_files():
+    files = []
+    for current, dirs, names in os.walk(SOURCE):
+        dirs[:] = sorted(d for d in dirs if d not in BLOCKED and not d.startswith("_cdp_"))
+        files += [rel for rel in ((Path(current) / name).relative_to(SOURCE).as_posix() for name in sorted(names))
+                  if ships(rel)]
+    return files
+
+
+def python_paths(target):
+    scripts = target / ".venv" / "Scripts"
+    return scripts / "python.exe", scripts / "pythonw.exe"
+
+
+def powershell(script, env=None, timeout=30):
+    return subprocess.run(["powershell.exe", "-NoProfile", "-Command", script], env={**os.environ, **(env or {})},
+                          capture_output=True, text=True, timeout=timeout)
+
+
+def stop_processes(target):
+    env = {"SMART_TRAY": str(target / "tray.py"), "SMART_DAEMON": str(target / "smart_tool_daemon.py")}
+    powershell(_FIND + " | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }", env=env)
+    deadline = time.monotonic() + 10
+    while True:
+        left = powershell("@(" + _FIND + ").Count", env=env).stdout.strip()
+        if left == "0":
+            return
+        if time.monotonic() > deadline:
+            raise RuntimeError(f"Could not close the running Smart Tool ({left or '?'} process(es) still active).")
+        time.sleep(0.5)
+
+
+def wait_port_free():
+    deadline = time.monotonic() + 15
+    while time.monotonic() < deadline and _daemon_up():
+        time.sleep(0.5)
+    if _daemon_up():
+        raise RuntimeError("Another Smart Tool daemon is still active on the registered port; close it before updating.")
+
+
+def _daemon_up():
+    try:
+        url = json.loads(REGISTRY.read_text(encoding="utf-8"))["url"]
+        with _OPENER.open(url + "/health", timeout=1) as response:
+            return response.status == 200
+    except (OSError, ValueError, KeyError):
+        return False
+
+
+def copy_files(target, files, backup, changed, removed):
+    previous = set(json.loads((target / MANIFEST).read_text(encoding="utf-8"))["files"]) if (target / MANIFEST).is_file() else set()
+    if (target / MANIFEST).is_file():
+        shutil.copy2(target / MANIFEST, backup / MANIFEST)
+    for rel in files:
+        source, dest = SOURCE / rel, target / rel
+        if dest.is_file() and filecmp.cmp(source, dest, shallow=False):
+            continue
+        if dest.is_file():
+            (backup / rel).parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(dest, backup / rel)
+        changed.append(rel)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, dest)
+    for rel in sorted(previous - set(files)):
+        if (target / rel).is_file():
+            (backup / rel).parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(target / rel, backup / rel)
+            removed.append(rel)
+    (target / MANIFEST).write_text(json.dumps({"installed_at": time.time(), "source": str(SOURCE), "files": files},
+                                              indent=1), encoding="utf-8")
+
+
+def restore(target, backup, changed, removed):
+    for rel in changed:
+        if (backup / rel).is_file():
+            shutil.copy2(backup / rel, target / rel)
+        else:
+            (target / rel).unlink(missing_ok=True)
+    for rel in removed:
+        if (backup / rel).is_file():
+            (target / rel).parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(backup / rel, target / rel)
+    if (backup / MANIFEST).is_file():
+        shutil.copy2(backup / MANIFEST, target / MANIFEST)
+    else:
+        (target / MANIFEST).unlink(missing_ok=True)
+
+
+def freeze(python):
+    if not python.exists():
+        return None
+    return subprocess.run([str(python), "-m", "pip", "freeze", "--disable-pip-version-check"],
+                          check=True, capture_output=True, text=True).stdout
+
+
+def restore_packages(python, frozen, backup):
+    if frozen is None:
+        return
+    (backup / "requirements.frozen.txt").write_text(frozen, encoding="utf-8")
+    subprocess.run([str(python), "-m", "pip", "install", "--disable-pip-version-check", "-q", "-r",
+                    str(backup / "requirements.frozen.txt")], check=True)
+
+
+def install_dependencies(target, python):
+    if not python.exists():
+        venv.create(python.parent.parent, with_pip=True)
+    subprocess.run([str(python), "-m", "pip", "install", "--disable-pip-version-check", "-q", "-r",
+                    str(target / "requirements.txt")], check=True)
+    subprocess.run([str(python), str(target / "install_runtime.py")], check=True)
+
+
+def start(target, python, pythonw):
+    subprocess.run([str(python), "-c", "import autostart, json; print(json.dumps(autostart.install()))"],
+                   cwd=target, check=True, capture_output=True, text=True, timeout=60)
+    subprocess.Popen([str(pythonw if pythonw.exists() else python), str(target / "tray.py")], cwd=target,
+                     stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                     creationflags=getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(subprocess, "CREATE_NO_WINDOW", 0))
+
+
+def verify(target, python):
+    script = ("import json,urllib.request,daemon_launcher; url=daemon_launcher.ensure_daemon_running(wait_seconds=30); "
+              "body=json.dumps({'jsonrpc':'2.0','id':1,'method':'tools/list','params':{}}).encode(); "
+              "req=urllib.request.Request(url+'/mcp',data=body,method='POST',headers={'Content-Type':'application/json'}); "
+              "opener=urllib.request.build_opener(urllib.request.ProxyHandler({})); "
+              "print(json.dumps(sorted(r['name'] for r in json.load(opener.open(req,timeout=10))['result']['tools'])))")
+    result = subprocess.run([str(python), "-c", script], cwd=target, capture_output=True, text=True, timeout=60)
+    if result.returncode:
+        raise RuntimeError("Daemon did not respond: " + ((result.stderr or result.stdout).strip().splitlines() or ["no output"])[-1])
+    missing = REQUIRED_TOOLS - set(json.loads(result.stdout.strip().splitlines()[-1]))
+    if missing:
+        raise RuntimeError("Missing MCP tools: " + ", ".join(sorted(missing)))
+    pid = json.loads(REGISTRY.read_text(encoding="utf-8"))["pid"]
+    command = powershell(f"(Get-CimInstance Win32_Process -Filter 'ProcessId = {int(pid)}').CommandLine").stdout
+    if str(target / "smart_tool_daemon.py").lower() not in command.lower():
+        raise RuntimeError(f"The active daemon (pid {pid}) does not belong to this installation: {command.strip()[:200]}")
+
+
+MIN_PYTHON = (3, 11)
+
+
+def main():
+    if sys.version_info < MIN_PYTHON:
+        raise SystemExit(f"Smart Tool needs Python {'.'.join(map(str, MIN_PYTHON))} or newer; this is "
+                         f"{sys.version.split()[0]} ({sys.executable}).")
+    parser = argparse.ArgumentParser(description="Install or update Smart Tool over the existing installation.")
+    parser.add_argument("--target", type=Path, default=DEFAULT_TARGET)
+    parser.add_argument("--skip-deps", action="store_true", help="do not run pip or install_runtime.py")
+    parser.add_argument("--no-start", action="store_true", help="do not restart or check the daemon")
+    parser.add_argument("--skip-tests", action="store_true",
+                        help="install without running tests/run.py (npm package, whose tests ran in CI; emergency only otherwise)")
+    args = parser.parse_args()
+    target = args.target.resolve()
+    if target == SOURCE:
+        raise SystemExit("The target cannot be the source folder itself.")
+    if args.skip_tests:
+        print("Tests skipped by --skip-tests.")
+    elif not (SOURCE / "tests" / "run.py").is_file():
+        raise SystemExit(f"No test suite in {SOURCE}; a packaged install runs with --skip-tests (npx @allansantos-dev/smart-tool install).")
+    else:
+        interpreter = python_paths(target)[0] if python_paths(target)[0].is_file() else Path(sys.executable)
+        tests = subprocess.run([str(interpreter), str(SOURCE / "tests" / "run.py")], capture_output=True, text=True,
+                               encoding="utf-8", errors="replace")
+        print(tests.stdout.rstrip())
+        if tests.stderr.strip():
+            print(tests.stderr.rstrip()[-3000:], file=sys.stderr)
+        if tests.returncode:
+            raise SystemExit("Tests failed; installation aborted without touching the installed version.")
+    python, pythonw = python_paths(target)
+    files = source_files()
+    existed = (target / "smart_tool_daemon.py").is_file()
+    print(("Updating" if existed else "Installing") + f" Smart Tool at {target} ({len(files)} files from {SOURCE})")
+    target.mkdir(parents=True, exist_ok=True)
+    stop_processes(target)
+    if not args.no_start:
+        wait_port_free()
+    backup = target.parent / f".smart-tool-backup-{time.strftime('%Y%m%d-%H%M%S')}"
+    backup.mkdir()
+    changed, removed, frozen, deps_touched = [], [], None, False
+    try:
+        copy_files(target, files, backup, changed, removed)
+        print(f"Files changed: {len(changed)}; removed as obsolete: {len(removed)}")
+        if not args.skip_deps:
+            frozen = freeze(python)
+            deps_touched = True
+            install_dependencies(target, python)
+        if not args.no_start:
+            start(target, python, pythonw)
+            verify(target, python)
+    except BaseException as exc:
+        print(f"Failed: {exc}. Restoring the previous version.", file=sys.stderr)
+        problems = []
+        steps = [lambda: stop_processes(target), lambda: restore(target, backup, changed, removed)]
+        if deps_touched:
+            steps.append(lambda: restore_packages(python, frozen, backup))
+        if existed and not args.no_start:
+            steps.append(lambda: start(target, python, pythonw))
+        for step in steps:
+            try:
+                step()
+            except Exception as error:
+                problems.append(str(error))
+        if problems:
+            print(f"Incomplete rollback; backup kept at {backup}: " + " | ".join(problems), file=sys.stderr)
+            raise SystemExit(1)
+        shutil.rmtree(backup, ignore_errors=True)
+        raise SystemExit(1)
+    shutil.rmtree(backup)
+    print("Smart Tool ready." if not args.no_start else "Files installed; daemon not restarted (--no-start).")
+
+
+if __name__ == "__main__":
+    main()

package/install_runtime.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Instala as dependências opcionais de busca dentro da pasta da Smart Tool.
+
+Uso: python install_runtime.py [--check]
+Não altera ~/.claude nem instala pacotes npm globalmente.
+"""
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+import venv
+import zipfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent
+NODE_DIR = ROOT / "web_adapters" / "node"
+BROWSER_DIR = ROOT / "web_adapters" / "browser"
+BROWSER_PYTHON = BROWSER_DIR / ".venv" / "Scripts" / "python.exe"
+OPEN_WEBSEARCH_CLI = NODE_DIR / "node_modules" / "open-websearch" / "build" / "index.js"
+TYPESCRIPT_PARSER = NODE_DIR / "node_modules" / "typescript" / "lib" / "typescript.js"
+JAVA_PARSER = NODE_DIR / 'node_modules' / 'java-parser' / 'src' / 'index.js'
+ANGULAR_PARSER = NODE_DIR / 'node_modules' / '@angular' / 'compiler' / 'fesm2022' / 'compiler.mjs'
+NODE_RUNTIME = NODE_DIR / ".node-runtime"
+
+
+def _node_supported(node):
+    """Aceita apenas versoes suportadas pelo @angular/compiler 20.3.0."""
+    try:
+        result = subprocess.run([str(node), "--version"], capture_output=True, text=True,
+                                timeout=10, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    match = re.fullmatch(r"v(\d+)\.(\d+)\.\d+", result.stdout.strip())
+    if result.returncode or not match:
+        return False
+    major, minor = map(int, match.groups())
+    return (major == 20 and minor >= 19) or (major == 22 and minor >= 12) or major >= 24
+
+
+def _node_commands():
+    local_node, local_npm = NODE_RUNTIME / "node.exe", NODE_RUNTIME / "npm.cmd"
+    if NODE_RUNTIME.exists():
+        if local_node.is_file() and local_npm.is_file() and _node_supported(local_node):
+            return str(local_node), str(local_npm)
+        return None, None
+    node = shutil.which("node")
+    npm = shutil.which("npm.cmd") or shutil.which("npm")
+    return (node, npm) if node and npm and _node_supported(node) else (None, None)
+
+
+def _install_node():
+    """Baixa o Node LTS oficial e confere SHA-256 antes de extrair."""
+    print("Downloading Node LTS for the Smart Tool web runtime...", flush=True)
+    with urllib.request.urlopen("https://nodejs.org/dist/index.json", timeout=30) as response:
+        releases = json.load(response)
+    release = next((row for row in releases if row.get("lts") and
+                    "win-x64-zip" in row.get("files", [])), None)
+    if not release:
+        raise RuntimeError("Node LTS for Windows x64 not found in the official index.")
+    version = release["version"]
+    archive = f"node-{version}-win-x64.zip"
+    base = f"https://nodejs.org/dist/{version}/"
+    with urllib.request.urlopen(base + "SHASUMS256.txt", timeout=30) as response:
+        checksums = response.read().decode("ascii")
+    expected = next((line.split()[0] for line in checksums.splitlines()
+                     if line.split()[-1:] == [archive]), None)
+    if not expected:
+        raise RuntimeError("Official Node checksum not found.")
+    with tempfile.TemporaryDirectory(prefix="node-setup-", dir=NODE_DIR) as temp:
+        temp_dir = Path(temp)
+        zip_path = temp_dir / archive
+        digest = hashlib.sha256()
+        with urllib.request.urlopen(base + archive, timeout=60) as response, zip_path.open("wb") as out:
+            while block := response.read(1024 * 1024):
+                digest.update(block)
+                out.write(block)
+        if digest.hexdigest().lower() != expected.lower():
+            raise RuntimeError("Node SHA-256 checksum does not match the official index.")
+        unpacked = temp_dir / "runtime"
+        unpacked.mkdir()
+        with zipfile.ZipFile(zip_path) as zf:
+            for member in zf.infolist():
+                parts = Path(member.filename.replace("\\", "/")).parts
+                if parts == (f"node-{version}-win-x64",) and member.is_dir():
+                    continue
+                if len(parts) < 2 or parts[0] != f"node-{version}-win-x64" or ".." in parts:
+                    raise RuntimeError("Node archive contains an unexpected path.")
+                destination = unpacked.joinpath(*parts[1:])
+                if member.is_dir():
+                    destination.mkdir(parents=True, exist_ok=True)
+                else:
+                    destination.parent.mkdir(parents=True, exist_ok=True)
+                    with zf.open(member) as source, destination.open("wb") as target:
+                        shutil.copyfileobj(source, target)
+        if not (unpacked / "node.exe").is_file() or not (unpacked / "npm.cmd").is_file():
+            raise RuntimeError("Node package does not contain the expected executables.")
+        previous = temp_dir / "previous-node-runtime"
+        if NODE_RUNTIME.exists():
+            os.replace(NODE_RUNTIME, previous)
+        try:
+            os.replace(unpacked, NODE_RUNTIME)
+        except OSError:
+            if previous.exists() and not NODE_RUNTIME.exists():
+                os.replace(previous, NODE_RUNTIME)
+            raise
+    print(f"Node {version} installed inside Smart Tool.")
+
+
+def _run(args, *, cwd=None, label="Web dependency", timeout_s=600):
+    env = os.environ.copy()
+    if NODE_RUNTIME.is_dir():
+        env["PATH"] = str(NODE_RUNTIME) + os.pathsep + env.get("PATH", "")
+    flags = (subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW) if os.name == "nt" else 0
+    print(f"{label}: starting...", flush=True)
+    started = time.monotonic()
+    process = subprocess.Popen(args, cwd=cwd, env=env, stdout=subprocess.PIPE,
+                               stderr=subprocess.PIPE, text=True, encoding="utf-8",
+                               errors="replace", creationflags=flags)
+    while True:
+        remaining = timeout_s - (time.monotonic() - started)
+        if remaining <= 0:
+            if os.name == "nt":
+                subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"],
+                               capture_output=True, creationflags=subprocess.CREATE_NO_WINDOW)
+            else:
+                process.kill()
+            try:
+                process.communicate(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.communicate(timeout=5)
+            raise RuntimeError(f"{label} exceeded {timeout_s}s; check network, proxy and access to the package registry.")
+        try:
+            stdout, stderr = process.communicate(timeout=min(30, remaining))
+            break
+        except subprocess.TimeoutExpired:
+            print(f"{label}: waiting for {int(time.monotonic() - started)}s...", flush=True)
+    if process.returncode:
+        detail = (stderr or stdout).strip()[-1500:]
+        raise RuntimeError(f"{' '.join(map(str, args[:3]))} failed: {detail}")
+    print(f"{label}: done.", flush=True)
+
+
+def _check():
+    node, _npm = _node_commands()
+    status = {
+        "node": bool(node),
+        "open_websearch": bool(node and OPEN_WEBSEARCH_CLI.is_file()),
+        "typescript_parser": bool(node and TYPESCRIPT_PARSER.is_file()),
+        "java_parser":bool(node and JAVA_PARSER.is_file()),
+        "angular_parser":bool(node and ANGULAR_PARSER.is_file()),
+        "browser_python": BROWSER_PYTHON.is_file(),
+        "browser_packages": False,
+    }
+    if status["browser_python"]:
+        try:
+            result = subprocess.run(
+                [str(BROWSER_PYTHON), "-c", "import camoufox, crawl4ai, playwright"],
+                capture_output=True, check=False, timeout=30,
+            )
+            status["browser_packages"] = result.returncode == 0
+        except subprocess.TimeoutExpired:
+            status["browser_packages"] = False
+    return status
+
+
+def _link_existing_browser(existing, link):
+    try:
+        os.symlink(existing, link, target_is_directory=True)
+    except OSError:
+        # Junction não exige Developer Mode nem privilégio de symlink no Windows.
+        env = os.environ.copy()
+        env["SMART_TOOL_BROWSER_LINK_PATH"] = str(link)
+        env["SMART_TOOL_BROWSER_LINK_TARGET"] = str(existing)
+        result = subprocess.run(
+            ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command",
+             "New-Item -ItemType Junction -Path $env:SMART_TOOL_BROWSER_LINK_PATH "
+             "-Target $env:SMART_TOOL_BROWSER_LINK_TARGET | Out-Null"],
+            env=env, capture_output=True, text=True, encoding="utf-8", errors="replace",
+        )
+        if result.returncode or not link.is_dir():
+            raise RuntimeError(f"Could not link the existing runtime: {result.stderr.strip()[-600:]}")
+
+
+def install(reuse_browser_runtime=None):
+    if os.name != "nt":
+        raise RuntimeError("This browser installer is built for Windows.")
+    node, npm = _node_commands()
+    if not node or not npm:
+        _install_node()
+        node, npm = _node_commands()
+    if not all(path.is_file() for path in (OPEN_WEBSEARCH_CLI,TYPESCRIPT_PARSER,JAVA_PARSER,ANGULAR_PARSER)):
+        _run([npm, "ci", "--omit=dev", "--no-audit", "--no-fund"], cwd=NODE_DIR,
+             label="Web adapters and code parser via npm", timeout_s=300)
+    if reuse_browser_runtime:
+        existing = Path(reuse_browser_runtime).expanduser().resolve()
+        if not (existing / "Scripts" / "python.exe").is_file():
+            raise RuntimeError(f"Invalid browser environment: {existing}")
+        link = BROWSER_DIR / ".venv"
+        if link.exists() and link.resolve() != existing:
+            raise RuntimeError(f"Another browser environment already exists at {link}")
+        if not link.exists():
+            _link_existing_browser(existing, link)
+    if not BROWSER_PYTHON.is_file():
+        venv.create(BROWSER_DIR / ".venv", with_pip=True)
+    if not _check()["browser_packages"]:
+        _run([str(BROWSER_PYTHON), "-m", "pip", "install", "--disable-pip-version-check",
+              "--no-input", "-r", str(BROWSER_DIR / "requirements.txt")],
+             label="Camoufox and Crawl4AI via pip", timeout_s=600)
+    # Camoufox usa Firefox modificado; Crawl4AI usa Chromium via Playwright.
+    if not reuse_browser_runtime:
+        _run([str(BROWSER_PYTHON), "-m", "camoufox", "fetch"],
+             label="Camoufox browser", timeout_s=600)
+        _run([str(BROWSER_PYTHON), "-m", "playwright", "install", "chromium"],
+             label="Chromium browser", timeout_s=600)
+    status = _check()
+    if not all(status.values()):
+        raise RuntimeError(f"Incomplete web runtime: {status}")
+    print("Smart Tool runtime installed: Node, open-websearch, TypeScript, Java, Angular, Camoufox and Crawl4AI.")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Install/check the Smart Tool web runtime")
+    parser.add_argument("--check", action="store_true", help="Show the status without installing")
+    parser.add_argument("--reuse-browser-runtime", metavar="FOLDER",
+                        help="Reuse an existing venv without duplicating files (useful when disk is low)")
+    args = parser.parse_args()
+    if args.check:
+        for name, ready in _check().items():
+            print(f"{name}: {'ok' if ready else 'missing'}")
+        return 0 if all(_check().values()) else 1
+    try:
+        install(args.reuse_browser_runtime)
+    except (OSError, RuntimeError, subprocess.SubprocessError) as exc:
+        print(f"Web runtime installation failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/integration_metrics.py

@@ -0,0 +1,82 @@
+import collections
+import json
+import os
+import paths
+import threading
+import time
+
+import atomic_io
+import router
+
+PATH = os.path.join(paths.DATA_DIR, "integration-metrics.jsonl")
+MAX_BYTES = 20 * 1024 * 1024
+_LOCK = threading.Lock()
+
+
+def record(event, **fields):
+    line = json.dumps({"ts": time.time(), "event": event, **fields}, ensure_ascii=False)
+    with _LOCK:
+        os.makedirs(os.path.dirname(PATH), exist_ok=True)
+        atomic_io.rotate(PATH, MAX_BYTES)
+        with open(PATH, "a", encoding="utf-8") as stream:
+            stream.write(line + "\n")
+
+
+def _read(path, since):
+    rows = []
+    for candidate in (path + ".1", path):
+        try:
+            with open(candidate, encoding="utf-8") as stream:
+                for line in stream:
+                    try:
+                        row = json.loads(line)
+                    except ValueError:
+                        continue
+                    if isinstance(row, dict) and isinstance(row.get("ts"), (int, float)) and row["ts"] >= since:
+                        rows.append(row)
+        except FileNotFoundError:
+            continue
+    return rows
+
+
+def summary(days=7):
+    since = time.time() - days * 86400
+    events = _read(PATH, since)
+    by_client = collections.defaultdict(collections.Counter)
+    reasons, rejects = collections.Counter(), collections.Counter()
+    for row in events:
+        by_client[row.get("client") or "desconhecido"][row.get("event", "?")] += 1
+        if row.get("event") == "search" and row.get("single_language_reason"):
+            reasons[row["single_language_reason"][:120]] += 1
+        if row.get("event") == "reject":
+            rejects[row.get("kind", "outro")] += 1
+    web = [row for row in events if row.get("event") == "web_search"]
+    origin = lambda row: "error" if row.get("error") else row.get("cache", "?")
+    by_cache = collections.Counter(origin(row) for row in web)
+    elapsed = collections.defaultdict(list)
+    for row in web:
+        if isinstance(row.get("elapsed_s"), (int, float)):
+            elapsed[origin(row)].append(row["elapsed_s"])
+    reused = sum(count for status, count in by_cache.items() if status not in ("fresh", "error"))
+    web_cache = {
+        "calls": len(web), "reused": reused, "reuse_rate": round(reused / len(web), 3) if web else None,
+        "by_cache": dict(by_cache),
+        "probes": sum(1 for row in web if row.get("probe")),
+        "probe_verdicts": dict(collections.Counter(row["verdict"] for row in web if row.get("verdict"))),
+        "errors": dict(collections.Counter(row["error"] for row in web if row.get("error"))),
+        "reused_volatility": dict(collections.Counter(row.get("volatility") or "?" for row in web
+                                                      if origin(row) not in ("fresh", "error"))),
+        "bilingual": sum(1 for row in web if row.get("bilingual")),
+        "degraded": sum(1 for row in web if row.get("degraded")),
+        "with_warnings": sum(1 for row in web if row.get("warnings")),
+        "avg_elapsed_s": {status: round(sum(values) / len(values), 2) for status, values in elapsed.items()},
+    }
+    routed = _read(router.METRICS_PATH, since)
+    decisions = collections.defaultdict(collections.Counter)
+    for row in routed:
+        decisions[row.get("client") or "no client"][row.get("decision", "?")] += 1
+    return {"days": days, "events_by_client": {k: dict(v) for k, v in by_client.items()},
+            "rejects_by_kind": dict(rejects), "single_language_reasons": dict(reasons.most_common(20)),
+            "hook_decisions_by_client": {k: dict(v) for k, v in decisions.items()},
+            "web_search_cache": web_cache,
+            "files": {"integration": PATH, "router": router.METRICS_PATH}}