Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

ux: add single-command dashboard dev launcher

Mafifriziaca2637330ed
diff --git a/QUICKSTART.md b/QUICKSTART.md
index f39feb0..310e08c 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -80,19 +80,50 @@ For repeated local use, copy `.env.example` to `.env`, fill these values once, a
## 4. Start The API And Dashboard
```bash
-ares-api
+ares dashboard dev
```
-Open:
+This starts the FastAPI backend and the Vite dashboard dev server in one
+terminal. It prints:
+
+- Backend API URL: `http://127.0.0.1:8080`
+- Dashboard URL: `http://127.0.0.1:5173/dashboard/`
+- Login username: `admin`
+- Login password: value of `ARES_DEFAULT_ADMIN_PASSWORD` in `.env`
+
+The launcher opens the dashboard by default and does not print the password
+value. Use `ares dashboard dev --no-open` to print the URL without opening a
+browser. If `frontend/node_modules` is missing, run:
+
+```bash
+ares dashboard dev --install
+```
+
+Manual fallback for troubleshooting:
+
+Terminal 1:
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload
+```
+
+Terminal 2:
+
+```powershell
+cd frontend
+"C:\Program Files\nodejs\npm.cmd" run dev -- --host 127.0.0.1 --port 5173
+```
+
+Then open:
```text
-http://localhost:8080/dashboard
+http://127.0.0.1:5173/dashboard/
```
Health check:
```bash
-curl http://localhost:8080/health
+curl http://127.0.0.1:8080/health
```
Expected result:
@@ -114,6 +145,17 @@ already have a local database, use the current admin password. Changing
password. For disposable local data, recreate the local `ares.db`; otherwise,
change the password from the dashboard after login.
+Local development reset warning: this deletes local dashboard data in
+`ares.db`. Do not use it on real or shared deployments.
+
+```powershell
+New-Item -ItemType Directory -Force ".\_db_backup" | Out-Null
+if (Test-Path ".\ares.db") {
+ Copy-Item ".\ares.db" ".\_db_backup\ares.db.before-reset" -Force
+}
+Remove-Item ".\ares.db" -Force -ErrorAction SilentlyContinue
+```
+
Dashboard shell:
- The left sidebar routes between Overview, Campaigns, Modules, Reports, Graph,
diff --git a/README.md b/README.md
index 7d8f42c..2866337 100644
--- a/README.md
+++ b/README.md
@@ -237,6 +237,17 @@ reset that user's password. For local development, either change the password
from the `Security` page after logging in or recreate the local database if you
intend to discard existing local data.
+Local development reset warning: this deletes local dashboard data in
+`ares.db`. Do not use it on real or shared deployments.
+
+```powershell
+New-Item -ItemType Directory -Force ".\_db_backup" | Out-Null
+if (Test-Path ".\ares.db") {
+ Copy-Item ".\ares.db" ".\_db_backup\ares.db.before-reset" -Force
+}
+Remove-Item ".\ares.db" -Force -ErrorAction SilentlyContinue
+```
+
Roles are assigned when a `team_lead` creates a user:
| Role | Intended use | Practical access |
@@ -372,30 +383,52 @@ $env:ANTHROPIC_API_KEY="sk-ant-..."
### 2. Start the API and Dashboard
-From an installed package:
+Recommended local dashboard startup from the repository root:
+
+```bash
+ares dashboard dev
+```
+
+The launcher starts both services in one terminal:
+
+- Backend API: `http://127.0.0.1:8080`
+- Dashboard dev server: `http://127.0.0.1:5173/dashboard/`
+
+It prints both URLs, opens the dashboard by default, prefixes backend/frontend
+logs, and shuts both child processes down when you press `Ctrl+C`. Login with:
+
+- Username: `admin`
+- Password: the value of `ARES_DEFAULT_ADMIN_PASSWORD` in `.env`
+
+The command does not print the password value. If `frontend/node_modules` is
+missing, run `npm ci` in `frontend/` or start with:
```bash
-ares-api
+ares dashboard dev --install
```
-From this repository on Windows:
+Use `--no-open` when you want the command to print the URL without opening a
+browser.
+
+Manual fallback for troubleshooting:
+
+Terminal 1:
```powershell
-.\.venv\Scripts\ares-api.exe
+.\.venv\Scripts\python.exe -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload
```
-Expected startup:
+Terminal 2:
-```text
-ARES API v6.0.0 started
-db_ready
-engine_loaded_modules
+```powershell
+cd frontend
+"C:\Program Files\nodejs\npm.cmd" run dev -- --host 127.0.0.1 --port 5173
```
Open:
```text
-http://localhost:8080/dashboard
+http://127.0.0.1:5173/dashboard/
```
### 3. Check Health
diff --git a/ares/cli/typer_main.py b/ares/cli/typer_main.py
index b45ef36..ff8c806 100644
--- a/ares/cli/typer_main.py
+++ b/ares/cli/typer_main.py
@@ -23,9 +23,17 @@ from __future__ import annotations
import asyncio
import json
+import os
+import shutil
+import signal
+import socket
+import subprocess
import sys
+import threading
+import time
+import webbrowser
from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional
import typer
from rich.console import Console
@@ -60,6 +68,7 @@ report_app = typer.Typer(help="Generate engagement reports", no_args_is_help=T
signing_app = typer.Typer(help="Module signing and verification", no_args_is_help=True)
goal_app = typer.Typer(help="Goal-based autonomous attack planning", no_args_is_help=True)
graph_app = typer.Typer(help="Attack graph queries and visualization", no_args_is_help=True)
+dashboard_app = typer.Typer(help="Local dashboard developer tools", no_args_is_help=True)
app.add_typer(campaign_app, name="campaign")
app.add_typer(target_app, name="target")
@@ -69,6 +78,7 @@ app.add_typer(report_app, name="report")
app.add_typer(signing_app, name="signing")
app.add_typer(goal_app, name="goal")
app.add_typer(graph_app, name="graph")
+app.add_typer(dashboard_app, name="dashboard")
# ── Version ────────────────────────────────────────────────────────────────────
@@ -1244,6 +1254,472 @@ def doctor() -> None:
# ── quickstart wizard ─────────────────────────────────────────────────────────
+# -- dashboard developer launcher ------------------------------------------------
+
+def find_repo_root(start: Path | None = None) -> Path:
+ """Find the repository root from the current directory or one of its parents."""
+ current = Path.cwd().resolve() if start is None else Path(start).resolve()
+ candidates = [current, *current.parents]
+ for candidate in candidates:
+ if (candidate / "pyproject.toml").exists() and (candidate / "frontend").is_dir():
+ return candidate
+ raise FileNotFoundError(
+ "Could not find the ARES repository root. Run this command from the repo checkout."
+ )
+
+
+def resolve_npm_command(
+ os_name: str | None = None,
+ program_files_npm: Path | None = None,
+ which: Callable[[str], str | None] = shutil.which,
+) -> str:
+ """Resolve the npm executable without using a shell."""
+ effective_os = os.name if os_name is None else os_name
+ if effective_os == "nt":
+ preferred = program_files_npm or Path(r"C:\Program Files\nodejs\npm.cmd")
+ if preferred.exists():
+ return str(preferred)
+ return which("npm.cmd") or which("npm") or "npm.cmd"
+ return which("npm") or "npm"
+
+
+def build_backend_command(
+ api_host: str,
+ api_port: int,
+ *,
+ reload: bool = True,
+ python_executable: str | None = None,
+) -> list[str]:
+ command = [
+ python_executable or sys.executable,
+ "-m",
+ "uvicorn",
+ "ares.api.server:app",
+ "--host",
+ api_host,
+ "--port",
+ str(api_port),
+ ]
+ if reload:
+ command.append("--reload")
+ return command
+
+
+def build_frontend_command(npm_command: str, ui_host: str, ui_port: int) -> list[str]:
+ return [
+ npm_command,
+ "run",
+ "dev",
+ "--",
+ "--host",
+ ui_host,
+ "--port",
+ str(ui_port),
+ ]
+
+
+def wait_for_port(host: str, port: int, *, timeout_seconds: float = 30.0) -> bool:
+ deadline = time.monotonic() + timeout_seconds
+ while time.monotonic() < deadline:
+ try:
+ with socket.create_connection((host, port), timeout=0.5):
+ return True
+ except OSError:
+ time.sleep(0.25)
+ return False
+
+
+def _popen_kwargs(os_name: str | None = None) -> dict[str, object]:
+ effective_os = os.name if os_name is None else os_name
+ if effective_os == "nt":
+ return {"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}
+ return {"start_new_session": True}
+
+
+class _WindowsCleanupJob:
+ """Best-effort Windows job object that kills child processes if ARES exits."""
+
+ def __init__(self) -> None:
+ import ctypes
+ from ctypes import wintypes
+
+ self._ctypes = ctypes
+ self._kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+
+ class _JobBasicLimitInformation(ctypes.Structure):
+ _fields_ = [
+ ("PerProcessUserTimeLimit", ctypes.c_longlong),
+ ("PerJobUserTimeLimit", ctypes.c_longlong),
+ ("LimitFlags", wintypes.DWORD),
+ ("MinimumWorkingSetSize", ctypes.c_size_t),
+ ("MaximumWorkingSetSize", ctypes.c_size_t),
+ ("ActiveProcessLimit", wintypes.DWORD),
+ ("Affinity", ctypes.c_size_t),
+ ("PriorityClass", wintypes.DWORD),
+ ("SchedulingClass", wintypes.DWORD),
+ ]
+
+ class _IoCounters(ctypes.Structure):
+ _fields_ = [
+ ("ReadOperationCount", ctypes.c_ulonglong),
+ ("WriteOperationCount", ctypes.c_ulonglong),
+ ("OtherOperationCount", ctypes.c_ulonglong),
+ ("ReadTransferCount", ctypes.c_ulonglong),
+ ("WriteTransferCount", ctypes.c_ulonglong),
+ ("OtherTransferCount", ctypes.c_ulonglong),
+ ]
+
+ class _JobExtendedLimitInformation(ctypes.Structure):
+ _fields_ = [
+ ("BasicLimitInformation", _JobBasicLimitInformation),
+ ("IoInfo", _IoCounters),
+ ("ProcessMemoryLimit", ctypes.c_size_t),
+ ("JobMemoryLimit", ctypes.c_size_t),
+ ("PeakProcessMemoryUsed", ctypes.c_size_t),
+ ("PeakJobMemoryUsed", ctypes.c_size_t),
+ ]
+
+ self._kernel32.CreateJobObjectW.argtypes = [wintypes.LPVOID, wintypes.LPCWSTR]
+ self._kernel32.CreateJobObjectW.restype = wintypes.HANDLE
+ self._kernel32.SetInformationJobObject.argtypes = [
+ wintypes.HANDLE,
+ wintypes.INT,
+ wintypes.LPVOID,
+ wintypes.DWORD,
+ ]
+ self._kernel32.SetInformationJobObject.restype = wintypes.BOOL
+ self._kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+ self._kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
+ self._kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+ self._kernel32.CloseHandle.restype = wintypes.BOOL
+
+ self.handle = self._kernel32.CreateJobObjectW(None, None)
+ if not self.handle:
+ raise OSError(ctypes.get_last_error(), "CreateJobObjectW failed")
+
+ info = _JobExtendedLimitInformation()
+ info.BasicLimitInformation.LimitFlags = 0x2000 # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+ ok = self._kernel32.SetInformationJobObject(
+ self.handle,
+ 9, # JobObjectExtendedLimitInformation
+ ctypes.byref(info),
+ ctypes.sizeof(info),
+ )
+ if not ok:
+ error = ctypes.get_last_error()
+ self.close()
+ raise OSError(error, "SetInformationJobObject failed")
+
+ def assign(self, process: subprocess.Popen) -> None:
+ process_handle = getattr(process, "_handle", None)
+ if not process_handle or not self.handle:
+ return
+ self._kernel32.AssignProcessToJobObject(self.handle, process_handle)
+
+ def close(self) -> None:
+ if getattr(self, "handle", None):
+ self._kernel32.CloseHandle(self.handle)
+ self.handle = None
+
+
+def _create_windows_cleanup_job(os_name: str | None = None) -> _WindowsCleanupJob | None:
+ effective_os = os.name if os_name is None else os_name
+ if effective_os != "nt":
+ return None
+ try:
+ return _WindowsCleanupJob()
+ except Exception:
+ return None
+
+
+def _start_dashboard_process(
+ label: str,
+ command: list[str],
+ cwd: Path,
+ *,
+ popen_factory: Callable[..., subprocess.Popen] = subprocess.Popen,
+ os_name: str | None = None,
+) -> subprocess.Popen:
+ console.print(f"[cyan]{label}[/cyan] {' '.join(command)}")
+ return popen_factory(
+ command,
+ cwd=str(cwd),
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ stdin=subprocess.DEVNULL,
+ text=True,
+ bufsize=1,
+ **_popen_kwargs(os_name),
+ )
+
+
+def _stream_dashboard_logs(label: str, process: subprocess.Popen) -> None:
+ stream = getattr(process, "stdout", None)
+ if stream is None:
+ return
+ try:
+ for line in stream:
+ text = str(line).rstrip()
+ if text:
+ console.print(f"[dim]{label}[/dim] {text}")
+ except Exception as exc: # pragma: no cover - best-effort log streaming
+ console.print(f"[yellow]{label} log stream ended:[/yellow] {exc}")
+
+
+def terminate_process_tree(
+ process: subprocess.Popen | None,
+ *,
+ os_name: str | None = None,
+ timeout_seconds: float = 8.0,
+) -> None:
+ if process is None or process.poll() is not None:
+ return
+
+ effective_os = os.name if os_name is None else os_name
+ if effective_os == "nt":
+ try:
+ subprocess.run(
+ ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ check=False,
+ )
+ process.wait(timeout=timeout_seconds)
+ return
+ except Exception:
+ try:
+ process.kill()
+ except Exception:
+ pass
+ return
+
+ try:
+ os.killpg(process.pid, signal.SIGTERM)
+ except Exception:
+ try:
+ process.terminate()
+ except Exception:
+ pass
+
+ try:
+ process.wait(timeout=timeout_seconds)
+ return
+ except Exception:
+ pass
+
+ try:
+ os.killpg(process.pid, signal.SIGKILL)
+ except Exception:
+ try:
+ process.kill()
+ except Exception:
+ pass
+
+
+def _ensure_frontend_dependencies(
+ frontend_dir: Path,
+ npm_command: str,
+ *,
+ install: bool = False,
+ run_func: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+) -> None:
+ node_modules = frontend_dir / "node_modules"
+ if node_modules.exists():
+ return
+
+ if not install:
+ console.print(
+ "[red]frontend/node_modules is missing.[/red] "
+ "Run [cyan]npm ci[/cyan] in the frontend directory, or re-run with "
+ "[cyan]--install[/cyan]."
+ )
+ raise typer.Exit(1)
+
+ console.print("[cyan]Installing frontend dependencies with npm ci...[/cyan]")
+ result = run_func([npm_command, "ci"], cwd=str(frontend_dir), check=False)
+ if result.returncode != 0:
+ console.print("[red]npm ci failed; dashboard dev server was not started.[/red]")
+ raise typer.Exit(result.returncode or 1)
+
+
+def _install_dashboard_signal_handlers() -> list[tuple[int, object]]:
+ previous_handlers: list[tuple[int, object]] = []
+
+ def _raise_keyboard_interrupt(_signum, _frame) -> None:
+ raise KeyboardInterrupt
+
+ signals = [signal.SIGINT]
+ sigbreak = getattr(signal, "SIGBREAK", None)
+ if sigbreak is not None:
+ signals.append(sigbreak)
+
+ for sig in signals:
+ try:
+ previous_handlers.append((sig, signal.getsignal(sig)))
+ signal.signal(sig, _raise_keyboard_interrupt)
+ except Exception:
+ pass
+ return previous_handlers
+
+
+def _restore_dashboard_signal_handlers(previous_handlers: list[tuple[int, object]]) -> None:
+ for sig, handler in previous_handlers:
+ try:
+ signal.signal(sig, handler)
+ except Exception:
+ pass
+
+
+def _run_dashboard_dev(
+ *,
+ api_host: str = "127.0.0.1",
+ api_port: int = 8080,
+ ui_host: str = "127.0.0.1",
+ ui_port: int = 5173,
+ open_browser: bool = True,
+ reload: bool = True,
+ install: bool = False,
+ root: Path | None = None,
+ os_name: str | None = None,
+ popen_factory: Callable[..., subprocess.Popen] = subprocess.Popen,
+ run_func: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+ wait_for_port_func: Callable[..., bool] = wait_for_port,
+ open_browser_func: Callable[[str], object] = webbrowser.open,
+ sleep_func: Callable[[float], object] = time.sleep,
+) -> int:
+ root_path = find_repo_root(root)
+ frontend_dir = root_path / "frontend"
+ if not (frontend_dir / "package.json").exists():
+ console.print(f"[red]Frontend directory not found:[/red] {frontend_dir}")
+ raise typer.Exit(1)
+
+ npm_command = resolve_npm_command(os_name=os_name)
+ _ensure_frontend_dependencies(
+ frontend_dir,
+ npm_command,
+ install=install,
+ run_func=run_func,
+ )
+
+ backend_url = f"http://{api_host}:{api_port}"
+ dashboard_url = f"http://{ui_host}:{ui_port}/dashboard/"
+ backend_command = build_backend_command(api_host, api_port, reload=reload)
+ frontend_command = build_frontend_command(npm_command, ui_host, ui_port)
+
+ console.print("\n[bold]ARES dashboard developer launcher[/bold]")
+ console.print(f"Backend API URL: {backend_url}")
+ console.print(f"Dashboard URL: {dashboard_url}")
+ console.print("Login username: admin")
+ console.print("Login password: value of ARES_DEFAULT_ADMIN_PASSWORD in .env (not printed)")
+ if not (root_path / ".env").exists():
+ console.print("[yellow]Warning:[/yellow] .env was not found in the repo root.")
+ console.print()
+
+ backend_process: subprocess.Popen | None = None
+ frontend_process: subprocess.Popen | None = None
+ threads: list[threading.Thread] = []
+ cleanup_job = _create_windows_cleanup_job(os_name)
+ previous_signal_handlers = _install_dashboard_signal_handlers()
+
+ try:
+ backend_process = _start_dashboard_process(
+ "backend",
+ backend_command,
+ root_path,
+ popen_factory=popen_factory,
+ os_name=os_name,
+ )
+ if cleanup_job is not None:
+ cleanup_job.assign(backend_process)
+ frontend_process = _start_dashboard_process(
+ "frontend",
+ frontend_command,
+ frontend_dir,
+ popen_factory=popen_factory,
+ os_name=os_name,
+ )
+ if cleanup_job is not None:
+ cleanup_job.assign(frontend_process)
+
+ for label, process in (("backend", backend_process), ("frontend", frontend_process)):
+ thread = threading.Thread(
+ target=_stream_dashboard_logs,
+ args=(label, process),
+ daemon=True,
+ )
+ thread.start()
+ threads.append(thread)
+
+ if open_browser:
+ if wait_for_port_func(ui_host, ui_port, timeout_seconds=30.0):
+ console.print(f"[green]Opening dashboard:[/green] {dashboard_url}")
+ else:
+ console.print(
+ "[yellow]Dashboard port was not ready yet; opening the URL anyway.[/yellow]"
+ )
+ open_browser_func(dashboard_url)
+ else:
+ console.print("[dim]Browser open skipped because --no-open was provided.[/dim]")
+
+ while True:
+ backend_code = backend_process.poll()
+ frontend_code = frontend_process.poll()
+ if backend_code is not None:
+ console.print(f"[red]Backend process exited with code {backend_code}.[/red]")
+ return backend_code or 1
+ if frontend_code is not None:
+ console.print(f"[red]Frontend process exited with code {frontend_code}.[/red]")
+ return frontend_code or 1
+ sleep_func(0.25)
+ except KeyboardInterrupt:
+ console.print("\n[yellow]Shutting down dashboard dev servers...[/yellow]")
+ return 0
+ finally:
+ terminate_process_tree(frontend_process, os_name=os_name)
+ terminate_process_tree(backend_process, os_name=os_name)
+ if cleanup_job is not None:
+ cleanup_job.close()
+ _restore_dashboard_signal_handlers(previous_signal_handlers)
+ for thread in threads:
+ thread.join(timeout=1.0)
+
+
+@dashboard_app.command("dev")
+def dashboard_dev(
+ api_host: str = typer.Option("127.0.0.1", "--api-host", help="Backend API host."),
+ api_port: int = typer.Option(8080, "--api-port", help="Backend API port."),
+ ui_host: str = typer.Option("127.0.0.1", "--ui-host", help="Frontend dev host."),
+ ui_port: int = typer.Option(5173, "--ui-port", help="Frontend dev port."),
+ open_browser: bool = typer.Option(
+ True,
+ "--open/--no-open",
+ help="Open the dashboard URL in the default browser.",
+ ),
+ reload: bool = typer.Option(
+ True,
+ "--reload/--no-reload",
+ help="Run uvicorn with reload enabled.",
+ ),
+ install: bool = typer.Option(
+ False,
+ "--install",
+ help="Run npm ci in frontend/ if node_modules is missing.",
+ ),
+) -> None:
+ """Run the FastAPI backend and Vite dashboard dev server together."""
+ exit_code = _run_dashboard_dev(
+ api_host=api_host,
+ api_port=api_port,
+ ui_host=ui_host,
+ ui_port=ui_port,
+ open_browser=open_browser,
+ reload=reload,
+ install=install,
+ )
+ if exit_code:
+ raise typer.Exit(exit_code)
+
+
@app.command("quickstart")
def quickstart() -> None:
"""Guided wizard for first-time users — creates your first campaign."""
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index ef437d5..8912f94 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -9,6 +9,47 @@ Production URL:
http://localhost:8080/dashboard
```
+## Local Developer Startup
+
+Recommended local dashboard startup from the repository root:
+
+```bash
+ares dashboard dev
+```
+
+This one-terminal launcher starts:
+
+- Backend API: `python -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload`
+- Frontend: `npm run dev -- --host 127.0.0.1 --port 5173`
+
+It prints `http://127.0.0.1:5173/dashboard/`, opens it by default, and stops
+both child processes when you press `Ctrl+C`. Login with username `admin` and
+the value of `ARES_DEFAULT_ADMIN_PASSWORD` from `.env`; the launcher does not
+print that password. Use `ares dashboard dev --no-open` to skip browser open,
+or `ares dashboard dev --install` to run `npm ci` if `frontend/node_modules`
+is missing.
+
+Manual fallback for troubleshooting:
+
+Terminal 1:
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload
+```
+
+Terminal 2:
+
+```powershell
+cd frontend
+"C:\Program Files\nodejs\npm.cmd" run dev -- --host 127.0.0.1 --port 5173
+```
+
+Open:
+
+```text
+http://127.0.0.1:5173/dashboard/
+```
+
## Screenshot Set
The dashboard screenshots in this repository use local/demo data only. Do not
@@ -76,6 +117,17 @@ first login. For disposable local development data, recreate the local
database only when you intentionally want to discard existing users and
campaign data.
+Local development reset warning: this deletes local dashboard data in
+`ares.db`. Do not use it on real or shared deployments.
+
+```powershell
+New-Item -ItemType Directory -Force ".\_db_backup" | Out-Null
+if (Test-Path ".\ares.db") {
+ Copy-Item ".\ares.db" ".\_db_backup\ares.db.before-reset" -Force
+}
+Remove-Item ".\ares.db" -Force -ErrorAction SilentlyContinue
+```
+
Additional users are created by a `team_lead` through `POST /auth/register`.
The dashboard currently shows users in the `Security` page, but it does not
include a role editor. In the current release, the role is assigned when the
diff --git a/docs/frontend.md b/docs/frontend.md
index b5be7c0..e0b79fa 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -5,11 +5,29 @@ for the FastAPI backend.
## Runtime
-- Development: `cd frontend && npm ci && npm run dev`
+- Development: run `ares dashboard dev` from the repository root. It starts
+ the FastAPI API on `http://127.0.0.1:8080` and the Vite dashboard on
+ `http://127.0.0.1:5173/dashboard/` in one terminal.
+- Browser open can be skipped with `ares dashboard dev --no-open`.
+- If `frontend/node_modules` is missing, run `ares dashboard dev --install` or
+ `cd frontend && npm ci`.
- Production: `npm run build`, then FastAPI serves `frontend/dist` at `/dashboard`
- Vite base path: `/dashboard/`
- API proxy: main FastAPI routes, not legacy dashboard shadow routes
+Manual fallback for troubleshooting:
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload
+```
+
+```powershell
+cd frontend
+"C:\Program Files\nodejs\npm.cmd" run dev -- --host 127.0.0.1 --port 5173
+```
+
+Then open `http://127.0.0.1:5173/dashboard/`.
+
## Auth
- Login calls `POST /auth/token` with `application/x-www-form-urlencoded`.
diff --git a/tests/unit/test_dashboard_dev_launcher.py b/tests/unit/test_dashboard_dev_launcher.py
new file mode 100644
index 0000000..e29c361
--- /dev/null
+++ b/tests/unit/test_dashboard_dev_launcher.py
@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import pytest
+import typer
+
+
+def _make_repo(root: Path, *, node_modules: bool = True) -> None:
+ (root / "pyproject.toml").write_text("[project]\nname='ares-test'\n", encoding="utf-8")
+ frontend = root / "frontend"
+ frontend.mkdir()
+ (frontend / "package.json").write_text('{"scripts":{"dev":"vite"}}\n', encoding="utf-8")
+ if node_modules:
+ (frontend / "node_modules").mkdir()
+
+
+def test_find_repo_root_discovers_parent(tmp_path, monkeypatch):
+ from ares.cli.typer_main import find_repo_root
+
+ _make_repo(tmp_path)
+ child = tmp_path / "docs" / "nested"
+ child.mkdir(parents=True)
+ monkeypatch.chdir(child)
+
+ assert find_repo_root() == tmp_path
+
+
+def test_resolve_npm_command_windows_prefers_program_files(tmp_path):
+ from ares.cli.typer_main import resolve_npm_command
+
+ preferred = tmp_path / "npm.cmd"
+ preferred.write_text("@echo off\n", encoding="utf-8")
+
+ def fake_which(name: str) -> str | None:
+ return f"fallback-{name}"
+
+ assert resolve_npm_command(
+ os_name="nt",
+ program_files_npm=preferred,
+ which=fake_which,
+ ) == str(preferred)
+
+
+def test_dashboard_dev_command_builders():
+ from ares.cli.typer_main import build_backend_command, build_frontend_command
+
+ assert build_backend_command(
+ "127.0.0.1",
+ 8080,
+ reload=False,
+ python_executable="python-test",
+ ) == [
+ "python-test",
+ "-m",
+ "uvicorn",
+ "ares.api.server:app",
+ "--host",
+ "127.0.0.1",
+ "--port",
+ "8080",
+ ]
+ assert "--reload" in build_backend_command("127.0.0.1", 8080)
+ assert build_frontend_command("npm.cmd", "127.0.0.1", 5173) == [
+ "npm.cmd",
+ "run",
+ "dev",
+ "--",
+ "--host",
+ "127.0.0.1",
+ "--port",
+ "5173",
+ ]
+
+
+def test_dashboard_dev_missing_node_modules_prints_clear_instruction(tmp_path, capsys):
+ from ares.cli.typer_main import _run_dashboard_dev
+
+ _make_repo(tmp_path, node_modules=False)
+
+ with pytest.raises(typer.Exit):
+ _run_dashboard_dev(root=tmp_path, open_browser=False)
+
+ output = capsys.readouterr().out
+ assert "frontend/node_modules is missing" in output
+ assert "npm ci" in output
+ assert "--install" in output
+
+
+def test_dashboard_dev_install_runs_npm_ci_when_requested(tmp_path):
+ from ares.cli.typer_main import _ensure_frontend_dependencies
+
+ _make_repo(tmp_path, node_modules=False)
+ calls = []
+
+ def fake_run(command, **kwargs):
+ calls.append((command, kwargs))
+ return subprocess.CompletedProcess(command, 0)
+
+ _ensure_frontend_dependencies(
+ tmp_path / "frontend",
+ "npm.cmd",
+ install=True,
+ run_func=fake_run,
+ )
+
+ assert calls == [
+ (
+ ["npm.cmd", "ci"],
+ {"cwd": str(tmp_path / "frontend"), "check": False},
+ )
+ ]
+
+
+def test_dashboard_dev_launches_both_processes_and_cleans_up(monkeypatch, tmp_path, capsys):
+ from ares.cli import typer_main
+
+ _make_repo(tmp_path, node_modules=True)
+ (tmp_path / ".env").write_text(
+ "ARES_DEFAULT_ADMIN_PASSWORD=DoNotPrintThisSecret123!\n",
+ encoding="utf-8",
+ )
+
+ launched = []
+ opened = []
+ taskkill_calls = []
+
+ class FakeProcess:
+ _next_pid = 4000
+
+ def __init__(self, command, **kwargs):
+ self.command = command
+ self.kwargs = kwargs
+ self.pid = FakeProcess._next_pid
+ FakeProcess._next_pid += 1
+ self.stdout = []
+ self.stopped = False
+ self.signals = []
+ launched.append(self)
+
+ def poll(self):
+ return 0 if self.stopped else None
+
+ def send_signal(self, sig):
+ self.signals.append(sig)
+ self.stopped = True
+
+ def terminate(self):
+ self.stopped = True
+
+ def wait(self, timeout=None):
+ self.stopped = True
+ return 0
+
+ def kill(self):
+ self.stopped = True
+
+ def fake_popen(command, **kwargs):
+ return FakeProcess(command, **kwargs)
+
+ def interrupt(_seconds: float):
+ raise KeyboardInterrupt
+
+ monkeypatch.setattr(typer_main, "resolve_npm_command", lambda os_name=None: "npm.cmd")
+
+ def fake_run(command, **kwargs):
+ taskkill_calls.append((command, kwargs))
+ return subprocess.CompletedProcess(command, 0)
+
+ monkeypatch.setattr(typer_main.subprocess, "run", fake_run)
+
+ exit_code = typer_main._run_dashboard_dev(
+ root=tmp_path,
+ os_name="nt",
+ open_browser=False,
+ popen_factory=fake_popen,
+ wait_for_port_func=lambda *args, **kwargs: True,
+ open_browser_func=lambda url: opened.append(url),
+ sleep_func=interrupt,
+ )
+
+ assert exit_code == 0
+ assert len(launched) == 2
+ assert launched[0].command[:4] == [
+ typer_main.sys.executable,
+ "-m",
+ "uvicorn",
+ "ares.api.server:app",
+ ]
+ assert launched[1].command == [
+ "npm.cmd",
+ "run",
+ "dev",
+ "--",
+ "--host",
+ "127.0.0.1",
+ "--port",
+ "5173",
+ ]
+ assert launched[0].kwargs["cwd"] == str(tmp_path)
+ assert launched[1].kwargs["cwd"] == str(tmp_path / "frontend")
+ assert opened == []
+ assert all(process.stopped for process in launched)
+ assert [call[0][:2] for call in taskkill_calls] == [
+ ["taskkill", "/PID"],
+ ["taskkill", "/PID"],
+ ]
+ assert all("/T" in call[0] and "/F" in call[0] for call in taskkill_calls)
+
+ output = capsys.readouterr().out
+ assert "Dashboard URL: http://127.0.0.1:5173/dashboard/" in output
+ assert "Login username: admin" in output
+ assert "Login password: value of ARES_DEFAULT_ADMIN_PASSWORD in .env" in output
+ assert "DoNotPrintThisSecret123!" not in output