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): rebuild local web bundle when source is newer; add --refresh-ui (#165)

Raghav Chamadiyabca750908cb5
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md
index 5d5123011..64d2837b0 100644
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -112,13 +112,23 @@ Start the API server and web UI.
| `--workers` | Uvicorn workers (default: 1) |
| `--ui-port` | Web UI port (default: 3000) |
| `--no-ui` | Start API server only |
+| `--refresh-ui` | Force re-download of the web UI tarball, ignoring any cache |
```bash
repowise serve # API + Web UI
repowise serve --no-ui # API only
repowise serve --port 8080 --ui-port 8081
+repowise serve --refresh-ui # bypass cache, pull latest UI tarball
```
+**Web UI sources, in order of precedence:**
+
+1. **Local monorepo build** at `packages/web/.next/standalone/...` — used when the CLI is run from inside a checkout. The bundle's mtime is compared against source under `packages/web/`, `packages/ui/src/`, and `packages/types/src/`; if any source is newer the bundle is rebuilt with `npm run build` (or skipped if `npm` is unavailable).
+2. **Cached download** at `~/.repowise/web/`, keyed by the CLI version in `.version`.
+3. **Fresh download** of `repowise-web.tar.gz` from the GitHub release matching the CLI version.
+
+Pass `--refresh-ui` to skip (1) and (2) and force (3).
+
---
### `repowise watch [PATH]`
diff --git a/packages/cli/src/repowise/cli/commands/serve_cmd.py b/packages/cli/src/repowise/cli/commands/serve_cmd.py
index f10274b0d..2eb20472d 100644
--- a/packages/cli/src/repowise/cli/commands/serve_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/serve_cmd.py
@@ -196,6 +196,57 @@ def _find_local_web() -> Path | None:
return None
+def _local_build_is_stale(web_dir: Path) -> bool:
+ """True if the local .next/standalone bundle is older than any input source.
+
+ Compares the standalone server.js mtime against the newest mtime under the
+ source roots that get compiled into the bundle (web/ui/types packages plus
+ web's config files). Skips node_modules / .next / .turbo. Used so that a
+ cloned monorepo with stale build artifacts falls back to the released
+ tarball instead of serving a bundle behind the user's source tree.
+ """
+ standalone = web_dir / ".next" / "standalone" / "packages" / "web" / "server.js"
+ if not standalone.exists():
+ return True
+ build_mtime = standalone.stat().st_mtime
+
+ repo_root = web_dir.parent.parent # packages/web → repo root
+ skip_dirs = {"node_modules", ".next", ".turbo", "dist", ".git"}
+
+ file_inputs: list[Path] = [
+ web_dir / "package.json",
+ web_dir / "next.config.ts",
+ web_dir / "next.config.js",
+ web_dir / "tsconfig.json",
+ ]
+ dir_inputs: list[Path] = [
+ web_dir / "src",
+ web_dir / "app",
+ web_dir / "components",
+ web_dir / "lib",
+ web_dir / "public",
+ repo_root / "packages" / "ui" / "src",
+ repo_root / "packages" / "types" / "src",
+ ]
+
+ for f in file_inputs:
+ if f.exists() and f.is_file() and f.stat().st_mtime > build_mtime:
+ return True
+
+ for root in dir_inputs:
+ if not root.exists():
+ continue
+ for path in root.rglob("*"):
+ if any(part in skip_dirs for part in path.parts):
+ continue
+ try:
+ if path.is_file() and path.stat().st_mtime > build_mtime:
+ return True
+ except OSError:
+ continue
+ return False
+
+
def _download_web(version: str) -> bool:
"""Download pre-built web frontend from GitHub releases."""
import httpx
@@ -265,8 +316,18 @@ def _build_local_web(web_dir: Path, npm: str) -> bool:
return False
-def _start_frontend(node: str, backend_port: int, frontend_port: int) -> subprocess.Popen | None:
- """Start the Next.js frontend server. Returns the process or None."""
+def _start_frontend(
+ node: str,
+ backend_port: int,
+ frontend_port: int,
+ local_web: Path | None = None,
+) -> subprocess.Popen | None:
+ """Start the Next.js frontend server. Returns the process or None.
+
+ If ``local_web`` is provided, the local monorepo build is used as Option 1.
+ Pass ``None`` to skip the local build (e.g. when it's stale or refresh was
+ forced) and use only the cached tarball at ``~/.repowise/web``.
+ """
env = {
**os.environ,
"REPOWISE_API_URL": f"http://localhost:{backend_port}",
@@ -275,7 +336,6 @@ def _start_frontend(node: str, backend_port: int, frontend_port: int) -> subproc
}
# Option 1: Local repo build (preferred — uses latest source)
- local_web = _find_local_web()
if local_web:
standalone_dir = local_web / ".next" / "standalone"
server_js = standalone_dir / "packages" / "web" / "server.js"
@@ -314,7 +374,14 @@ def _start_frontend(node: str, backend_port: int, frontend_port: int) -> subproc
@click.option("--workers", default=1, type=int, help="Number of uvicorn workers.")
@click.option("--ui-port", default=3000, type=int, help="Web UI port.")
@click.option("--no-ui", is_flag=True, help="Start API server only, skip the web UI.")
-def serve_command(port: int, host: str, workers: int, ui_port: int, no_ui: bool) -> None:
+ "--refresh-ui",
+ is_flag=True,
+ help="Force re-download of the web UI tarball, ignoring any cache.",
+)
+def serve_command(
+ port: int, host: str, workers: int, ui_port: int, no_ui: bool, refresh_ui: bool
+) -> None:
"""Start the repowise server with the web UI.
Starts the API backend and automatically launches the web frontend.
@@ -355,29 +422,42 @@ def serve_command(port: int, host: str, workers: int, ui_port: int, no_ui: bool)
else:
# Try to get the frontend running
ready = False
+ local_web: Path | None = None if refresh_ui else _find_local_web()
+
+ # Option 1: Local repo build (preferred — uses latest source).
+ # Only honoured when the bundle isn't behind the source tree.
+ if local_web:
+ if _local_build_is_stale(local_web):
+ if npm:
+ console.print(
+ "[dim]Local web bundle is older than source — rebuilding...[/dim]"
+ )
+ ready = _build_local_web(local_web, npm)
+ if not ready:
+ console.print(
+ "[yellow]Local rebuild failed — falling back to "
+ "released tarball.[/yellow]"
+ )
+ local_web = None
+ else:
+ console.print(
+ "[yellow]Local web bundle is stale and npm not found — "
+ "falling back to released tarball.[/yellow]"
+ )
+ local_web = None
+ else:
+ ready = True
- # Check cached download
- if _web_is_cached(__version__):
+ # Option 2: Cached download (skip when --refresh-ui is set).
+ if not ready and not refresh_ui and _web_is_cached(__version__):
ready = True
- # Check local repo build
- if not ready:
- local_web = _find_local_web()
- if local_web:
- standalone = (
- local_web / ".next" / "standalone" / "packages" / "web" / "server.js"
- )
- if standalone.exists():
- ready = True
- elif npm:
- ready = _build_local_web(local_web, npm)
-
- # Try downloading from GitHub releases
+ # Option 3: Download from GitHub releases.
if not ready:
ready = _download_web(__version__)
if ready:
- frontend_proc = _start_frontend(node, port, ui_port)
+ frontend_proc = _start_frontend(node, port, ui_port, local_web=local_web)
if frontend_proc:
console.print(f"[green]Web UI starting on http://localhost:{ui_port}[/green]")
else: