codeboarding 0.9.4__tar.gz → 0.9.5__tar.gz

{codeboarding-0.9.4/codeboarding.egg-info → codeboarding-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.9.4
+Version: 0.9.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License: MIT

codeboarding-0.9.5/README.md

@@ -0,0 +1,149 @@
+# CodeBoarding
+
+See what your AI is building before it breaks.
+
+CodeBoarding gives developers and coding agents a visual map of a codebase. It combines static analysis with LLM reasoning to generate architecture diagrams, component-level documentation, and navigable outputs you can use in your IDE, CI, and docs.
+
+[Website](https://codeboarding.org) · [Open VSX extension](https://open-vsx.org/extension/CodeBoarding/codeboarding) · [Explore examples](https://codeboarding.org/diagrams) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) · [GitHub Action](https://github.com/marketplace/actions/codeboarding-diagram-first-documentation) ·[Discord](https://discord.gg/T5zHTJYFuy)
+
+[![CodeBoarding demo](docs/assets/codeboarding-demo.gif)](https://open-vsx.org/extension/CodeBoarding/codeboarding)
+
+Install the extension from Open VSX.
+
+[![JavaScript](https://img.shields.io/badge/JavaScript-222222?style=flat-square&logo=javascript&logoColor=F7DF1E)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Java](https://img.shields.io/badge/Java-E76F00?style=flat-square&logo=openjdk&logoColor=white)](https://www.java.com/)
+[![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Go](https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev/)
+[![PHP](https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white)](https://www.php.net/)
+
+## Few use cases:
+
+- Keep architecture visible while agents code.
+- Review AI-generated changes with system context before they turn into hidden debt.
+- Understand large repositories faster with layered diagrams and component breakdowns.
+- Share the same visual model across local workflows, IDEs, pull requests, and docs.
+
+## What CodeBoarding generates
+
+- High-level system architecture diagrams.
+- Deeper component diagrams for important subsystems.
+- Markdown documentation in `.codeboarding/`.
+- Mermaid output that is easy to embed in docs and PRs.
+- Incremental updates when only part of the codebase changes.
+
+## How it works
+
+```mermaid
+graph LR
+    Application_Orchestrator_Repository_Manager["Application Orchestrator & Repository Manager"]
+    LLM_Agent_Core["LLM Agent Core"]
+    Static_Code_Analyzer["Static Code Analyzer"]
+    Agent_Tooling_Interface["Agent Tooling Interface"]
+    Incremental_Analysis_Engine["Incremental Analysis Engine"]
+    Documentation_Diagram_Generator["Documentation & Diagram Generator"]
+    Application_Orchestrator_Repository_Manager -- "Orchestrator initiates analysis workflow, leveraging incremental updates based on detected code changes." --> Incremental_Analysis_Engine
+    Application_Orchestrator_Repository_Manager -- "Orchestrator passes project context and triggers the main analysis workflow for the LLM Agent." --> LLM_Agent_Core
+    Incremental_Analysis_Engine -- "Incremental engine requests static analysis for specific code segments (new or changed)." --> Static_Code_Analyzer
+    Static_Code_Analyzer -- "Static analyzer provides analysis results to the incremental engine for caching." --> Incremental_Analysis_Engine
+    LLM_Agent_Core -- "LLM Agent invokes specialized tools to interact with the codebase and analysis data." --> Agent_Tooling_Interface
+    Agent_Tooling_Interface -- "Agent tools query the static analysis engine for detailed code insights." --> Static_Code_Analyzer
+    Static_Code_Analyzer -- "Static analysis engine provides requested data to the agent tools." --> Agent_Tooling_Interface
+    LLM_Agent_Core -- "LLM Agent delivers structured analysis insights for documentation and diagram generation." --> Documentation_Diagram_Generator
+    click Application_Orchestrator_Repository_Manager href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Application_Orchestrator_Repository_Manager.md" "Details"
+    click LLM_Agent_Core href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/LLM_Agent_Core.md" "Details"
+    click Static_Code_Analyzer href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Static_Code_Analyzer.md" "Details"
+    click Agent_Tooling_Interface href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Agent_Tooling_Interface.md" "Details"
+    click Incremental_Analysis_Engine href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Incremental_Analysis_Engine.md" "Details"
+    click Documentation_Diagram_Generator href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Documentation_Diagram_Generator.md" "Details"
+```
+
+For a deeper architecture walkthrough, see [`.codeboarding/overview.md`](.codeboarding/overview.md).
+
+## Quick start
+
+### Run from source
+
+```bash
+uv sync --frozen
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python install.py
+python main.py --local /path/to/repo
+```
+
+### Use the packaged CLI
+
+```bash
+pip install codeboarding
+codeboarding-setup
+codeboarding --local /path/to/repo
+```
+
+Output is written to `/path/to/repo/.codeboarding/`.
+
+`python install.py` and `codeboarding-setup` download language server binaries to `~/.codeboarding/servers/`, shared across projects. `npm` is required for Python, TypeScript, JavaScript, and PHP language servers; if it is missing, setup can install it via `nodeenv`.
+
+## Configuration
+
+On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provider there or use environment variables.
+
+```toml
+[provider]
+# openai_api_key            = "sk-..."
+# anthropic_api_key         = "sk-ant-..."
+# google_api_key            = "AIza..."
+# vercel_api_key            = "vck_..."
+# aws_bearer_token_bedrock  = "..."
+# ollama_base_url           = "http://localhost:11434"
+# openrouter_api_key        = "sk-..."
+
+[llm]
+# agent_model   = "gemini-3-flash"
+# parsing_model = "gemini-3-flash"
+```
+
+Shell environment variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, and `OLLAMA_BASE_URL` take precedence over the config file. For private repositories, set `GITHUB_TOKEN` in your environment.
+
+## Common commands
+
+```bash
+# Analyze a local repository
+python main.py --local ./my-project
+
+# Increase diagram depth
+python main.py --local ./my-project --depth-level 2
+
+# Re-analyze only changed parts when possible
+python main.py --local ./my-project --incremental
+
+# Update a single component by ID
+python main.py --local ./my-project --partial-component-id "a3f2b1c4d5e6f789"
+
+# Analyze a remote GitHub repository
+python main.py https://github.com/pytorch/pytorch
+```
+
+## Where to use it
+
+- [CLI](https://github.com/CodeBoarding/CodeBoarding) for local analysis, automation, and CI workflows.
+- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) for in-editor visual architecture.
+- [GitHub Action](https://github.com/marketplace/actions/codeboarding-diagram-first-documentation) to keep diagrams updated in CI.
+
+## Supported stack
+
+- Languages: Python, TypeScript, JavaScript, Java, Go, PHP.
+- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, and more.
+
+## Examples
+
+- Visualized 800+ open-source repositories.
+- Browse generated examples in [GeneratedOnBoardings](https://github.com/CodeBoarding/GeneratedOnBoardings).
+- Try the hosted explorer at [codeboarding.org/diagrams](https://codeboarding.org/diagrams).
+
+## Contributing
+
+If you want to improve CodeBoarding, open an [issue](https://github.com/CodeBoarding/CodeBoarding/issues) or send a pull request. We welcome improvements to analysis quality, output generators, integrations, and developer experience.
+
+## Vision
+
+CodeBoarding is building an open standard for code understanding: a visual, accurate, high-level representation of a codebase that both humans and agents can use.

{codeboarding-0.9.4 → codeboarding-0.9.5/codeboarding.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.9.4
+Version: 0.9.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License: MIT

{codeboarding-0.9.4 → codeboarding-0.9.5}/codeboarding.egg-info/SOURCES.txt

@@ -134,6 +134,8 @@ tests/test_incremental_analyzer.py
 tests/test_install.py
 tests/test_logging_config.py
 tests/test_main.py
+tests/test_tool_registry.py
+tests/test_user_config.py
 tests/test_vscode_constants.py
 tests/test_windows_compatibility.py
 tests/test_windows_encoding.py

{codeboarding-0.9.4 → codeboarding-0.9.5}/install.py

@@ -5,6 +5,7 @@ import platform
 import shutil
 import subprocess
 import sys
+import tarfile
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -18,7 +19,10 @@ from tool_registry import (
     install_archive_tool,
     install_native_tools,
     install_node_tools,
+    npm_subprocess_env,
     platform_bin_dir,
+    preferred_node_path,
+    preferred_npm_command,
 )
 from user_config import ensure_config_template
 
@@ -43,15 +47,17 @@ class LanguageSupportCheck:
         return False, reason
 
 
-def check_npm():
-    """Check if npm is installed on the system."""
+def check_npm(target_dir: Path | None = None) -> bool:
+    """Check if npm is available via the configured Node.js runtime or PATH."""
     print("Step: npm check started")
 
-    npm_path = shutil.which("npm")
+    target = (target_dir or get_servers_dir()).resolve()
+    npm_command = preferred_npm_command(target)
 
-    if npm_path:
+    if npm_command:
         try:
-            result = subprocess.run([npm_path, "--version"], capture_output=True, text=True, check=True)
+            env = npm_subprocess_env(target)
+            result = subprocess.run([*npm_command, "--version"], capture_output=True, text=True, check=True, env=env)
             print(f"Step: npm check finished: success (version {result.stdout.strip()})")
             return True
         except Exception as e:
@@ -59,31 +65,71 @@ def check_npm():
                 f"Step: npm check finished: failure - npm command failed ({e}). Skipping Language Servers installation."
             )
             return False
-    else:
-        print("Step: npm check finished: failure - npm not found")
-        return False
+
+    print("Step: npm check finished: failure - npm not found")
+    return False
+
+
+def bootstrapped_npm_cli_path(target_dir: Path) -> Path:
+    """Return the npm CLI entrypoint inside the target directory."""
+    return target_dir / "npm" / "package" / "bin" / "npm-cli.js"
 
 
-def install_npm_with_nodeenv() -> bool:
-    """Install npm locally in the active Python virtual environment using nodeenv."""
-    command = [sys.executable, "-m", "nodeenv", "--python-virtualenv"]
+def extract_tarball_safely(fileobj: io.BytesIO, destination: Path) -> None:
+    """Extract a tarball while rejecting path traversal entries."""
+    destination = destination.resolve()
+    with tarfile.open(fileobj=fileobj, mode="r:gz") as tar:
+        for member in tar.getmembers():
+            member_path = (destination / member.name).resolve()
+            if not member_path.is_relative_to(destination):
+                raise ValueError(f"Unsafe tar entry: {member.name}")
+        tar.extractall(destination)
+
+
+def bootstrap_npm(target_dir: Path | None = None) -> bool:
+    """Download npm from the registry and invoke it through the configured Node.js runtime."""
+    target = (target_dir or get_servers_dir()).resolve()
+    target.mkdir(parents=True, exist_ok=True)
+    node_path = preferred_node_path(target)
+
     print("Step: npm remediation started")
-    print(f"   command: {' '.join(command)}")
-    print("   impact: installs Node.js + npm into the active Python virtual environment")
+    print(f"   target: {target}")
+    print("   impact: installs npm into the CodeBoarding tools directory and invokes it via Node.js")
 
-    try:
-        result = subprocess.run(command, capture_output=True, text=True, check=True)
-    except subprocess.CalledProcessError as e:
-        print(f"Step: npm remediation finished: failure - {e}")
-        if e.stderr:
-            print(f"   {e.stderr.strip()}")
-        print("   You can install Node.js manually from: https://nodejs.org/en/download")
-        print("   Then verify with: npm --version")
+    if not node_path:
+        print("Step: npm remediation finished: failure - no Node.js runtime available")
+        print("   Set CODEBOARDING_NODE_PATH or install Node.js from: https://nodejs.org/en/download")
         return False
 
-    npm_available = check_npm()
+    os.environ.setdefault("CODEBOARDING_NODE_PATH", node_path)
+    print(f"   node: {os.environ['CODEBOARDING_NODE_PATH']}")
+
+    npm_cli = bootstrapped_npm_cli_path(target)
+    if not npm_cli.exists():
+        npm_root = npm_cli.parent.parent.parent
+        metadata_url = "https://registry.npmjs.org/npm/latest"
+        try:
+            metadata_response = requests.get(metadata_url, timeout=30)
+            metadata_response.raise_for_status()
+            metadata = metadata_response.json()
+            tarball_url = metadata["dist"]["tarball"]
+            print(f"   source: {tarball_url}")
+
+            tarball_response = requests.get(tarball_url, timeout=60)
+            tarball_response.raise_for_status()
+
+            shutil.rmtree(npm_root, ignore_errors=True)
+            npm_root.mkdir(parents=True, exist_ok=True)
+            extract_tarball_safely(io.BytesIO(tarball_response.content), npm_root)
+        except (requests.RequestException, KeyError, OSError, ValueError, tarfile.TarError) as e:
+            print(f"Step: npm remediation finished: failure - {e}")
+            print("   Install Node.js manually from: https://nodejs.org/en/download")
+            print("   Then verify with: npm --version")
+            return False
+
+    npm_available = check_npm(target)
     if not npm_available:
-        print("Step: npm remediation finished: failure - npm still not found after nodeenv install")
+        print("Step: npm remediation finished: failure - npm still not found after bootstrap")
         print("   You can install Node.js manually from: https://nodejs.org/en/download")
         print("   Then verify with: npm --version")
         return False
@@ -97,30 +143,25 @@ def is_non_interactive_mode() -> bool:
     return bool(os.getenv("CI")) or not sys.stdin.isatty()
 
 
-def resolve_missing_npm(auto_install_npm: bool = False) -> bool:
-    """Prompt the user to install npm; abort if they decline or if non-interactive.
+def resolve_missing_npm(auto_install_npm: bool = False, target_dir: Path | None = None) -> bool:
+    """Try to bootstrap npm; fall back gracefully if it cannot be obtained.
 
-    Returns True only when npm becomes available. Raises SystemExit if the user
-    declines or if running non-interactively, because npm is required.
+    Returns True when npm becomes available, False otherwise.
+    In non-interactive mode (VS Code extension / CI) the function never raises —
+    a missing npm just means Node-based language servers will be unavailable.
     """
     print("Step: npm required for TypeScript/JavaScript/PHP/Python language servers")
 
-    if auto_install_npm:
-        installed = install_npm_with_nodeenv()
+    if auto_install_npm or is_non_interactive_mode():
+        installed = bootstrap_npm(target_dir=target_dir)
         if not installed:
-            print("Error: npm installation failed. Install Node.js from https://nodejs.org/en/download and retry.")
-            raise SystemExit(1)
-        return True
-
-    if is_non_interactive_mode():
-        print("Error: npm is required but not found and cannot be installed non-interactively.")
-        print("   Re-run with --auto-install-npm to install npm in this virtual environment,")
-        print("   or install Node.js manually from: https://nodejs.org/en/download")
-        raise SystemExit(1)
+            print("Warning: npm bootstrap failed. Node-based language servers will be unavailable.")
+            print("   Install Node.js from https://nodejs.org/en/download to enable them.")
+        return installed
 
-    choice = input("npm is missing. Install it now using nodeenv in this virtual environment? [y/N]: ").strip().lower()
+    choice = input("npm is missing. Install it now using the configured Node.js runtime? [y/N]: ").strip().lower()
     if choice in {"y", "yes"}:
-        installed = install_npm_with_nodeenv()
+        installed = bootstrap_npm(target_dir=target_dir)
         if not installed:
             print("Error: npm installation failed. Install Node.js from https://nodejs.org/en/download and retry.")
             raise SystemExit(1)
@@ -130,12 +171,12 @@ def resolve_missing_npm(auto_install_npm: bool = False) -> bool:
     raise SystemExit(1)
 
 
-def resolve_npm_availability(auto_install_npm: bool = False) -> bool:
+def resolve_npm_availability(auto_install_npm: bool = False, target_dir: Path | None = None) -> bool:
     """Determine npm availability and run remediation when needed."""
-    npm_available = check_npm()
+    npm_available = check_npm(target_dir)
 
     if not npm_available:
-        npm_available = resolve_missing_npm(auto_install_npm=auto_install_npm)
+        npm_available = resolve_missing_npm(auto_install_npm=auto_install_npm, target_dir=target_dir)
 
     return npm_available
 
@@ -146,7 +187,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--auto-install-npm",
         action="store_true",
-        help="Automatically install npm via nodeenv when npm is missing",
+        help="Automatically bootstrap npm when missing (downloads from registry, runs via Node.js)",
     )
     parser.add_argument(
         "--auto-install-vcpp",
@@ -483,7 +524,7 @@ def run_install(
 
     ensure_config_template()
 
-    npm_available = resolve_npm_availability(auto_install_npm=auto_install_npm)
+    npm_available = resolve_npm_availability(auto_install_npm=auto_install_npm, target_dir=target)
     if npm_available:
         install_node_servers(target)
 

{codeboarding-0.9.4 → codeboarding-0.9.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeboarding"
-version = "0.9.4"
+version = "0.9.5"
 description = "Interactive Diagrams for Code"
 readme = "PYPI.md"
 license = {text = "MIT"}

codeboarding-0.9.5/tests/test_install.py

@@ -0,0 +1,120 @@
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import install
+
+
+class TestParseArgs(unittest.TestCase):
+    def test_parse_args_defaults(self):
+        with patch.object(sys, "argv", ["install.py"]):
+            args = install.parse_args()
+        self.assertFalse(args.auto_install_npm)
+
+    def test_parse_args_auto_install_npm(self):
+        with patch.object(sys, "argv", ["install.py", "--auto-install-npm"]):
+            args = install.parse_args()
+        self.assertTrue(args.auto_install_npm)
+
+
+class TestResolveMissingNpm(unittest.TestCase):
+    @patch("install.bootstrap_npm", return_value=True)
+    def test_auto_install_mode_bootstraps_npm(self, mock_bootstrap):
+        target_dir = Path("/tmp/codeboarding-servers")
+        result = install.resolve_missing_npm(auto_install_npm=True, target_dir=target_dir)
+        self.assertTrue(result)
+        mock_bootstrap.assert_called_once_with(target_dir=target_dir)
+
+    @patch("install.bootstrap_npm", return_value=False)
+    @patch("install.is_non_interactive_mode", return_value=True)
+    def test_non_interactive_falls_back_gracefully(self, mock_non_interactive, mock_bootstrap):
+        """Non-interactive mode should not raise SystemExit — just return False."""
+        result = install.resolve_missing_npm(auto_install_npm=False)
+        self.assertFalse(result)
+        mock_bootstrap.assert_called_once()
+
+    @patch("install.bootstrap_npm", return_value=False)
+    def test_auto_install_failure_degrades_gracefully(self, mock_bootstrap):
+        """When auto_install is True but bootstrap fails, return False (don't crash server)."""
+        result = install.resolve_missing_npm(auto_install_npm=True, target_dir=Path("/tmp/test"))
+        self.assertFalse(result)
+
+
+class TestResolveNpmAvailability(unittest.TestCase):
+    @patch("install.resolve_missing_npm")
+    @patch("install.check_npm", return_value=True)
+    def test_npm_present_does_not_attempt_remediation(self, mock_check_npm, mock_resolve_missing_npm):
+        target_dir = Path("/tmp/codeboarding-servers")
+        result = install.resolve_npm_availability(auto_install_npm=False, target_dir=target_dir)
+        self.assertTrue(result)
+        mock_check_npm.assert_called_once_with(target_dir)
+        mock_resolve_missing_npm.assert_not_called()
+
+    @patch("install.resolve_missing_npm", return_value=True)
+    @patch("install.check_npm", return_value=False)
+    def test_missing_npm_attempts_remediation(self, mock_check_npm, mock_resolve_missing_npm):
+        target_dir = Path("/tmp/codeboarding-servers")
+        result = install.resolve_npm_availability(auto_install_npm=True, target_dir=target_dir)
+        self.assertTrue(result)
+        mock_check_npm.assert_called_once_with(target_dir)
+        mock_resolve_missing_npm.assert_called_once_with(auto_install_npm=True, target_dir=target_dir)
+
+
+class TestBootstrapNpm(unittest.TestCase):
+    @patch("install.check_npm", return_value=True)
+    @patch("install.requests.get")
+    @patch("install.preferred_node_path", return_value="/custom/node")
+    def test_bootstraps_npm_cli_when_missing(self, mock_preferred_node_path, mock_requests_get, mock_check_npm):
+        with tempfile.TemporaryDirectory() as temp_dir, patch.dict(os.environ, {}, clear=True):
+            target_dir = Path(temp_dir)
+
+            metadata_response = Mock()
+            metadata_response.raise_for_status.return_value = None
+            metadata_response.json.return_value = {
+                "dist": {"tarball": "https://registry.npmjs.org/npm/-/npm-1.0.0.tgz"}
+            }
+            tarball_response = Mock()
+            tarball_response.raise_for_status.return_value = None
+            tarball_response.content = b"fake-tarball"
+            mock_requests_get.side_effect = [metadata_response, tarball_response]
+
+            with patch("install.extract_tarball_safely") as mock_extract, patch("install.shutil.rmtree") as mock_rmtree:
+                result = install.bootstrap_npm(target_dir=target_dir)
+                self.assertEqual(os.environ["CODEBOARDING_NODE_PATH"], "/custom/node")
+
+        self.assertTrue(result)
+        mock_preferred_node_path.assert_called_once_with(target_dir.resolve())
+        mock_requests_get.assert_any_call("https://registry.npmjs.org/npm/latest", timeout=30)
+        mock_requests_get.assert_any_call("https://registry.npmjs.org/npm/-/npm-1.0.0.tgz", timeout=60)
+        mock_rmtree.assert_called_once_with(target_dir.resolve() / "npm", ignore_errors=True)
+        mock_extract.assert_called_once()
+        mock_check_npm.assert_called_once_with(target_dir.resolve())
+
+    @patch("install.check_npm", return_value=True)
+    @patch("install.requests.get")
+    @patch("install.preferred_node_path", return_value="/custom/node")
+    def test_uses_existing_bootstrapped_npm_cli(self, mock_preferred_node_path, mock_requests_get, mock_check_npm):
+        with tempfile.TemporaryDirectory() as temp_dir, patch.dict(os.environ, {}, clear=True):
+            target_dir = Path(temp_dir)
+            npm_cli = install.bootstrapped_npm_cli_path(target_dir)
+            npm_cli.parent.mkdir(parents=True, exist_ok=True)
+            npm_cli.write_text("", encoding="utf-8")
+
+            result = install.bootstrap_npm(target_dir=target_dir)
+
+        self.assertTrue(result)
+        mock_preferred_node_path.assert_called_once_with(target_dir.resolve())
+        mock_requests_get.assert_not_called()
+        mock_check_npm.assert_called_once_with(target_dir.resolve())
+
+    @patch("install.preferred_node_path", return_value=None)
+    def test_returns_false_when_no_node_runtime_is_available(self, mock_preferred_node_path):
+        with tempfile.TemporaryDirectory() as temp_dir, patch.dict(os.environ, {}, clear=True):
+            target_dir = Path(temp_dir)
+            result = install.bootstrap_npm(target_dir=target_dir)
+
+        self.assertFalse(result)
+        mock_preferred_node_path.assert_called_once_with(target_dir.resolve())

codeboarding-0.9.5/tests/test_tool_registry.py

@@ -0,0 +1,94 @@
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from tool_registry import TOOL_REGISTRY, ToolKind, install_node_tools, resolve_config
+
+
+class TestToolRegistry(unittest.TestCase):
+    @patch("platform.system", return_value="Linux")
+    @patch.dict(os.environ, {"CODEBOARDING_NODE_PATH": "/vscode/node"}, clear=False)
+    def test_resolve_config_uses_explicit_node_path_for_node_servers(self, mock_system):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base_dir = Path(temp_dir)
+            (base_dir / "node_modules" / ".bin").mkdir(parents=True)
+            (base_dir / "node_modules" / ".bin" / "typescript-language-server").write_text("")
+            ts_dir = base_dir / "node_modules" / "typescript-language-server"
+            ts_dir.mkdir(parents=True)
+            (ts_dir / "cli.mjs").write_text("")
+
+            config = resolve_config(base_dir)
+            command = config["lsp_servers"]["typescript"]["command"]
+
+            self.assertEqual(command[0], "/vscode/node")
+            self.assertTrue(command[1].endswith("cli.mjs"))
+            self.assertEqual(command[2:], ["--stdio", "--log-level=2"])
+
+    @patch("platform.system", return_value="Linux")
+    def test_resolve_config_falls_back_to_embedded_nodeenv_node(self, mock_system):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base_dir = Path(temp_dir)
+            nodeenv_bin = base_dir / "nodeenv" / "bin"
+            nodeenv_bin.mkdir(parents=True)
+            (nodeenv_bin / "node").write_text("")
+            (nodeenv_bin / "npm").write_text("")
+
+            (base_dir / "node_modules" / ".bin").mkdir(parents=True)
+            (base_dir / "node_modules" / ".bin" / "pyright-langserver").write_text("")
+            pyright_dir = base_dir / "node_modules" / "pyright" / "dist"
+            pyright_dir.mkdir(parents=True)
+            (pyright_dir / "langserver.index.js").write_text("")
+
+            config = resolve_config(base_dir)
+            command = config["lsp_servers"]["python"]["command"]
+
+            self.assertEqual(command[0], str(nodeenv_bin / "node"))
+            self.assertTrue(command[1].endswith("langserver.index.js"))
+            self.assertEqual(command[2:], ["--stdio"])
+
+    @patch("tool_registry.subprocess.run")
+    @patch("platform.system", return_value="Linux")
+    def test_install_node_tools_prefers_embedded_npm(self, mock_system, mock_run):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base_dir = Path(temp_dir)
+            nodeenv_bin = base_dir / "nodeenv" / "bin"
+            nodeenv_bin.mkdir(parents=True)
+            (nodeenv_bin / "npm").write_text("")
+
+            node_deps = [dep for dep in TOOL_REGISTRY if dep.kind is ToolKind.NODE]
+            install_node_tools(base_dir, node_deps)
+
+            self.assertGreaterEqual(mock_run.call_count, 2)
+            first_command = mock_run.call_args_list[0].args[0]
+            second_command = mock_run.call_args_list[1].args[0]
+            self.assertEqual(first_command[0], str(nodeenv_bin / "npm"))
+            self.assertEqual(second_command[0], str(nodeenv_bin / "npm"))
+            # Verify env is passed with ELECTRON_RUN_AS_NODE
+            for call in mock_run.call_args_list:
+                env = call.kwargs.get("env", {})
+                self.assertEqual(env.get("ELECTRON_RUN_AS_NODE"), "1")
+
+    @patch("tool_registry.subprocess.run")
+    @patch("platform.system", return_value="Linux")
+    @patch.dict(os.environ, {"CODEBOARDING_NODE_PATH": "/vscode/node"}, clear=False)
+    def test_install_node_tools_uses_bootstrapped_npm_cli(self, mock_system, mock_run):
+        """When only a bootstrapped npm-cli.js exists, use [node, npm-cli.js, ...]."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base_dir = Path(temp_dir)
+            npm_cli = base_dir / "npm" / "package" / "bin" / "npm-cli.js"
+            npm_cli.parent.mkdir(parents=True)
+            npm_cli.write_text("")
+
+            node_deps = [dep for dep in TOOL_REGISTRY if dep.kind is ToolKind.NODE]
+            install_node_tools(base_dir, node_deps)
+
+            self.assertGreaterEqual(mock_run.call_count, 2)
+            first_command = mock_run.call_args_list[0].args[0]
+            self.assertEqual(first_command[0], "/vscode/node")
+            self.assertEqual(first_command[1], str(npm_cli))
+
+
+if __name__ == "__main__":
+    unittest.main()