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

package/bin/smart-tool.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
+const RUNTIME_DIR = join(homedir(), ".smart-tool", "runtime");
+const UV_VERSION = "0.12.23";
+const UV_ASSET = "uv-x86_64-pc-windows-msvc.zip";
+const UV_SHA256 = "75d05de6762778c31ee183398de7dd15093fad0ed90b1f236d8205ea5ec00c90";
+const UV_DIR = join(RUNTIME_DIR, `uv-${UV_VERSION}`);
+const UV_EXE = join(UV_DIR, "uv.exe");
+const PYTHON_VERSION = "3.12";
+const PYTHON_DIR = join(RUNTIME_DIR, "python");
+const USAGE = `Usage: npx @allansantos-dev/smart-tool install [--target DIR] [--no-start] [--skip-deps]
+
+Installs or updates Smart Tool for this Windows user. Run it again with @latest to update.`;
+
+function fail(message) {
+  console.error(`smart-tool: ${message}`);
+  process.exit(1);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", windowsHide: true, ...options });
+  if (result.error) fail(`${command} did not start: ${result.error.message}`);
+  if (result.status !== 0) fail(`${command} ${args.join(" ")} exited with ${result.status}: ${(result.stderr || result.stdout || "").trim().slice(-2000)}`);
+  return (result.stdout || "").trim();
+}
+
+async function ensureUv() {
+  if (existsSync(UV_EXE)) return;
+  const url = `https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/${UV_ASSET}`;
+  console.log(`Downloading uv ${UV_VERSION} (Python manager)...`);
+  const response = await fetch(url);
+  if (!response.ok) fail(`download of ${url} failed: HTTP ${response.status}`);
+  const archive = Buffer.from(await response.arrayBuffer());
+  const digest = createHash("sha256").update(archive).digest("hex");
+  if (digest !== UV_SHA256) fail(`${UV_ASSET} checksum mismatch (expected ${UV_SHA256}, got ${digest}).`);
+  const scratch = mkdtempSync(join(tmpdir(), "smart-tool-uv-"));
+  try {
+    const zip = join(scratch, UV_ASSET);
+    writeFileSync(zip, archive);
+    mkdirSync(UV_DIR, { recursive: true });
+    run(join(process.env.SystemRoot || "C:\\Windows", "System32", "tar.exe"), ["-xf", zip, "-C", UV_DIR]);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  if (!existsSync(UV_EXE)) fail(`uv.exe not found in ${UV_DIR} after extracting ${UV_ASSET}.`);
+}
+
+function ensurePython() {
+  const env = { ...process.env, UV_PYTHON_INSTALL_DIR: PYTHON_DIR };
+  console.log(`Preparing Python ${PYTHON_VERSION} in ${PYTHON_DIR}...`);
+  run(UV_EXE, ["python", "install", PYTHON_VERSION, "--no-bin", "--no-registry"], { env });
+  const python = run(UV_EXE, ["python", "find", "--managed-python", "--no-python-downloads", PYTHON_VERSION], { env });
+  if (!python.toLowerCase().startsWith(PYTHON_DIR.toLowerCase())) fail(`uv returned a Python outside ${PYTHON_DIR}: ${python}`);
+  return python;
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (command === "--version" || command === "-v") {
+    console.log(JSON.parse(readFileSync(join(PACKAGE_DIR, "package.json"), "utf8")).version);
+    return;
+  }
+  if (command !== "install") {
+    console.log(USAGE);
+    process.exit(command === undefined || command === "--help" || command === "-h" ? 0 : 1);
+  }
+  if (process.platform !== "win32" || process.arch !== "x64") fail(`Smart Tool runs on Windows x64 only (this is ${process.platform}-${process.arch}).`);
+  await ensureUv();
+  const python = ensurePython();
+  const installer = spawnSync(python, [join(PACKAGE_DIR, "install.py"), "--skip-tests", ...rest], { stdio: "inherit", cwd: PACKAGE_DIR });
+  if (installer.error) fail(`the installer did not start: ${installer.error.message}`);
+  process.exit(installer.status ?? 1);
+}
+
+main().catch((error) => fail(error.stack || String(error)));

package/browser_service_client.py

@@ -0,0 +1,232 @@
+"""Cliente do navegador residente (web_adapters/browser/browser_service.py): um processo para todos os consumidores."""
+import concurrent.futures
+import json
+import os
+import queue
+import subprocess
+import threading
+import time
+import uuid
+
+START_TIMEOUT_S = 45
+START_FAILURE_COOLDOWN_S = 60
+SERVICE_IDLE_S = 300
+# Restart instead of writing to a service that may be exiting on its own idle timer.
+IDLE_RESTART_MARGIN_S = 15
+_IS_WINDOWS = os.name == "nt"
+
+
+class BrowserCaptcha(RuntimeError):
+    pass
+
+
+class BrowserSkipped(RuntimeError):
+    """Self-imposed limit (queue, pacing, pause, startup): not a failure of the search engine."""
+
+
+class BrowserExited(RuntimeError):
+    pass
+
+
+def _kill_on_close_job():
+    import ctypes
+    from ctypes import wintypes
+
+    class IoCounters(ctypes.Structure):
+        _fields_ = [(name, ctypes.c_ulonglong) for name in
+                    ("read_ops", "write_ops", "other_ops", "read_bytes", "write_bytes", "other_bytes")]
+
+    class BasicLimits(ctypes.Structure):
+        _fields_ = [("per_process_time", ctypes.c_longlong), ("per_job_time", ctypes.c_longlong),
+                    ("flags", wintypes.DWORD), ("min_ws", ctypes.c_size_t), ("max_ws", ctypes.c_size_t),
+                    ("active_processes", wintypes.DWORD), ("affinity", ctypes.c_size_t),
+                    ("priority", wintypes.DWORD), ("scheduling", wintypes.DWORD)]
+
+    class ExtendedLimits(ctypes.Structure):
+        _fields_ = [("basic", BasicLimits), ("io", IoCounters), ("process_memory", ctypes.c_size_t),
+                    ("job_memory", ctypes.c_size_t), ("peak_process_memory", ctypes.c_size_t),
+                    ("peak_job_memory", ctypes.c_size_t)]
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.CreateJobObjectW.restype = wintypes.HANDLE
+    job = kernel32.CreateJobObjectW(None, None)
+    if not job:
+        raise ctypes.WinError(ctypes.get_last_error())
+    limits = ExtendedLimits()
+    limits.basic.flags = 0x2000  # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+    if not kernel32.SetInformationJobObject(wintypes.HANDLE(job), 9, ctypes.byref(limits), ctypes.sizeof(limits)):
+        raise ctypes.WinError(ctypes.get_last_error())
+    return kernel32, job
+
+
+class BrowserService:
+    def __init__(self, executable, script):
+        self.executable = executable
+        self.script = script
+        self.lock = threading.Lock()
+        self.start_lock = threading.Lock()
+        self.proc = None
+        self.writes = None
+        self.pending = {}
+        self.stderr_tail = ""
+        self.last_used = 0.0
+        self.start_failure = None
+        self.job = None
+
+    def _alive(self):
+        return self.proc is not None and self.proc.poll() is None
+
+    def _ensure_started(self, deadline):
+        with self.lock:
+            if self._alive() and time.monotonic() - self.last_used < SERVICE_IDLE_S - IDLE_RESTART_MARGIN_S:
+                return self.proc, self.writes
+        if not self.start_lock.acquire(timeout=max(0, deadline - time.monotonic())):
+            raise BrowserSkipped("resident browser still opening at the deadline")
+        try:
+            with self.lock:
+                if self._alive() and time.monotonic() - self.last_used < SERVICE_IDLE_S - IDLE_RESTART_MARGIN_S:
+                    return self.proc, self.writes
+                stale, self.proc = self.proc, None
+            if stale is not None:
+                self._kill(stale)
+            if self.start_failure and time.monotonic() - self.start_failure[0] < START_FAILURE_COOLDOWN_S:
+                raise RuntimeError(self.start_failure[1])
+            try:
+                proc, writes = self._start()
+            except RuntimeError as exc:
+                self.start_failure = (time.monotonic(), str(exc))
+                raise
+            self.start_failure = None
+            with self.lock:
+                self.proc, self.writes, self.last_used = proc, writes, time.monotonic()
+            return proc, writes
+        finally:
+            self.start_lock.release()
+
+    def _start(self):
+        flags = (subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW) if _IS_WINDOWS else 0
+        proc = subprocess.Popen([self.executable, self.script], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace",
+                                creationflags=flags)
+        if _IS_WINDOWS:
+            self._bind_to_daemon(proc)
+        ready = concurrent.futures.Future()
+        writes = queue.Queue()
+        threading.Thread(target=self._read_stderr, args=(proc,), daemon=True).start()
+        threading.Thread(target=self._read_stdout, args=(proc, ready), daemon=True).start()
+        threading.Thread(target=self._write_stdin, args=(proc, writes), daemon=True).start()
+        try:
+            ready.result(timeout=START_TIMEOUT_S)
+        except Exception as exc:
+            self._kill(proc)
+            raise RuntimeError(f"resident browser failed to start: {exc}; {self.stderr_tail[-500:]}") from None
+        return proc, writes
+
+    def _bind_to_daemon(self, proc):
+        # Kill-on-close job: the browser tree dies with the daemon even when the daemon is killed hard.
+        try:
+            if self.job is None:
+                self.job = _kill_on_close_job()
+            kernel32, job = self.job
+            import ctypes
+            from ctypes import wintypes
+            if not kernel32.AssignProcessToJobObject(wintypes.HANDLE(job), wintypes.HANDLE(proc._handle)):
+                raise ctypes.WinError(ctypes.get_last_error())
+        except OSError as exc:
+            self.stderr_tail += f"\nprocess outside the job object: {exc}\n"
+
+    def _write_stdin(self, proc, writes):
+        while True:
+            line = writes.get()
+            if line is None:
+                return
+            try:
+                proc.stdin.write(line)
+                proc.stdin.flush()
+            except (OSError, ValueError):
+                return
+
+    def _read_stdout(self, proc, ready):
+        for line in proc.stdout:
+            try:
+                message = json.loads(line)
+            except ValueError:
+                continue
+            if not isinstance(message, dict):
+                continue
+            if message.get("ready"):
+                if not ready.done():
+                    ready.set_result(True)
+                continue
+            with self.lock:
+                _owner, future = self.pending.pop(message.get("id"), (None, None))
+            if future and not future.done():
+                future.set_result(message)
+        reason = f"resident browser exited (code {proc.wait()}): {self.stderr_tail[-500:]}"
+        if not ready.done():
+            ready.set_exception(RuntimeError(reason))
+        with self.lock:
+            orphans = [key for key, (owner, _) in self.pending.items() if owner is proc]
+            futures = [self.pending.pop(key)[1] for key in orphans]
+        for future in futures:
+            if not future.done():
+                future.set_exception(BrowserExited(reason))
+
+    def _read_stderr(self, proc):
+        for line in proc.stderr:
+            self.stderr_tail = (self.stderr_tail + line)[-4000:]
+
+    def _kill(self, proc):
+        if proc.poll() is None:
+            if _IS_WINDOWS:
+                subprocess.run(["taskkill", "/PID", str(proc.pid), "/T", "/F"], capture_output=True,
+                               creationflags=subprocess.CREATE_NO_WINDOW)
+            else:
+                proc.kill()
+            try:
+                proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                pass
+        for stream in (proc.stdin, proc.stdout, proc.stderr):
+            try:
+                stream.close()
+            except (OSError, ValueError):
+                pass
+
+    def search(self, engine, query, num, timeout_s):
+        deadline = time.monotonic() + timeout_s
+        proc, writes = self._ensure_started(deadline)
+        left = deadline - time.monotonic()
+        if left < 1:
+            raise BrowserSkipped(f"{engine}: deadline used up while opening the browser")
+        request_id = uuid.uuid4().hex
+        future = concurrent.futures.Future()
+        with self.lock:
+            self.pending[request_id] = (proc, future)
+            self.last_used = time.monotonic()
+        writes.put(json.dumps({"id": request_id, "engine": engine, "query": query, "num": num,
+                               "expires_at": time.time() + left - 0.5}) + "\n")
+        try:
+            message = future.result(timeout=left + 2)
+        except concurrent.futures.TimeoutError:
+            with self.lock:
+                self.pending.pop(request_id, None)
+            raise TimeoutError(f"{engine}: resident browser did not respond in time") from None
+        finally:
+            with self.lock:
+                self.last_used = time.monotonic()
+        if message.get("captcha"):
+            raise BrowserCaptcha(message["error"])
+        if message.get("skipped"):
+            raise BrowserSkipped(message["error"])
+        if "error" in message:
+            raise RuntimeError(message["error"])
+        return message["results"]
+
+    def close(self):
+        with self.lock:
+            proc, writes, self.proc = self.proc, self.writes, None
+        if writes is not None:
+            writes.put(None)
+        if proc is not None:
+            self._kill(proc)

package/capabilities.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Probe de capacidades do Smart Tool (grafo/embedding/rerank), rodado no boot do daemon.
+
+Grafo: client-pure, mesmo contrato do Brain Server (`claude-code-boss/.../graph/daemon.js`) —
+lê o registry auto-anunciado em `~/.mcp-memory/run/daemon.json` e faz health-check em
+`{url}/health` (200 ou 503 = viva). Nunca spawna o daemon do grafo; se ausente/offline, falha
+aberto (graph=False), sem lançar exceção.
+"""
+import json
+import os
+import urllib.error
+import urllib.request
+
+import model_client
+
+BRAIN_RUN_DIR = os.environ.get("MCP_RUN_DIR") or os.path.join(
+    os.path.expanduser("~"), ".mcp-memory", "run"
+)
+BRAIN_REGISTRY_PATH = os.path.join(BRAIN_RUN_DIR, "daemon.json")
+
+
+class Capabilities:
+    def __init__(self, graph, embed, rerank):
+        self.graph = graph
+        self.embed = embed
+        self.rerank = rerank
+
+    def to_dict(self):
+        return {"graph": self.graph, "embed": self.embed, "rerank": self.rerank}
+
+
+def _probe_graph(timeout=2):
+    try:
+        with open(BRAIN_REGISTRY_PATH, "r", encoding="utf-8") as f:
+            info = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return False
+    url = info.get("url") if isinstance(info, dict) else None
+    if not url:
+        return False
+    try:
+        with urllib.request.urlopen(url.rstrip("/") + "/health", timeout=timeout) as resp:
+            return resp.status in (200, 503)
+    except (urllib.error.URLError, OSError, ValueError):
+        return False
+
+
+def _probe_embed_rerank():
+    token = model_client.get_token()
+    data = model_client.fetch("/v1/models", token)
+    ids = [row.get("id", "") for row in data.get("data", [])]
+    embed = any("embed" in i.lower() for i in ids)
+    rerank = any("rerank" in i.lower() for i in ids)
+    return embed, rerank
+
+
+def probe():
+    graph = _probe_graph()
+    try:
+        embed, rerank = _probe_embed_rerank()
+    except Exception:
+        embed, rerank = False, False
+    return Capabilities(graph, embed, rerank)

package/client_hooks.py

@@ -0,0 +1,192 @@
+import json
+import os
+import secrets
+import shutil
+import sys
+import time
+
+import daemon_launcher
+import endpoint_sync
+
+HOOK_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "hooks", "pretool_router.py")
+MARKER = "pretool_router.py"
+HTTP_PATH = "/hooks/pretool"
+HTTP_TIMEOUT_S = 15
+HOME = os.path.expanduser("~")
+PREVIEW_TTL_S = 600
+CLIENTS = {
+    "claude": {"label": "Claude Code", "names": {"claude-code"}, "files": [os.path.join(endpoint_sync.claude_dir(), "settings.json")],
+               "docs": "https://code.claude.com/docs/en/hooks", "event": "PreToolUse", "matcher": "Grep|Glob|Read|Bash|WebSearch|WebFetch", "http": True},
+    "codex": {"label": "Codex", "prefix": "codex", "files": [os.path.join(HOME, ".codex", "hooks.json"), os.path.join(HOME, ".codex", "config.toml")],
+              "docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash",
+              "after_install": "Codex only runs new hooks after the user approves the definition in /hooks."},
+    "cursor": {"label": "Cursor", "prefix": "cursor", "files": [os.path.join(HOME, ".cursor", "hooks.json")],
+               "docs": "https://cursor.com/docs/agent/hooks", "event": "preToolUse", "matcher": "Shell|Read|Grep",
+               "blocked": "In Cursor, `allow` approves the tool without the user and empty output blocks: there is no documented neutral "
+                          "response, so the hook is not installed automatically."},
+}
+_PREVIEWS = {}
+
+
+def identify(client_info):
+    name = str((client_info or {}).get("name") or "").casefold()
+    return next((key for key, spec in CLIENTS.items()
+                 if name in spec.get("names", ()) or (spec.get("prefix") and name.startswith(spec["prefix"]))), None)
+
+
+def _our_hook(hook):
+    return isinstance(hook, dict) and (MARKER in str(hook.get("command", "")) or HTTP_PATH in str(hook.get("url", "")))
+
+
+def _ours(group):
+    return isinstance(group, dict) and isinstance(group.get("hooks"), list) and any(map(_our_hook, group["hooks"]))
+
+
+def _without_ours(groups):
+    """Drops only our hook entries; a group shared with other hooks keeps them and disappears only when emptied."""
+    kept = []
+    for group in groups:
+        if not _ours(group):
+            kept.append(group)
+            continue
+        others = [hook for hook in group["hooks"] if not _our_hook(hook)]
+        if others:
+            kept.append({**group, "hooks": others})
+    return kept
+
+
+def installed(client):
+    """Our hook is present with the current matcher; an entry with an older matcher counts as missing."""
+    spec = CLIENTS[client]
+    for path in spec["files"]:
+        try:
+            with open(path, encoding="utf-8") as stream:
+                text = stream.read()
+        except FileNotFoundError:
+            continue
+        if MARKER not in text and HTTP_PATH not in text:
+            continue
+        if not path.endswith(".json"):
+            return True
+        data = json.loads(text)
+        hooks = data.get("hooks") if isinstance(data, dict) else None
+        groups = hooks.get(spec["event"]) if isinstance(hooks, dict) else None
+        expected = _handler(client)
+        return isinstance(groups, list) and any(
+            group.get("matcher") == spec["matcher"] and expected in group["hooks"] for group in groups if _ours(group))
+    return False
+
+
+def status(client_info):
+    client = identify(client_info)
+    if client is None:
+        return {"client": None, "name": (client_info or {}).get("name"), "installed": None, "error": None}
+    spec = CLIENTS[client]
+    try:
+        state, error = installed(client), None
+    except (OSError, ValueError) as exc:
+        state, error = None, f"{type(exc).__name__}: {exc}"[:200]
+    return {"client": client, "name": client_info.get("name"), "installed": state, "error": error,
+            "files": spec["files"], "docs": spec["docs"]}
+
+
+def notice(state):
+    if state["client"] is None:
+        return (f"Unrecognized MCP client ({state['name'] or 'no clientInfo'}): Smart Tool does not check the hook "
+                "that redirects Grep/Read to smart_search and WebSearch/WebFetch to web_search/web_fetch in this client.")
+    spec = CLIENTS[state["client"]]
+    if state["error"]:
+        return f"Could not check the Smart Tool hook in {spec['files'][0]}: {state['error']}"
+    if state["installed"]:
+        return None
+    action = spec.get("blocked") or ("If the user asks, use project_manage action=install_hook_preview, show the "
+                                     "change and confirm with action=install_hook (makes a backup).")
+    return (f"Smart Tool hook missing or outdated in {spec['label']} ({spec['files'][0]}): Grep/Read/Bash are not "
+            f"redirected to smart_search, nor WebSearch/WebFetch to web_search/web_fetch. {action} Docs: {spec['docs']}")
+
+
+def _shell_safe(path):
+    """Unquoted path that runs the same in cmd, PowerShell and bash (the Codex docs don't name the shell): forward
+    slashes (bash eats backslashes), no spaces (8.3 short name), no quotes (PowerShell reads a quoted head as a string)."""
+    if " " in path and sys.platform == "win32":
+        import ctypes
+        buffer = ctypes.create_unicode_buffer(1024)
+        if ctypes.windll.kernel32.GetShortPathNameW(path, buffer, len(buffer)):
+            path = buffer.value
+    if " " in path:
+        raise ValueError(f"Path contains a space and has no 8.3 short name ({path}); the hook was not installed.")
+    return path.replace("\\", "/")
+
+
+def _command(client):
+    return f"{_shell_safe(sys.executable)} {_shell_safe(HOOK_SCRIPT)} --client {client}"
+
+
+def _handler(client):
+    """Claude Code posts the payload straight to the warm daemon (`type: "http"`, no process per tool call); other
+    clients run the thin command that forwards to the same route."""
+    if CLIENTS[client].get("http"):
+        registry = daemon_launcher.read_registry()
+        if not registry or not registry.get("url"):
+            raise ValueError("Smart Tool daemon has no registered URL; start the daemon before installing the hook.")
+        return {"type": "http", "url": f"{registry['url']}{HTTP_PATH}?client={client}", "timeout": HTTP_TIMEOUT_S}
+    return {"type": "command", "command": _command(client), "timeout": HTTP_TIMEOUT_S}
+
+
+def _plan(client_info):
+    client = identify(client_info)
+    if client is None:
+        raise ValueError(f"Unrecognized MCP client ({(client_info or {}).get('name') or 'no clientInfo'}); "
+                         "the hook is only installed for Claude Code or Codex, from that client's own session.")
+    spec = CLIENTS[client]
+    if spec.get("blocked"):
+        raise ValueError(spec["blocked"] + f" Configure it manually if you want: {spec['docs']}")
+    path = os.path.realpath(spec["files"][0])
+    try:
+        with open(path, encoding="utf-8") as stream:
+            data = json.load(stream)
+    except FileNotFoundError:
+        data = {}
+    if not isinstance(data, dict) or not isinstance(data.setdefault("hooks", {}), dict):
+        raise ValueError(f"{path} does not have the expected format (object with 'hooks'); nothing was changed.")
+    groups = data["hooks"].setdefault(spec["event"], [])
+    if not isinstance(groups, list):
+        raise ValueError(f"{path}: hooks.{spec['event']} is not a list; nothing was changed.")
+    groups[:] = _without_ours(groups)
+    entry = {"matcher": spec["matcher"], "hooks": [_handler(client)]}
+    return client, spec, path, data, groups, entry
+
+
+def preview(client_info):
+    client, spec, path, _data, _groups, entry = _plan(client_info)
+    if installed(client):
+        return {"client": client, "installed": True, "file": path, "change": None}
+    token = secrets.token_urlsafe(12)
+    _PREVIEWS[token] = {"client": client, "at": time.time()}
+    return {"client": client, "installed": False, "file": path, "event": spec["event"], "change": entry,
+            "token": token, "expires_s": PREVIEW_TTL_S, "after_install": spec.get("after_install")}
+
+
+def install(client_info, token, confirm):
+    planned = _PREVIEWS.pop(token or "", None)
+    client, spec, path, data, groups, entry = _plan(client_info)
+    if confirm is not True or not planned or planned["client"] != client or time.time() - planned["at"] > PREVIEW_TTL_S:
+        raise ValueError("Installing requires the install_hook_preview token from this session (valid for 10 min) and confirm=true.")
+    if installed(client):
+        return {"client": client, "installed": True, "changed": False, "file": path}
+    groups.append(entry)
+    backup = None
+    if os.path.exists(path):
+        backup = f"{path}.smart-tool-backup-{time.strftime('%Y%m%d-%H%M%S')}"
+        shutil.copy2(path, backup)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temporary = path + ".smart-tool-tmp"
+    with open(temporary, "w", encoding="utf-8") as stream:
+        json.dump(data, stream, indent=2, ensure_ascii=False)
+    os.replace(temporary, path)
+    if not installed(client):
+        if backup:
+            shutil.copy2(backup, path)
+        raise RuntimeError(f"The hook does not appear in {path} after writing; the file was restored.")
+    return {"client": client, "installed": True, "changed": True, "file": path, "backup": backup,
+            "after_install": spec.get("after_install")}