ixt-cli 0.8.0__py3-none-any.whl

ixt/backends/node.py

@@ -0,0 +1,490 @@
+"""Node backend — isolated node_modules per tool via bun (npm fallback).
+
+Binaries are discovered from ``node_modules/.bin/`` which is the ecosystem's
+source of truth — bun and npm both populate it with correct shebangs, NODE_PATH,
+and entries from postinstall scripts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ixt.config.settings import Settings, get_settings
+from ixt.core.backend import BackendType
+from ixt.libs.logger import get_logger
+from ixt.libs.shell import ShellError, command_exists, shell_run
+from ixt.platform import is_windows
+
+# Matches `node` as a standalone token in a shebang line:
+#   #!/usr/bin/env node             → match
+#   #!/usr/bin/env -S node --harmony → match
+#   #!/usr/bin/nodejs               → no match (false positive avoided)
+#   #!/usr/bin/env nodemon          → no match
+_NODE_SHEBANG_RE = re.compile(rb"^#!.*\bnode\b")
+
+# ---------------------------------------------------------------------------
+# npm spec helpers
+# ---------------------------------------------------------------------------
+
+
+def parse_npm_spec(spec: str) -> tuple[str, str | None]:
+    """Parse an npm package spec into (name, version_or_None).
+
+    Handles:
+      - ``@scope/pkg@1.2.3`` → (``@scope/pkg``, ``1.2.3``)
+      - ``@scope/pkg``       → (``@scope/pkg``, None)
+      - ``pkg@^5.0``         → (``pkg``, ``^5.0``)
+      - ``pkg``              → (``pkg``, None)
+    """
+    s = spec.strip()
+    if s.startswith("@"):
+        # Scoped: find the second @ (version separator)
+        rest = s[1:]
+        if "/" not in rest:
+            return s, None
+        slash_idx = rest.index("/")
+        after_slash = rest[slash_idx + 1 :]
+        if "@" in after_slash:
+            at_idx = after_slash.index("@")
+            name = s[: 1 + slash_idx + 1 + at_idx]
+            version = after_slash[at_idx + 1 :]
+            return name, version or None
+        return s, None
+    # Unscoped
+    if "@" in s:
+        name, version = s.split("@", 1)
+        return name, version or None
+    return s, None
+
+
+# ---------------------------------------------------------------------------
+# Metadata
+# ---------------------------------------------------------------------------
+
+_META_FILE = "node_metadata.json"
+
+
+def _encode_path_under_env(path: str, env_dir: Path) -> str:
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        return path
+    try:
+        return str(candidate.absolute().relative_to(env_dir.absolute()))
+    except ValueError:
+        return path
+
+
+def _decode_path_from_env(path: str, env_dir: Path) -> str:
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return path
+    return str(env_dir / candidate)
+
+
+def _existing_metadata_binaries(meta: dict) -> dict[str, str]:
+    binaries = meta.get("binaries", {})
+    if not isinstance(binaries, dict):
+        return {}
+    existing: dict[str, str] = {}
+    for name, bin_path in binaries.items():
+        path = Path(bin_path)
+        if path.exists():
+            existing[str(name)] = str(path)
+    return existing
+
+
+def _write_metadata(
+    env_dir: Path,
+    *,
+    spec: str,
+    package_name: str,
+    version: str | None,
+    binaries: dict[str, str],
+    used_npm_fallback: bool = False,
+    runtime: str | None = None,
+) -> Path:
+    path = env_dir / _META_FILE
+    data = {
+        "spec": spec,
+        "package_name": package_name,
+        "version": version,
+        "binaries": {
+            name: _encode_path_under_env(path, env_dir)
+            for name, path in binaries.items()
+        },
+        "used_npm_fallback": used_npm_fallback,
+        "runtime": runtime,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    return path
+
+
+def read_metadata(env_dir: Path) -> dict | None:
+    path = env_dir / _META_FILE
+    if not path.exists():
+        return None
+    with path.open(encoding="utf-8") as f:
+        data = json.load(f)
+    binaries = data.get("binaries")
+    if isinstance(binaries, dict):
+        data["binaries"] = {
+            name: _decode_path_from_env(path, env_dir)
+            for name, path in binaries.items()
+        }
+    return data
+
+
+# ---------------------------------------------------------------------------
+# node_modules/.bin — ecosystem source of truth
+# ---------------------------------------------------------------------------
+
+
+def _dot_bin_dir(env_dir: Path) -> Path:
+    """Return ``node_modules/.bin/`` — populated by bun/npm with correct wrappers."""
+    return env_dir / "node_modules" / ".bin"
+
+
+def _list_dot_bin(env_dir: Path) -> list[Path]:
+    """List executable entries in ``node_modules/.bin/``."""
+    dot_bin = _dot_bin_dir(env_dir)
+    if not dot_bin.exists():
+        return []
+    if is_windows():
+        # On Windows, bun/npm create .cmd wrappers
+        return sorted(
+            p for p in dot_bin.iterdir() if p.is_file() and p.suffix.lower() in {".cmd", ".exe"}
+        )
+    return sorted(
+        p
+        for p in dot_bin.iterdir()
+        if p.is_file() and os.access(p, os.X_OK) and not p.name.endswith(".cmd")
+    )
+
+
+# ---------------------------------------------------------------------------
+# Node shebang shim (bun-as-node when host has no node)
+# ---------------------------------------------------------------------------
+
+
+def _shim_node_shebangs(env_dir: Path, bun_path: str) -> list[str]:
+    """Rewrite ``#!...node`` shebangs to bun inside the tool's env.
+
+    Rationale: many npm packages (biome, prettier, …) ship a JS entrypoint
+    with ``#!/usr/bin/env node`` in their ``bin`` scripts. bun installs them
+    fine but the scripts fail at runtime if host has no node. bun itself is
+    a Node-compatible runtime, so rewriting the shebang to an absolute bun
+    path makes the tool self-contained — ixt's isolation stays intact.
+
+    Safety:
+        - Only acts when host has no ``node`` on PATH (no need to shim
+          otherwise, and users explicitly on node get their runtime).
+        - Breaks bun's global-cache hardlink before rewriting (unlink +
+          rewrite) so we never pollute ``~/.bun/install/cache``.
+
+    Returns the list of ``.bin/`` entry names whose real script was
+    rewritten (for a user-facing warning).
+    """
+    if shutil.which("node"):
+        return []
+
+    rewritten: list[str] = []
+    bin_dir = _dot_bin_dir(env_dir)
+    if not bin_dir.exists():
+        return rewritten
+
+    seen_targets: set[Path] = set()
+    for entry in bin_dir.iterdir():
+        if not entry.is_file():
+            continue
+        try:
+            target = entry.resolve()
+        except (OSError, RuntimeError):
+            continue
+        if target in seen_targets or not target.is_file():
+            continue
+        seen_targets.add(target)
+
+        try:
+            content = target.read_bytes()
+        except OSError:
+            continue
+
+        if not content.startswith(b"#!"):
+            continue
+        nl = content.find(b"\n")
+        if nl == -1:
+            continue
+        first_line = content[:nl]
+        if not _NODE_SHEBANG_RE.match(first_line):
+            continue
+
+        # Break potential hardlink to bun's global cache, then rewrite.
+        mode = target.stat().st_mode
+        new_content = f"#!{bun_path}".encode() + content[nl:]
+        target.unlink()
+        target.write_bytes(new_content)
+        target.chmod(mode)
+        rewritten.append(entry.name)
+
+    return rewritten
+
+
+# ---------------------------------------------------------------------------
+# Package introspection
+# ---------------------------------------------------------------------------
+
+
+def _read_package_json(env_dir: Path, package_name: str) -> dict | None:
+    """Read the installed package's package.json."""
+    pkg_json = env_dir / "node_modules" / package_name / "package.json"
+    if not pkg_json.exists():
+        return None
+    with pkg_json.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _get_bin_entries(pkg_data: dict, package_name: str) -> dict[str, str]:
+    """Extract ``bin`` entries from package.json.
+
+    Returns ``{binary_name: relative_path}``.
+    """
+    raw = pkg_data.get("bin")
+    if raw is None:
+        return {}
+    if isinstance(raw, str):
+        # Single binary → use package short name
+        short = package_name.rsplit("/", 1)[-1]
+        return {short: raw}
+    if isinstance(raw, dict):
+        return dict(raw)
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# NodeBackend
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class NodeBackend:
+    """Install Node CLI tools in isolated node_modules via ``bun``."""
+
+    settings: Settings = field(default_factory=get_settings)
+    backend_type: BackendType = field(default=BackendType.NODE, init=False)
+
+    # -- runtime helpers ----------------------------------------------------
+
+    def _bun(self) -> str:
+        from ixt.core.bootstrap import ensure_bun
+
+        return ensure_bun(self.settings)
+
+    def _npm_available(self) -> bool:
+        return command_exists("npm")
+
+    # -- Backend protocol ---------------------------------------------------
+
+    def env_exists(self, env_dir: Path) -> bool:
+        return (env_dir / "node_modules").is_dir()
+
+    def create_env(self, env_dir: Path) -> bool:
+        if env_dir.exists() and self.env_exists(env_dir):
+            return False
+        env_dir.mkdir(parents=True, exist_ok=True)
+        # Minimal package.json so bun/npm has a project root.
+        pkg_json = env_dir / "package.json"
+        if not pkg_json.exists():
+            pkg_json.write_text(
+                json.dumps({"private": True, "dependencies": {}}, indent=2) + "\n",
+                encoding="utf-8",
+            )
+        return True
+
+    def install_packages(
+        self,
+        env_dir: Path,
+        specs: list[str],
+        *,
+        upgrade: bool = False,
+        runtime: str | None = None,
+        node_shim: bool | None = None,
+    ) -> None:
+        if not specs:
+            return
+
+        main_spec = specs[0]
+        pkg_name, _version = parse_npm_spec(main_spec)
+
+        used_npm = self._run_install_command(env_dir, specs, runtime=runtime, upgrade=upgrade)
+        pkg_data, used_npm = self._verify_and_retry_with_npm(env_dir, pkg_name, specs, used_npm)
+
+        self._maybe_shim_node_shebangs(env_dir, used_npm=used_npm, node_shim=node_shim)
+
+        binaries = {p.stem: str(p) for p in _list_dot_bin(env_dir)}
+
+        _write_metadata(
+            env_dir,
+            spec=main_spec,
+            package_name=pkg_name,
+            version=pkg_data.get("version") if pkg_data else None,
+            binaries=binaries,
+            used_npm_fallback=used_npm,
+            runtime=runtime,
+        )
+
+    def _run_install_command(
+        self,
+        env_dir: Path,
+        specs: list[str],
+        *,
+        runtime: str | None,
+        upgrade: bool,
+    ) -> bool:
+        """Run the install via bun (default) or npm (explicit --runtime=node).
+
+        Returns True when npm was used (directly or as a bun-failure fallback).
+        """
+        log = get_logger("node")
+
+        if runtime == "node":
+            if not self._npm_available():
+                raise RuntimeError(
+                    "Requested --runtime=node but npm is not available.\n"
+                    "  Hint: Install Node.js/npm: https://nodejs.org"
+                )
+            log.debug(f"npm install (--runtime=node): {' '.join(specs)}")
+            cmd = ["npm", "install", "--no-fund", "--no-audit", *specs]
+            shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
+            return True
+
+        try:
+            bun = self._bun()
+            cmd = [bun, "add", *(["--force"] if upgrade else []), *specs]
+            log.debug(f"bun add: {' '.join(specs)}")
+            shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
+            return False
+        except (ShellError, Exception) as exc:
+            if not self._npm_available():
+                raise RuntimeError(
+                    f"bun install failed and npm is not available.\n"
+                    f"  bun error: {exc}\n"
+                    f"  Hint: Install Node.js/npm to enable fallback: https://nodejs.org"
+                ) from exc
+            log.debug(f"bun failed, falling back to npm: {exc}")
+            cmd = ["npm", "install", "--no-fund", "--no-audit", *specs]
+            shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
+            return True
+
+    def _verify_and_retry_with_npm(
+        self,
+        env_dir: Path,
+        pkg_name: str,
+        specs: list[str],
+        used_npm: bool,
+    ) -> tuple[dict | None, bool]:
+        """Verify package.json is present; retry with npm if bun silently failed."""
+        pkg_data = _read_package_json(env_dir, pkg_name)
+        if pkg_data is None and not used_npm and self._npm_available():
+            get_logger("node").debug("Package not found after bun install, retrying with npm")
+            cmd = ["npm", "install", "--no-fund", "--no-audit", *specs]
+            shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
+            return _read_package_json(env_dir, pkg_name), True
+        return pkg_data, used_npm
+
+    def _maybe_shim_node_shebangs(
+        self,
+        env_dir: Path,
+        *,
+        used_npm: bool,
+        node_shim: bool | None,
+    ) -> None:
+        """Rewrite #!node shebangs to bun when bun installed and host has no node.
+
+        Keeps the tool self-contained without requiring node on the host.
+        """
+        if used_npm or node_shim is False:
+            return
+        log = get_logger("node")
+        try:
+            bun_for_shim = self._bun()
+            rewritten = _shim_node_shebangs(env_dir, bun_for_shim)
+        except (OSError, ShellError) as exc:
+            log.debug(f"node shebang shim skipped: {exc}")
+            return
+        if rewritten:
+            log.warn(
+                "node not found on host — rewrote shebangs to bun for: "
+                f"{', '.join(rewritten)}. bun runs these as a "
+                "Node-compatible runtime; install Node.js on the host "
+                "if the tool misbehaves."
+            )
+
+    def uninstall_package(self, env_dir: Path, package: str) -> None:
+        """No-op: Node envs are atomic; full removal is handled by the caller."""
+
+    def find_binaries(self, env_dir: Path) -> list[Path]:
+        """Return all executables in ``node_modules/.bin/``."""
+        return _list_dot_bin(env_dir)
+
+    def get_package_binaries(self, env_dir: Path, package_name: str) -> dict[str, str]:
+        """Return binaries declared by *package_name* (not transitive deps).
+
+        Uses package.json ``bin`` field to filter ``node_modules/.bin/``
+        entries that belong to this specific package.  Falls back to
+        metadata or full ``.bin/`` listing.
+        """
+        # Primary: match package.json "bin" entries against .bin/ contents
+        pkg_data = _read_package_json(env_dir, package_name)
+        if pkg_data is not None:
+            declared = _get_bin_entries(pkg_data, package_name)
+            if declared:
+                dot_bin = _dot_bin_dir(env_dir)
+                result: dict[str, str] = {}
+                for name in declared:
+                    candidate = dot_bin / name
+                    if is_windows():
+                        candidate = dot_bin / f"{name}.cmd"
+                    if candidate.exists():
+                        result[name] = str(candidate)
+                if result:
+                    return result
+
+        # Fallback: metadata (covers postinstall-generated binaries)
+        meta = read_metadata(env_dir)
+        if meta and meta.get("binaries"):
+            existing = _existing_metadata_binaries(meta)
+            if existing:
+                return existing
+
+        # Last resort: everything in .bin/
+        return {p.stem: str(p) for p in _list_dot_bin(env_dir)}
+
+    def installed_version(self, env_dir: Path, package_name: str) -> str | None:
+        # Fast path: metadata
+        meta = read_metadata(env_dir)
+        if meta and meta.get("version"):
+            return meta["version"]
+
+        # Slow path: read package.json
+        pkg_data = _read_package_json(env_dir, package_name)
+        if pkg_data is None:
+            return None
+        return pkg_data.get("version")
+
+    def export(self, env_dir: Path) -> list[str]:
+        meta = read_metadata(env_dir)
+        if meta is None:
+            return []
+        name = meta.get("package_name", "")
+        version = meta.get("version", "")
+        if name and version:
+            return [f"{name}@{version}"]
+        return []