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

package/install.py

@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+import argparse
+import filecmp
+import json
+import os
+import re
+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"
+TASK_NAME = "SmartTool-Tray"
+ENTRY_SCRIPTS = ("tray.py", "smart_tool_daemon.py", "pretool_router.py")
+STARTUP_SCRIPT = Path(os.environ.get("APPDATA", str(Path.home() / "AppData" / "Roaming"))) / "Microsoft" / "Windows" / \
+    "Start Menu" / "Programs" / "Startup" / "SmartTool-Tray.vbs"
+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({}))
+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 _processes():
+    """(pid, command line) of every python/pythonw process."""
+    listed = powershell("Get-CimInstance Win32_Process -Filter \"Name = 'pythonw.exe' OR Name = 'python.exe'\" | "
+                        "ForEach-Object { \"$($_.ProcessId)`t$($_.CommandLine)\" }").stdout
+    rows = (row.partition("\t") for row in listed.splitlines())
+    return [(int(pid), line) for pid, _tab, line in rows if pid.strip().isdigit()]
+
+
+def _script_folder(script):
+    path = Path(script)
+    return path.parent.parent if path.name == "pretool_router.py" else path.parent
+
+
+def _same_folder(path, folder):
+    """Compares through resolve(), which turns 8.3 short and mixed spellings into the long name."""
+    try:
+        return path.resolve() == folder.resolve()
+    except OSError:
+        return False
+
+
+def stop_processes(target):
+    def running():
+        return [pid for pid, line in _processes() for script in _script_paths(line)
+                if Path(script).name != "pretool_router.py" and _same_folder(_script_folder(script), target)]
+
+    for pid in running():
+        powershell(f"Stop-Process -Id {pid} -Force -ErrorAction SilentlyContinue")
+    deadline = time.monotonic() + 10
+    while True:
+        left = running()
+        if not left:
+            return
+        if time.monotonic() > deadline:
+            raise RuntimeError(f"Could not close the running Smart Tool ({len(left)} 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 hook_files():
+    claude = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+    return claude / "settings.json", Path.home() / ".codex" / "hooks.json"
+
+
+def _script_paths(text):
+    """Absolute paths ending in an entry script, as written in text, tried from every drive letter (paths may hold
+    spaces)."""
+    script = re.compile(r'[^"\r\n]*?(?:' + "|".join(map(re.escape, ENTRY_SCRIPTS)) + ")")
+    for drive in re.finditer(r"[A-Za-z]:[\\/]", text):
+        found = script.match(text, drive.start())
+        if found:
+            yield found.group(0)
+
+
+def _install_folder(script):
+    folder = _script_folder(script)
+    try:
+        return folder.resolve() if (folder / MANIFEST).is_file() and (folder / "smart_tool_daemon.py").is_file() else None
+    except OSError:
+        return None
+
+
+def _task_definition():
+    result = subprocess.run(["schtasks", "/Query", "/TN", TASK_NAME, "/XML"], capture_output=True, text=True,
+                            timeout=20)
+    return result.stdout if result.returncode == 0 else ""
+
+
+def other_installs(target):
+    """Installer-made Smart Tool folders other than target, found through what still runs or points at them: tray and
+    daemon processes, the logon task or Startup script, and agent hook commands."""
+    texts = [line for _pid, line in _processes()] + [_task_definition()]
+    texts += [path.read_text(encoding="utf-8", errors="replace") for path in (STARTUP_SCRIPT, *hook_files())
+              if path.is_file()]
+    folders = {_install_folder(script) for text in texts for script in _script_paths(text)}
+    return sorted(folder for folder in folders
+                  if folder and not _same_folder(folder, target) and not _same_folder(folder, SOURCE))
+
+
+def _repointed(text, folder, target):
+    """text with each spelling of folder found in front of an entry script (long, 8.3 or mixed) replaced by target."""
+    for script in set(_script_paths(text)):
+        cut = len(Path(script).name) + 1 + (len("hooks") + 1 if Path(script).name == "pretool_router.py" else 0)
+        spelled = script[:-cut]
+        if _same_folder(Path(spelled), folder):
+            text = text.replace(spelled, target.as_posix() if "/" in spelled else str(target))
+    return text
+
+
+def remove_other_installs(target):
+    """An older installation in another folder keeps the port and the hooks: stop it, point the hooks at target and
+    delete its program folder. Its state folders are left alone."""
+    removed = []
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    for folder in other_installs(target):
+        print(f"Older Smart Tool installation found at {folder}; removing it.")
+        stop_processes(folder)
+        for path in hook_files():
+            original = path.read_text(encoding="utf-8") if path.is_file() else ""
+            text = _repointed(original, folder, target)
+            if text != original:
+                shutil.copy2(path, path.with_name(f"{path.name}.smart-tool-backup-{stamp}"))
+                path.write_text(text, encoding="utf-8")
+                print(f"Hooks in {path} now point to {target}.")
+        startup = STARTUP_SCRIPT.read_text(encoding="utf-8", errors="replace") if STARTUP_SCRIPT.is_file() else ""
+        if any(_same_folder(_script_folder(script), folder) for script in _script_paths(startup)):
+            STARTUP_SCRIPT.unlink()
+        shutil.rmtree(folder)
+        removed.append(folder)
+    return removed
+
+
+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)
+            folder = (target / rel).parent
+            while folder != target and not any(folder.iterdir()):
+                folder.rmdir()
+                folder = folder.parent
+    (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)
+    remove_other_installs(target)
+    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,283 @@
+#!/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 collections
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+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", idle_s=600, stream=False, attempts=1):
+    """Runs a step with UTF-8 output and closed stdin (a prompt fails at once instead of hanging); it is stopped only
+    after idle_s without any output, and stream shows the output live."""
+    env = os.environ.copy()
+    env.update(PYTHONUTF8="1", PYTHONIOENCODING="utf-8")
+    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
+    for attempt in range(1, attempts + 1):
+        print(f"{label}: starting{f' (attempt {attempt} of {attempts})' if attempt > 1 else ''}...", flush=True)
+        try:
+            _run_once(args, cwd, env, flags, label, idle_s, stream)
+            print(f"{label}: done.", flush=True)
+            return
+        except RuntimeError as exc:
+            if attempt == attempts:
+                raise
+            print(f"{label}: {exc}; trying again.", flush=True)
+
+
+def _run_once(args, cwd, env, flags, label, idle_s, stream):
+    with subprocess.Popen(args, cwd=cwd, env=env, stdin=subprocess.DEVNULL,
+                          stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, encoding="utf-8",
+                          errors="replace", creationflags=flags) as process:
+        tail = collections.deque(maxlen=40)
+        last_output = [time.monotonic()]
+        shown = {"stage": None, "tens": -1}
+
+        def pump():
+            for line in process.stdout:
+                line = line.rstrip()
+                if not line:
+                    continue
+                tail.append(line)
+                last_output[0] = time.monotonic()
+                percent = re.match(r"(.*?)(\d{1,3})%$", line)
+                if percent:
+                    stage, tens = percent.group(1), int(percent.group(2)) // 10
+                    if stage == shown["stage"] and tens <= shown["tens"]:
+                        continue
+                    shown.update(stage=stage, tens=tens)
+                if stream:
+                    print(f"{label}: {line}", flush=True)
+
+        reader = threading.Thread(target=pump, daemon=True)
+        reader.start()
+        started = noted = time.monotonic()
+        while process.poll() is None:
+            now = time.monotonic()
+            if now - last_output[0] > idle_s:
+                if os.name == "nt":
+                    subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"],
+                                   capture_output=True, creationflags=subprocess.CREATE_NO_WINDOW)
+                else:
+                    process.kill()
+                process.wait(timeout=10)
+                raise RuntimeError(f"{label} stopped: no output for {idle_s}s; last output: {tail[-1] if tail else 'none'}")
+            if not stream and now - noted >= 30:
+                noted = now
+                print(f"{label}: waiting for {int(now - started)}s...", flush=True)
+            time.sleep(0.5)
+        reader.join(timeout=10)
+        if process.returncode:
+            raise RuntimeError(f"{' '.join(map(str, args[:3]))} failed (exit {process.returncode}): "
+                               + "\n".join(tail)[-1500:])
+
+
+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", idle_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", idle_s=600)
+    # Camoufox usa Firefox modificado; Crawl4AI usa Chromium via Playwright.
+    if not reuse_browser_runtime:
+        _run([str(BROWSER_PYTHON), str(BROWSER_DIR / "fetch_camoufox.py")], label="Camoufox browser (1.3 GB)",
+             idle_s=180, stream=True, attempts=3)
+        _run([str(BROWSER_PYTHON), "-m", "playwright", "install", "chromium"],
+             label="Chromium browser", idle_s=180, stream=True, attempts=3)
+    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())