@allansantos-dev/smart-tool 0.9.28 → 0.9.29

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.9.29 - beta
+
+- Registering the MCP server in Claude Code or Codex is idempotent. `claude mcp add` refuses a name that exists
+  ("MCP server smart-tool already exists in user"), so a second registration used to fail. Now the same URL runs
+  nothing and succeeds, another URL (the port changed) is removed with `claude mcp remove smart-tool --scope user`
+  (`codex mcp remove smart-tool`) and added again, and no entry only adds. The result is read back from the client's
+  configuration, as before.
+- The client CLI is resolved before it runs and never left hanging:
+  - Only `.exe`, `.cmd` and `.bat` are candidates, never a `.ps1` or the extensionless script npm leaves beside its
+    shims.
+  - A `.exe` that does not start with `MZ`, or an npm shim whose `claude-code` package holds such a file (Claude Code
+    installed by npm 11 with its postinstall blocked: a ~500-byte text `claude.exe`, which makes Windows open a modal
+    "not compatible" box and hang the command), fails at once with the reason and, for Claude Code,
+    `npm install -g @anthropic-ai/claude-code@latest --include=optional --allow-scripts=@anthropic-ai/claude-code`.
+  - The limit is 120 s (it was 60) and `SMART_TOOL_CLI_TIMEOUT_S` sets it.
+- The CLI is searched in the PATH as Windows stores it now (machine and user, from the registry), not the one the daemon
+  started with, and then in `%USERPROFILE%\.local\bin`, `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin` and `%APPDATA%\npm`.
+- Networks that inspect TLS with a corporate root CA:
+  - `npx ... install` shows the real error code (`SELF_SIGNED_CERT_IN_CHAIN`, kept by Node in `error.cause`, not
+    "fetch failed") and, on Node 22.15+/23.8+/24, runs itself again once with `NODE_USE_SYSTEM_CA=1`; otherwise it says
+    to set `NODE_EXTRA_CA_CERTS`. uv gets one retry with `UV_NATIVE_TLS=1` on a certificate error. The installer steps
+    (npm, Playwright) run with `NODE_USE_SYSTEM_CA=1`, and the Camoufox download uses the Windows store through
+    `truststore`. `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `UV_NATIVE_TLS` and
+    `NODE_USE_SYSTEM_CA` are never overwritten.
+  - The bootstrap ends by setting `process.exitCode` instead of calling `process.exit()` while a fetch is closing (Node
+    24 on Windows aborts with `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`).
+- Tests: `tests/test_cli_registration.py`, `tests/test_bootstrap_network.py`, and cases in `test_fetch_camoufox.py` and
+  `test_install_runtime.py`.
+
 ## 0.9.28 - beta
 
 - Node, npx and npm are looked up when they are needed, never remembered. A process keeps the PATH it was born with:

package/README.md

@@ -15,7 +15,7 @@ registered as the `playwright` server where this machine lets a browser be drive
 An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
 are cheaper, or just tells the agent what Smart Tool would do.
 
-**Status:** 0.9.28 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
+**Status:** 0.9.29 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
 
 ## How it works
 

package/bin/network.mjs

@@ -0,0 +1,78 @@
+// Network failures of the bootstrap on machines whose firewall inspects TLS (a corporate root CA in the Windows store,
+// unknown to Node's bundled certificates). Nothing here overwrites a TLS setting the user already made.
+
+export class Failure extends Error {}
+
+const CERTIFICATE_CODES = new Set([
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "CERT_UNTRUSTED",
+  "CERT_HAS_EXPIRED",
+]);
+const CERTIFICATE_TEXT = /certificate|UnknownIssuer|invalid peer|self[- ]signed/i;
+
+/** The real reason of a failed fetch: Node reports "fetch failed" and keeps the code in `error.cause`. */
+export function errorCode(error) {
+  return error?.cause?.code ?? error?.code ?? "unknown";
+}
+
+export function isCertificateError(error) {
+  return CERTIFICATE_CODES.has(errorCode(error));
+}
+
+/** Whether this Node can read the system certificate store through NODE_USE_SYSTEM_CA (22.15+, 23.8+). */
+export function supportsSystemCa(version = process.versions.node) {
+  const [major, minor] = version.split(".").map(Number);
+  return major >= 24 || (major === 23 && minor >= 8) || (major === 22 && minor >= 15);
+}
+
+/** The environment of a second run that trusts the system certificate store, or null when the user already chose
+ * (NODE_USE_SYSTEM_CA set to anything), this is already that second run, or this Node cannot do it. */
+export function systemCaEnvironment(env = process.env, version = process.versions.node) {
+  if (env.NODE_USE_SYSTEM_CA !== undefined || env.SMART_TOOL_SYSTEM_CA_RETRY || !supportsSystemCa(version)) return null;
+  return { ...env, NODE_USE_SYSTEM_CA: "1", SMART_TOOL_SYSTEM_CA_RETRY: "1" };
+}
+
+/** The environment for retrying uv with the Windows certificate store, or null when UV_NATIVE_TLS is already set. */
+export function nativeTlsEnvironment(env = process.env) {
+  return env.UV_NATIVE_TLS !== undefined ? null : { ...env, UV_NATIVE_TLS: "1" };
+}
+
+export function isCertificateText(text) {
+  return CERTIFICATE_TEXT.test(text);
+}
+
+export function certificateAdvice(env = process.env) {
+  const configured = ["NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "UV_NATIVE_TLS"].filter((name) => env[name]);
+  return "The network seems to inspect TLS with a certificate Node does not trust. Point NODE_EXTRA_CA_CERTS at the " +
+    "corporate root certificate (a .pem file), or use Node 22.15+ with NODE_USE_SYSTEM_CA=1 to trust the Windows " +
+    "certificate store." + (configured.length ? ` Already set here and left untouched: ${configured.join(", ")}.` : "");
+}
+
+export function describeFetchError(url, error, env = process.env) {
+  const code = errorCode(error);
+  const reason = error?.cause?.message ? `${error.message}: ${error.cause.message}` : String(error?.message ?? error);
+  return `download of ${url} failed (${code}): ${reason}` + (isCertificateError(error) ? `\n${certificateAdvice(env)}` : "");
+}
+
+/** Downloads url as a Buffer. A certificate failure first runs `rerun(environment)` once, a second run of the whole
+ * bootstrap that trusts the system store, and returns { rerun: result } when it did; otherwise it throws Failure with
+ * the error code and what to configure. */
+export async function download(url, { fetchFn = fetch, env = process.env, version = process.versions.node, rerun } = {}) {
+  let response;
+  try {
+    response = await fetchFn(url);
+  } catch (error) {
+    const retry = isCertificateError(error) && rerun ? systemCaEnvironment(env, version) : null;
+    if (retry) {
+      console.log(`TLS inspection detected (${errorCode(error)}); running again with the Windows certificate store...`);
+      return { rerun: rerun(retry) };
+    }
+    throw new Failure(describeFetchError(url, error, env));
+  }
+  if (!response.ok) throw new Failure(`download of ${url} failed: HTTP ${response.status}`);
+  return { body: Buffer.from(await response.arrayBuffer()) };
+}

package/bin/smart-tool.mjs

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { Failure, certificateAdvice, download, isCertificateText, nativeTlsEnvironment } from "./network.mjs";
 
 const PACKAGE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
 const RUNTIME_DIR = join(homedir(), ".smart-tool", "runtime");
@@ -20,8 +21,7 @@ const USAGE = `Usage: npx @allansantos-dev/smart-tool install [--target DIR] [--
 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);
+  throw new Failure(message);
 }
 
 function run(command, args, options = {}) {
@@ -31,13 +31,18 @@ function run(command, args, options = {}) {
   return (result.stdout || "").trim();
 }
 
+function runAgain(env) {
+  const again = spawnSync(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], { stdio: "inherit", env });
+  if (again.error) fail(`could not run again: ${again.error.message}`);
+  return again.status ?? 1;
+}
+
 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 { body: archive, rerun } = await download(url, { rerun: runAgain });
+  if (rerun !== undefined) return { rerun };
   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-"));
@@ -55,7 +60,17 @@ async function ensureUv() {
 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 install = ["python", "install", PYTHON_VERSION, "--no-bin", "--no-registry"];
+  try {
+    run(UV_EXE, install, { env });
+  } catch (error) {
+    const native = nativeTlsEnvironment(env);
+    if (!(error instanceof Failure) || !isCertificateText(error.message)) throw error;
+    if (!native) throw new Failure(`${error.message}\n${certificateAdvice(env)}`);
+    console.log("TLS inspection detected by uv; running it again with the Windows certificate store...");
+    env.UV_NATIVE_TLS = native.UV_NATIVE_TLS;
+    run(UV_EXE, install, { 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;
@@ -69,10 +84,15 @@ async function main() {
   }
   if (command !== "install") {
     console.log(USAGE);
-    process.exit(command === undefined || command === "--help" || command === "-h" ? 0 : 1);
+    process.exitCode = command === undefined || command === "--help" || command === "-h" ? 0 : 1;
+    return;
   }
   if (process.platform !== "win32" || process.arch !== "x64") fail(`Smart Tool runs on Windows x64 only (this is ${process.platform}-${process.arch}).`);
-  await ensureUv();
+  const again = await ensureUv();
+  if (again) {
+    process.exitCode = again.rerun;
+    return;
+  }
   const python = ensurePython();
   const installer = spawnSync(python, [join(PACKAGE_DIR, "install.py"), "--skip-tests", ...rest], {
     stdio: "inherit",
@@ -80,7 +100,10 @@ async function main() {
     env: { ...process.env, PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
   });
   if (installer.error) fail(`the installer did not start: ${installer.error.message}`);
-  process.exit(installer.status ?? 1);
+  process.exitCode = installer.status ?? 1;
 }
 
-main().catch((error) => fail(error.stack || String(error)));
+main().catch((error) => {
+  console.error(error instanceof Failure ? `smart-tool: ${error.message}` : `smart-tool: ${error.stack || error}`);
+  process.exitCode = 1;
+});

package/endpoint_sync.py

@@ -8,11 +8,12 @@ Cada arquivo é relido logo antes da gravação atômica: o Claude Code reescrev
 import json
 import os
 import re
-import shutil
 import subprocess
 import time
 import urllib.parse
 
+import node_locator
+
 SERVER = "smart-tool"
 HOOK_PATH = "/hooks/pretool"
 POST_HOOK_PATH = "/hooks/posttool"
@@ -110,7 +111,11 @@ def registrations():
     return found
 
 
-REGISTER_TIMEOUT_S = 60
+REGISTER_TIMEOUT_S = 120
+TIMEOUT_ENV = "SMART_TOOL_CLI_TIMEOUT_S"
+CLI_EXTENSIONS = (".exe", ".cmd", ".bat")
+NPM_CLAUDE_FIX = "npm install -g @anthropic-ai/claude-code@latest --include=optional --allow-scripts=@anthropic-ai/claude-code"
+_NPM_CLAUDE_BINARY = os.path.join("node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe")
 _CMD_METACHARS = re.compile(r'[&|<>^%!"\r\n]')
 
 
@@ -124,21 +129,99 @@ def register_command(client, base):
     raise ValueError(f"Client without MCP registration: {client!r}")
 
 
+def remove_command(client):
+    """Official CLI command that removes the smart-tool MCP server a client holds."""
+    if client == "claude":
+        return ["claude", "mcp", "remove", SERVER, "--scope", "user"]
+    if client == "codex":
+        return ["codex", "mcp", "remove", SERVER]
+    raise ValueError(f"Client without MCP registration: {client!r}")
+
+
 def register(client, base):
-    """Runs the client's own CLI (it owns its config file; ~/.claude.json is rewritten by Claude Code all the time)."""
+    """Makes the client's smart-tool MCP entry point to base, through the client's own CLI (it owns its config file;
+    ~/.claude.json is rewritten by Claude Code all the time). Idempotent: the same URL runs nothing, another URL (the
+    port changed) is removed first because `mcp add` refuses an existing name, no entry only adds. Returns what was run."""
+    url = f"{base}/mcp"
+    current = registrations().get(client)
+    if current == url:
+        return f"nothing to run: {client} already points to {url}"
     command = register_command(client, base)
+    if current:
+        run_cli(remove_command(client))
     run_cli(command)
-    if registrations().get(client) != f"{base}/mcp":
+    if registrations().get(client) != url:
         raise RuntimeError(f"'{' '.join(command)}' finished, but the registration did not appear in the client's configuration.")
     return " ".join(command)
 
 
+def cli_folders():
+    """Where the native installers of the clients put their CLI, for a PATH that does not list them."""
+    home, local, roaming = os.path.expanduser("~"), os.environ.get("LOCALAPPDATA"), os.environ.get("APPDATA")
+    folders = [os.path.join(home, ".local", "bin")]
+    if local:
+        folders.append(os.path.join(local, "Programs", "OpenAI", "Codex", "bin"))
+    if roaming:
+        folders.append(os.path.join(roaming, "npm"))
+    return folders
+
+
+def resolve_cli(name):
+    """Full path of the client CLI `name` as a .exe, .cmd or .bat (never a .ps1 or the extensionless script npm leaves
+    beside its shims, which Windows cannot run), looked up in the PATH as Windows stores it now and then in cli_folders;
+    None when absent."""
+    for folder in node_locator.search_path() + cli_folders():
+        for extension in CLI_EXTENSIONS:
+            path = os.path.join(folder, name + extension)
+            if os.path.isfile(path):
+                return path
+    return None
+
+
+def _is_native(path):
+    with open(path, "rb") as stream:
+        return stream.read(2) == b"MZ"
+
+
+def check_runnable(executable):
+    """Raises RuntimeError, without running anything, when executable is a .exe that is not a Windows program or an npm
+    shim whose package holds such a file: Windows answers those with a modal "not compatible" box and the command hangs.
+    That is how Claude Code installed by npm 11 ends up when its postinstall is blocked (a ~500-byte text claude.exe)."""
+    if executable.lower().endswith(".exe"):
+        broken = executable if not _is_native(executable) else None
+    else:
+        package_binary = os.path.join(os.path.dirname(executable), _NPM_CLAUDE_BINARY)
+        broken = package_binary if os.path.isfile(package_binary) and not _is_native(package_binary) else None
+    if not broken:
+        return
+    if os.path.join("@anthropic-ai", "claude-code") in broken:
+        raise RuntimeError(f"Claude Code was installed by npm without its native binary ({broken} is a text file). "
+                           f"Run: {NPM_CLAUDE_FIX}")
+    raise RuntimeError(f"{broken} is not a Windows executable (it does not start with MZ); reinstall that CLI.")
+
+
+def cli_timeout_s():
+    """Seconds a client CLI may run: SMART_TOOL_CLI_TIMEOUT_S when set (a positive number), else REGISTER_TIMEOUT_S."""
+    raw = os.environ.get(TIMEOUT_ENV)
+    if raw is None:
+        return REGISTER_TIMEOUT_S
+    try:
+        seconds = float(raw)
+    except ValueError:
+        seconds = 0
+    if seconds <= 0:
+        raise RuntimeError(f"{TIMEOUT_ENV} must be a positive number of seconds, not {raw!r}.")
+    return seconds
+
+
 def run_cli(command):
-    """Runs a client CLI command (claude, codex) found on PATH, killing its whole shim tree after REGISTER_TIMEOUT_S.
-    Raises RuntimeError with the command and the CLI's own message when it is missing, hangs or exits non-zero."""
-    executable = shutil.which(command[0])
+    """Runs a client CLI command (claude, codex) found by resolve_cli, killing its whole shim tree after cli_timeout_s.
+    Raises RuntimeError with the command and the CLI's own message when it is missing, cannot run, hangs or exits non-zero."""
+    executable = resolve_cli(command[0])
     if not executable:
         raise RuntimeError(f"CLI '{command[0]}' not found in Smart Tool's PATH. Register it manually: {' '.join(command)}")
+    check_runnable(executable)
+    timeout = cli_timeout_s()
     unsafe = [arg for arg in command[1:] if _CMD_METACHARS.search(arg)]
     if executable.lower().endswith((".cmd", ".bat")) and unsafe:
         # cmd.exe parses a .cmd shim's arguments again: & | < > ^ % ! would run as commands or expand as variables.
@@ -152,7 +235,7 @@ def run_cli(command):
     except OSError as exc:
         raise RuntimeError(f"'{' '.join(command)}' did not start: {exc}") from None
     try:
-        stdout, stderr = proc.communicate(timeout=REGISTER_TIMEOUT_S)
+        stdout, stderr = proc.communicate(timeout=timeout)
     except subprocess.TimeoutExpired:
         # npm shims are cmd.exe -> node: killing only cmd.exe leaves node holding the pipes forever.
         if os.name == "nt":
@@ -160,7 +243,7 @@ def run_cli(command):
         else:
             proc.kill()
         proc.communicate(timeout=10)
-        raise RuntimeError(f"'{' '.join(command)}' did not finish in {REGISTER_TIMEOUT_S}s.") from None
+        raise RuntimeError(f"'{' '.join(command)}' did not finish in {timeout:g}s.") from None
     if proc.returncode != 0:
         detail = (stderr or stdout).strip()[-400:]
         raise RuntimeError(f"'{' '.join(command)}' failed (code {proc.returncode}): {detail}")

package/install_runtime.py

@@ -176,6 +176,7 @@ def _run(args, *, cwd=None, label="Web dependency", idle_s=600, stream=False, at
     node, _npm = _node_commands()
     env = node_locator.environment(prefer=node)
     env.update(PYTHONUTF8="1", PYTHONIOENCODING="utf-8")
+    env.setdefault("NODE_USE_SYSTEM_CA", "1")
     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)
@@ -256,7 +257,7 @@ def _check():
     if status["browser_python"]:
         try:
             result = subprocess.run(
-                [str(BROWSER_PYTHON), "-c", "import camoufox, crawl4ai, playwright"],
+                [str(BROWSER_PYTHON), "-c", "import camoufox, crawl4ai, playwright, truststore"],
                 capture_output=True, check=False, timeout=30,
             )
             status["browser_packages"] = result.returncode == 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.28",
+  "version": "0.9.29",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/version.py

@@ -1,7 +1,7 @@
 """Single source of the Smart Tool version and of the User-Agent sent to public APIs."""
 import re
 
-VERSION = "0.9.28"
+VERSION = "0.9.29"
 _CONTACT_RE = re.compile(r"^(?:[^\s@()<>;]+@[^\s@()<>;]+\.[^\s@()<>;]+|https?://[^\s()<>;]+)$")
 
 

package/web_adapters/browser/fetch_camoufox.py

@@ -2,7 +2,10 @@
 caught here and turned into a failing exit, and the browser executable must exist afterwards. The 1.3 GB download
 goes through ranged_download (Range requests that resume after a dropped or stalled connection; camoufox still checks
 the sha256), its other requests get a timeout (requests passes None, which also overrides socket.setdefaulttimeout),
-and progress is printed as plain lines (the rich bar stays invisible in a pipe)."""
+and progress is printed as plain lines (the rich bar stays invisible in a pipe). requests trusts only certifi's bundle, so on
+a network that inspects TLS with a corporate root CA its release lookups fail; the Windows certificate store is used
+instead (truststore), unless the user already set a CA bundle variable."""
+import os
 import sys
 from io import BytesIO
 from pathlib import Path
@@ -14,6 +17,7 @@ from camoufox import pkgman
 import ranged_download
 
 TIMEOUT_S = (30, 60)
+CA_VARIABLES = ("REQUESTS_CA_BUNDLE", "SSL_CERT_FILE", "CURL_CA_BUNDLE")
 REPORT_EVERY_MB = 50
 _update = camoufox_cli.CamoufoxUpdate.update
 _get = requests.get
@@ -59,7 +63,18 @@ def installed_executable():
     return executable
 
 
+def trust_system_certificates():
+    """Makes ssl (and so requests) verify against the Windows certificate store; False and untouched when the user set
+    REQUESTS_CA_BUNDLE, SSL_CERT_FILE or CURL_CA_BUNDLE."""
+    if any(os.environ.get(name) for name in CA_VARIABLES):
+        return False
+    import truststore
+    truststore.inject_into_ssl()
+    return True
+
+
 def main():
+    trust_system_certificates()
     requests.get = _get_with_timeout
     pkgman.webdl = _ranged_webdl
     camoufox_cli.CamoufoxUpdate.update = _recording_update

package/web_adapters/browser/requirements.txt

@@ -1,2 +1,3 @@
 camoufox==0.5.6
+truststore==0.10.5
 crawl4ai==0.9.3