@bhooai/nexus-cli 0.1.0

package/templates/apps/ai-server/routers/lint.py

@@ -0,0 +1,167 @@
+"""Env + config linter router.
+
+Node sends the raw `.env` text (and the raw `nexus.runtime.json` text) and
+Python computes a structured report. Python never echoes secret *values* — only
+keys + issues. This keeps the lint logic in Python while Node owns auth + file
+access. There is no `.env.example` anymore: secrets live directly in `.env`.
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+router = APIRouter()
+
+ALLOWED_LOG_LEVELS = {"silent", "fatal", "error", "warn", "info", "debug", "trace"}
+
+
+class LintEnvRequest(BaseModel):
+    envText: str = ""
+
+
+class LintConfigRequest(BaseModel):
+    content: str = ""
+
+
+# ---- env parsing helpers ----
+
+def _parse_env(text: str) -> tuple[list[dict[str, Any]], list[str]]:
+    """Parse dotenv-ish text. Returns (exports, malformed_lines)."""
+    exports: list[dict[str, Any]] = []
+    malformed: list[str] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            malformed.append(f"line {lineno}: no '=' found")
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        exports.append({"key": key, "value": value})
+    return exports, malformed
+
+
+_PLACEHOLDER_PATTERNS = [
+    r"^(change|changeme|change-me|your|example|exampl|replace|dummy|sample)",
+    r"^xxxx+$",
+    r"^xxxx+",
+]
+
+
+def _is_placeholder(value: str) -> bool:
+    if len(value.strip()) < 4:
+        return True
+    lowered = value.strip().lower()
+    return any(re.search(p, lowered) for p in _PLACEHOLDER_PATTERNS)
+
+
+# ---- env checks ----
+
+def _check_env(exports: list[dict[str, Any]], malformed: list[str]) -> list[dict[str, Any]]:
+    checks: list[dict[str, Any]] = []
+    seen: dict[str, int] = {}
+    for e in exports:
+        k = e["key"]
+        count = seen.get(k, 0) + 1
+        seen[k] = count
+        if count > 1:
+            checks.append({"key": k, "severity": "error", "kind": "duplicate", "message": "duplicate key"})
+        if e["value"] == "":
+            checks.append({"key": k, "severity": "warning", "kind": "empty", "message": "has an empty value"})
+        elif _is_placeholder(e["value"]):
+            checks.append({"key": k, "severity": "warning", "kind": "placeholder", "message": "value still looks like a placeholder"})
+    for line in malformed:
+        checks.append({"key": "(syntax)", "severity": "error", "kind": "malformed", "message": line})
+    env = {f["key"] for f in exports}
+    if "NEXUS_AUTH_JWT_SECRET" not in env:
+        checks.append({"key": "NEXUS_AUTH_JWT_SECRET", "severity": "warning", "kind": "missing", "message": "set this in .env — there is no default JWT secret"})
+    return checks
+
+
+# ---- config checks ----
+
+def _config_checks(data: dict[str, Any]) -> list[dict[str, Any]]:
+    checks: list[dict[str, Any]] = []
+    port = _get(data, "server.port")
+    if port is not None and not (isinstance(port, (int, float)) and 1 <= int(port) <= 65535):
+        checks.append({"key": "server.port", "severity": "error", "kind": "type", "message": "must be an integer port 1–65535"})
+    body = _get(data, "server.bodyLimit")
+    if body is not None and not isinstance(body, (int, float)):
+        checks.append({"key": "server.bodyLimit", "severity": "warning", "kind": "type", "message": "must be a number (bytes)"})
+    lvl = _get(data, "logging.level")
+    if lvl is not None and lvl not in ALLOWED_LOG_LEVELS:
+        checks.append({"key": "logging.level", "severity": "warning", "kind": "value", "message": f"unexpected level '{lvl}' (expected one of {sorted(ALLOWED_LOG_LEVELS)})"})
+    uri = _get(data, "db.uri")
+    if uri is not None and not (isinstance(uri, str) and uri.startswith(("mongodb://", "mongodb+srv://"))):
+        checks.append({"key": "db.uri", "severity": "error", "kind": "url", "message": "must be a mongodb:// or mongodb+srv:// URL"})
+    auto = _get(data, "db.autoIndex")
+    if auto is not None and not isinstance(auto, bool):
+        checks.append({"key": "db.autoIndex", "severity": "warning", "kind": "type", "message": "must be a boolean"})
+    intro = _get(data, "graphql.introspection")
+    if intro is not None and not isinstance(intro, bool):
+        checks.append({"key": "graphql.introspection", "severity": "warning", "kind": "type", "message": "must be a boolean"})
+    return checks
+
+
+def _get(doc: dict[str, Any], path: str) -> Any:
+    node: Any = doc
+    for part in path.split("."):
+        if isinstance(node, dict) and part in node:
+            node = node[part]
+        else:
+            return None
+    return node
+
+
+# ---- report ----
+
+def _report(checks: list[dict[str, Any]]) -> dict[str, Any]:
+    summary = {"error": 0, "warning": 0, "info": 0, "ok": 0}
+    for c in checks:
+        sev = c["severity"] if c["severity"] in summary else "info"
+        summary[sev] += 1
+    if not checks:
+        summary["ok"] = 1
+    order = {"error": 0, "warning": 1, "info": 2, "ok": 9}
+    checks.sort(key=lambda c: (order.get(c["severity"], 9), c["key"]))
+    return {"ranAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "summary": summary, "checks": checks}
+
+
+# ---- routes ----
+
+@router.post("/lint/env")
+async def lint_env(req: LintEnvRequest):
+    exports, malformed = _parse_env(req.envText)
+    checks = _check_env(exports, malformed)
+    return _report(checks)
+
+
+@router.post("/lint/config")
+async def lint_config(req: LintConfigRequest):
+    try:
+        doc = json.loads(req.content)
+    except json.JSONDecodeError as e:
+        return {
+            "ranAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "summary": {"error": 1, "warning": 0, "info": 0, "ok": 0},
+            "checks": [
+                {"key": "(syntax)", "severity": "error", "kind": "malformed",
+                 "message": f"not valid JSON: {e} at line {e.lineno} col {e.colno}"}
+            ],
+        }
+    if not isinstance(doc, dict):
+        return {
+            "ranAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "summary": {"error": 1, "warning": 0, "info": 0, "ok": 0},
+            "checks": [{"key": "(root)", "severity": "error", "kind": "type", "message": "config root must be a JSON object"}],
+        }
+    return _report(_config_checks(doc))

package/templates/apps/ai-server/routers/models.py

@@ -0,0 +1,23 @@
+"""Models router — lists available upstream models."""
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from fastapi.params import Query
+
+from providers import get_provider
+
+router = APIRouter()
+
+
+@router.get("/models")
+async def list_models(provider: str | None = Query(default=None)):
+    try:
+        p = get_provider(provider)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    try:
+        return await p.list_models()
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"upstream error: {e}")

package/templates/apps/ai-server/routers/preflight.py

@@ -0,0 +1,169 @@
+"""Preflight diagnostics router — connectivity + latency checks.
+
+The Node backend composes the targets it wants checked (backend health, AI
+server health, Mongo/Redis TCP reachability, service ports) and posts them here.
+Python performs the checks concurrently and returns a normalized report. Only
+stdlib (`socket`) + httpx are used, so this router adds no new dependencies.
+
+Failed checks carry an `errorCategory` (refused/timeout/dns/ssl/http/other) plus
+a short human-readable `error` message so the admin console never has to surface
+raw transport exceptions like httpx's "All connection attempts failed...".
+"""
+from __future__ import annotations
+
+import asyncio
+import socket
+import ssl
+import time
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+import httpx
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class Target(BaseModel):
+    name: str
+    kind: Literal["http", "tcp"] = "tcp"
+    url: str | None = None
+    host: str | None = None
+    port: int | None = None
+    timeout: float | None = None
+
+
+class PreflightRequest(BaseModel):
+    targets: list[Target] = []
+    timeout: float = 2.0
+
+
+def _classify_error(e: Exception, host: str = "", port: int | None = None) -> tuple[str, str]:
+    """Map an exception to a (category, friendly message) pair.
+
+    httpx wraps low-level socket errors, so when the top-level exception is the
+    generic "All connection attempts failed..." the underlying cause is unwrapped.
+    """
+    endpoint = f"{host}:{port}" if host else "target"
+
+    if isinstance(e, (httpx.ConnectTimeout, httpx.ConnectError, asyncio.TimeoutError, socket.timeout)):
+        try:
+            cause = e.__cause__
+        except AttributeError:
+            cause = None
+        if isinstance(cause, socket.gaierror):
+            return "dns", f"host not found: {host or 'unknown'}"
+        if isinstance(cause, (ConnectionRefusedError, OSError)) and getattr(cause, "errno", None) == getattr(socket, "ECONNREFUSED", 111):
+            return "refused", f"connection refused on {endpoint} — is the service running?"
+        return "timeout", "timed out — the service may be filtering traffic or is down"
+
+    if isinstance(e, socket.gaierror):
+        return "dns", f"host not found: {host or 'unknown'}"
+    if isinstance(e, (ConnectionRefusedError, OSError)) and getattr(e, "errno", None) == getattr(socket, "ECONNREFUSED", 111):
+        return "refused", f"connection refused on {endpoint} — is the service running?"
+    if isinstance(e, ssl.SSLError):
+        return "ssl", "TLS handshake failed"
+    return "other", str(e) or type(e).__name__
+
+
+async def _check_http(target: Target, timeout: float) -> dict[str, Any]:
+    url = target.url or ""
+    start = time.perf_counter()
+    try:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=1.0, read=timeout, write=timeout, pool=timeout), follow_redirects=True) as client:
+            resp = await client.get(url)
+        latency_ms = round((time.perf_counter() - start) * 1000, 1)
+        ok = resp.status_code < 400
+        category: str | None = None
+        error: str | None = None
+        if not ok:
+            category = "http"
+            error = f"HTTP {resp.status_code}"
+        return {
+            "name": target.name,
+            "kind": "http",
+            "url": url,
+            "ok": ok,
+            "status": resp.status_code,
+            "latencyMs": latency_ms,
+            "errorCategory": category,
+            "error": error,
+        }
+    except Exception as e:  # noqa: BLE001 - classify connectivity errors
+        latency_ms = round((time.perf_counter() - start) * 1000, 1)
+        category, message = _classify_error(e, urlparse(url).hostname or "", urlparse(url).port)
+        return {
+            "name": target.name,
+            "kind": "http",
+            "url": url,
+            "ok": False,
+            "status": None,
+            "latencyMs": latency_ms,
+            "errorCategory": category,
+            "error": message,
+        }
+
+
+async def _check_tcp(target: Target, timeout: float) -> dict[str, Any]:
+    host = target.host or ""
+    port = target.port or 0
+    start = time.perf_counter()
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(host, port, limit=256),
+            timeout,
+        )
+        latency_ms = round((time.perf_counter() - start) * 1000, 1)
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except Exception:  # noqa: BLE001
+            pass
+        return {
+            "name": target.name,
+            "kind": "tcp",
+            "host": host,
+            "port": port,
+            "ok": True,
+            "latencyMs": latency_ms,
+            "errorCategory": None,
+            "error": None,
+        }
+    except Exception as e:  # noqa: BLE001 - classify connectivity errors
+        latency_ms = round((time.perf_counter() - start) * 1000, 1)
+        category, message = _classify_error(e, host, port)
+        return {
+            "name": target.name,
+            "kind": "tcp",
+            "host": host,
+            "port": port,
+            "ok": False,
+            "latencyMs": latency_ms,
+            "errorCategory": category,
+            "error": message,
+        }
+
+
+@router.post("/preflight")
+async def preflight(req: PreflightRequest):
+    if not req.targets:
+        raise HTTPException(status_code=400, detail="at least one target is required")
+    started = time.perf_counter()
+    results = await asyncio.gather(*(_check_http(t, t.timeout or req.timeout) if t.kind == "http" else _check_tcp(t, t.timeout or req.timeout) for t in req.targets))
+    duration_ms = round((time.perf_counter() - started) * 1000, 1)
+
+    failed = [c for c in results if not c["ok"]]
+    passed = [c for c in results if c["ok"]]
+    # failed then warnings (slow) then the rest, preserving stable order within groups.
+    slow = [c for c in passed if isinstance(c.get("latencyMs"), (int, float)) and c["latencyMs"] > 800]
+    ok = [c for c in passed if c not in slow]
+
+    return {
+        "ranAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "durationMs": duration_ms,
+        "passed": len(passed),
+        "warnings": len(slow),
+        "failed": len(failed),
+        "checks": failed + slow + ok,
+    }

package/templates/apps/ai-server/settings.py

@@ -0,0 +1,48 @@
+"""Configuration for the AI server (env-driven)."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _env(key: str, default: str) -> str:
+    return os.environ.get(key, default)
+
+
+@dataclass
+class Settings:
+    # OpenAI-compatible upstreams. Both OpenAI and Ollama speak the same shape;
+    # only the base URL + auth header differ.
+    openai_base_url: str = field(default_factory=lambda: _env("AI_OPENAI_BASE_URL", "https://api.openai.com/v1"))
+    # Fall back to the generic OPENAI_API_KEY / OLLAMA_HOST names so project
+    # .env keys work with the AI server as well as the AI_* names.
+    openai_api_key: str = field(
+        default_factory=lambda: _env("AI_OPENAI_API_KEY", _env("OPENAI_API_KEY", ""))
+    )
+    ollama_base_url: str = field(
+        default_factory=lambda: _env(
+            "AI_OLLAMA_BASE_URL",
+            (_env("OLLAMA_HOST", "http://localhost:11434") + "/v1"),
+        )
+    )
+    ollama_api_key: str = field(default_factory=lambda: _env("AI_OLLAMA_API_KEY", ""))
+
+    default_provider: str = field(default_factory=lambda: _env("AI_DEFAULT_PROVIDER", "auto"))
+    request_timeout_s: float = field(default_factory=lambda: float(_env("AI_TIMEOUT_S", "120")))
+    server_port: int = field(default_factory=lambda: int(_env("AI_PORT", "8000")))
+
+    # CORS: the Node backend proxies, but allow dev tools + the admin to call directly.
+    cors_origins: list[str] = field(default_factory=lambda: _env("AI_CORS_ORIGINS", "*").split(","))
+
+
+settings = Settings()
+
+
+def resolve_provider(requested: str | None) -> str:
+    """Resolve 'auto' to a concrete provider. auto → openai if a key is set, else ollama."""
+    provider = (requested or settings.default_provider or "auto").lower()
+    if provider == "auto":
+        provider = "openai" if settings.openai_api_key else "ollama"
+    if provider not in ("openai", "ollama"):
+        raise ValueError(f"unknown provider: {provider}")
+    return provider

package/templates/apps/backend/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@bhooai/app-backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/main.ts",
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "start": "tsx src/main.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "*",
+    "@bhooai/nexus-auth": "*",
+    "@bhooai/nexus-telemetry": "*",
+    "@bhooai/nexus-data": "*",
+    "@bhooai/nexus-realtime": "*",
+    "@bhooai/nexus-graphql": "*",
+    "@bhooai/nexus-cache": "*",
+    "@bhooai/nexus-email": "*",
+    "@bhooai/nexus-payments": "*",
+    "@bhooai/nexus-crypto": "*",
+    "@bhooai/nexus-ads": "*",
+    "@bhooai/nexus-plugins": "*",
+    "@bhooai/nexus-ai-client": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}