Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
index 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 running
diff --git a/tests/unit/cli/test_serve_node_version.py b/tests/unit/cli/test_serve_node_version.py
new file mode 100644
index 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