Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(serve): detect old Node.js and fall back to API-only with a clear message (#289)
Raghav Chamadiya2bac100c0b1e
diff --git a/packages/cli/src/repowise/cli/commands/serve_cmd.py b/packages/cli/src/repowise/cli/commands/serve_cmd.pyindex 8029291c8..60da54ceb 100644--- a/packages/cli/src/repowise/cli/commands/serve_cmd.py+++ b/packages/cli/src/repowise/cli/commands/serve_cmd.py@@ -234,11 +234,39 @@ _WEB_CACHE_DIR = Path.home() / ".repowise" / "web"_MARKER_FILE = _WEB_CACHE_DIR / ".version"+_NODE_MIN_MAJOR = 20 # Next.js 15 (see packages/web/package.json engines.node)++def _node_available() -> str | None:"""Return the path to node binary, or None."""return shutil.which("node")+def _node_major_version(node: str) -> int | None:+ """Return the major version of the *node* binary, or None if it can't be read.++ A failure to invoke or parse is treated as "unknown" rather than fatal — the+ caller decides whether to proceed or fall back.+ """+ try:+ result = subprocess.run(+ [node, "--version"],+ capture_output=True,+ text=True,+ timeout=5,+ check=True,+ )+ except (OSError, subprocess.SubprocessError):+ return None++ raw = result.stdout.strip().lstrip("v")+ head = raw.split(".", 1)[0]+ try:+ return int(head)+ except ValueError:+ return None++def _npm_available() -> str | None:"""Return the path to npm binary, or None."""return shutil.which("npm")@@ -504,11 +532,25 @@ def serve_command(node = _node_available()npm = _npm_available()+ # Reject Node versions older than what the bundled Next.js needs.+ # Without this check, an old node silently produces cryptic syntax+ # errors from inside the Next.js runtime (e.g. `Unexpected token '?'`+ # on `??`) once the frontend tries to start — see issue #276.+ node_major = _node_major_version(node) if node else None+ node_too_old = node is not None and node_major is not None and node_major < _NODE_MIN_MAJOR+if not node:console.print(- "[yellow]Node.js not found — starting API server only.[/yellow]\n"- "[dim]To get the web UI, install Node.js 20+ or use Docker:\n"- " docker run -p 7337:7337 -p 3000:3000 -v .repowise:/data repowise[/dim]"+ f"[yellow]Node.js not found — starting API server only.[/yellow]\n"+ f"[dim]To get the web UI, install Node.js {_NODE_MIN_MAJOR}+ or use Docker:\n"+ f" docker run -p 7337:7337 -p 3000:3000 -v .repowise:/data repowise[/dim]"+ )+ elif node_too_old:+ console.print(+ f"[yellow]Node.js {node_major} is too old for the bundled web UI "+ f"(requires {_NODE_MIN_MAJOR}+) — starting API server only.[/yellow]\n"+ f"[dim]Upgrade Node.js to {_NODE_MIN_MAJOR}+ or use Docker:\n"+ f" docker run -p 7337:7337 -p 3000:3000 -v .repowise:/data repowise[/dim]")else:# Try to get the frontend runningdiff --git a/tests/unit/cli/test_serve_node_version.py b/tests/unit/cli/test_serve_node_version.pynew file mode 100644index 000000000..cccf40cf1--- /dev/null+++ b/tests/unit/cli/test_serve_node_version.py@@ -0,0 +1,86 @@+"""Regression tests for Node.js version detection in `repowise serve` (issue #276).++When the user has an old Node.js on PATH, the bundled Next.js runtime crashes+with a cryptic syntax error (e.g. `Unexpected token '?'` on `??`) after the UI+appears to start. Detect the version up front and fall back to API-only mode+with a clear message instead.+"""++from __future__ import annotations++import subprocess+from typing import Any++import pytest++from repowise.cli.commands import serve_cmd+++class _FakeCompleted:+ def __init__(self, stdout: str) -> None:+ self.stdout = stdout+ self.returncode = 0+++def test_node_major_version_parses_standard_output(monkeypatch: pytest.MonkeyPatch) -> None:+ def fake_run(*_args: Any, **_kwargs: Any) -> _FakeCompleted:+ return _FakeCompleted("v20.11.1\n")++ monkeypatch.setattr(serve_cmd.subprocess, "run", fake_run)+ assert serve_cmd._node_major_version("/usr/bin/node") == 20+++def test_node_major_version_parses_old_release(monkeypatch: pytest.MonkeyPatch) -> None:+ """The exact scenario from issue #276 — Node 12 (pre-nullish-coalescing)."""++ def fake_run(*_args: Any, **_kwargs: Any) -> _FakeCompleted:+ return _FakeCompleted("v12.22.12\n")++ monkeypatch.setattr(serve_cmd.subprocess, "run", fake_run)+ assert serve_cmd._node_major_version("/usr/bin/node") == 12+++def test_node_major_version_handles_missing_v_prefix(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def fake_run(*_args: Any, **_kwargs: Any) -> _FakeCompleted:+ return _FakeCompleted("18.20.3\n")++ monkeypatch.setattr(serve_cmd.subprocess, "run", fake_run)+ assert serve_cmd._node_major_version("/usr/bin/node") == 18+++def test_node_major_version_returns_none_on_subprocess_error(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def fake_run(*_args: Any, **_kwargs: Any) -> _FakeCompleted:+ raise subprocess.CalledProcessError(1, "node")++ monkeypatch.setattr(serve_cmd.subprocess, "run", fake_run)+ assert serve_cmd._node_major_version("/usr/bin/node") is None+++def test_node_major_version_returns_none_on_oserror(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def fake_run(*_args: Any, **_kwargs: Any) -> _FakeCompleted:+ raise OSError("not executable")++ monkeypatch.setattr(serve_cmd.subprocess, "run", fake_run)+ assert serve_cmd._node_major_version("/missing/node") is None+++def test_node_major_version_returns_none_on_garbage_output(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def fake_run(*_args: Any, **_kwargs: Any) -> _FakeCompleted:+ return _FakeCompleted("not a version string\n")++ monkeypatch.setattr(serve_cmd.subprocess, "run", fake_run)+ assert serve_cmd._node_major_version("/usr/bin/node") is None+++def test_minimum_node_major_matches_next_engines() -> None:+ """If this trips, packages/web/package.json `engines.node` bumped and the+ constant in serve_cmd needs to be updated to match."""+ assert serve_cmd._NODE_MIN_MAJOR == 20