enderofwings/NexusOS
1
0
Fork 1
Code Issues Pull Requests 1 Actions 10 Packages Projects Releases Wiki Activity

feat(packaging): move the CLI into nexusos_cli and make the wheel self-sufficient

Browse Source 
The CLI shipped from `management/`, which also holds desktop-only pieces (the
Tk control panel, the XFCE panel wiring, the shell wrappers). Packaging that
directory meant the wheel either dragged in tkinter or shipped a broken import.
Split it: `nexusos_cli/` is what the wheel ships and what `nexus`/`ncp`/
`nexusos` dispatch to, `management/` keeps the desktop half.

Alongside the move:

* hatch_build.py decides the interface/web/dist include at build time. dist/
  is gitignored, so a static force-include aborts `pip install -e .` on a
  fresh clone - before the reader reaches the `npm run build` step. Editable
  installs now skip a missing dist; wheels and sdists hard-error naming the
  command to run.
* synapse/proc_util.py gives frontend_manager and ncp process inspection and
  termination without psutil, which became an optional extra when the wheel
  landed. It routes around Windows having no signals, where os.kill(pid, 15)
  is an unblockable TerminateProcess rather than a polite request.
* nexusos_cli/monitor.py adds `ncp monitor`, an ASCII dashboard with no curses
  or rich dependency so it works in Termux, plain SSH and Windows Terminal.
  Collector and renderer are separate so tests feed fixtures, no stack needed.
* tests/test_packaging_deps.py fails the gate when synapse or nexusos_cli
  import a distribution pyproject does not declare, and when an optional
  dependency is imported at module scope instead of lazily.
* bin/check.sh now builds the wheel, twine-checks it, and asserts the compiled
  UI and seed playbooks are actually inside it. A wheel that builds but ships
  no dist/ serves a blank page, which only shows up after release.

tests/test_nexus_api.py moves to tests/ with the module it covers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Athena Kaminsky
2026-08-26 08:11:39 -05:00
committed by Athena
co-authored by Claude Opus 5
parent d579502a5b
commit 9104c724c4
25 changed files with 1412 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nexusos_cli/__init__.py
+7
View File
@@ -0,0 +1,7 @@
"""The portable NexusOS command line, shipped in the wheel.
Kept out of `management/` so the installed distribution does not claim a
top-level `management` package name in site-packages. `management/` stays in
the source checkout for the desktop-only pieces - the Tk control panel, the
shell wrappers, the XFCE panel and .desktop wiring.
"""
nexusos_cli/cli.py
+849
View File
@@ -0,0 +1,849 @@
"""Portable NexusOS command line used by the ``nexus`` and ``ncp`` scripts."""
from __future__ import annotations
import argparse
import importlib.util
import json
import os
import shutil
import subprocess
import sys
import time
import urllib.error
import urllib.request
import webbrowser
from pathlib import Path
from urllib.parse import urlparse
from synapse import nexus_config as config
from synapse.nexus_config import settings
from . import ncp as services
CONFIG_SCHEMA = {
"home": "path",
"api_url": "url",
"memory_url": "url",
"bind_host": "text",
"backend_port": "port",
"memory_port": "port",
"provider": "provider",
"provider_url": "url",
"provider_timeout": "positive_int",
"data_dir": "path",
"models_dir": "path",
"runtime_dir": "path",
"memory_dir": "path",
"memory_db": "path",
}
LEGACY_TARGETS = {
"-m": "memory",
"--memory": "memory",
"-b": "backend",
"--backend": "backend",
"-f": "frontend",
"--frontend": "frontend",
"-a": "ai",
"--ai": "ai",
}
def _emit(payload, json_output: bool = False) -> None:
if json_output:
print(json.dumps(payload, indent=2, sort_keys=True))
elif isinstance(payload, str):
print(payload)
else:
for key, value in payload.items():
print(f"{key}: {value}")
def _http_ok(url: str, timeout: float = 1.0) -> bool:
try:
urllib.request.urlopen(url, timeout=timeout).read(1)
return True
except urllib.error.HTTPError:
return True
except Exception:
return False
def _is_termux() -> bool:
prefix = os.getenv("PREFIX", "")
return "com.termux" in prefix or bool(os.getenv("TERMUX_VERSION"))
def _validate_config(key: str, raw: str):
kind = CONFIG_SCHEMA[key]
value = raw.strip()
if kind == "url":
parsed = urlparse(value)
if parsed.scheme not in ("http", "https") or not parsed.netloc:
raise ValueError(f"{key} must be an http(s) URL")
return value.rstrip("/")
if kind == "port":
number = int(value)
if not 1 <= number <= 65535:
raise ValueError(f"{key} must be between 1 and 65535")
return number
if kind == "positive_int":
number = int(value)
if number <= 0:
raise ValueError(f"{key} must be greater than zero")
return number
if kind == "provider":
if value not in ("ollama", "ollama-remote"):
raise ValueError("provider must be ollama or ollama-remote")
return value
if kind == "path":
return str(Path(value).expanduser().resolve())
if not value:
raise ValueError(f"{key} cannot be empty")
return value
def cmd_init(args) -> int:
config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
copied = list(config.INITIALIZED_FILES) + config.init_state()
payload = {
"status": "initialized",
"state_dir": str(settings.state_dir),
"config_file": str(settings.config_file),
"data_dir": str(settings.data_dir),
"models_dir": str(settings.models_dir),
"runtime_dir": str(settings.runtime_dir),
"seeded_playbooks": len(copied),
}
_emit(payload, args.json)
return 0
def cmd_paths(args) -> int:
payload = {
"install_mode": "checkout" if settings.source_checkout else "wheel",
"project_root": str(settings.project_root),
"resource_root": str(settings.resource_root),
"state_dir": str(settings.state_dir),
"config_file": str(settings.config_file),
"data_dir": str(settings.data_dir),
"memory_db": str(settings.memory_db),
"models_dir": str(settings.models_dir),
"runtime_dir": str(settings.runtime_dir),
"web_dist_dir": str(settings.web_dist_dir),
}
_emit(payload, args.json)
return 0
# Keys whose value decides where the SQLite database is looked up. Changing one
# does not move the file, so the next start would quietly open a fresh, empty
# database and the user's conversations and memories would look deleted.
_DB_LOCATION_KEYS = ("memory_db", "memory_dir", "data_dir", "home")
def _relocation_warning(key: str, value) -> str | None:
"""Warn when a config change points the database somewhere with no data."""
if key not in _DB_LOCATION_KEYS:
return None
current = settings.memory_db
if not current.is_file():
return None
if key == "memory_db":
new_db = Path(str(value))
elif key == "memory_dir":
new_db = Path(str(value)) / current.name
else:
# data_dir/home only decide the DB location when nothing more specific
# does, and only in the layout where the DB actually sits under them -
# a source checkout keeps it in synapse/memory/ regardless.
existing = config.read_user_config()
if "memory_dir" in existing or "memory_db" in existing:
return None
anchor = settings.data_dir if key == "data_dir" else settings.state_dir
try:
tail = current.resolve().relative_to(anchor.resolve())
except ValueError:
return None
new_db = Path(str(value)) / tail
if new_db.resolve() == current.resolve() or new_db.is_file():
return None
return (
f"{current} holds your existing conversations and memories, but this "
f"change points NexusOS at {new_db}, which does not exist yet - it will "
"start with an empty database. Stop NexusOS and move the .db (plus any "
"-wal/-shm files) to the new path to keep your history."
)
def cmd_config(args) -> int:
values = config.read_user_config()
if args.action == "path":
print(config.CONFIG_FILE)
return 0
if args.action == "list":
_emit(values, args.json)
return 0
if args.action == "get":
if args.key not in CONFIG_SCHEMA:
print(f"Unknown configuration key: {args.key}", file=sys.stderr)
return 2
value = values.get(args.key, getattr(settings, args.key, None))
_emit({args.key: value}, args.json)
return 0
if args.action == "set":
if args.key not in CONFIG_SCHEMA:
print(f"Unknown configuration key: {args.key}", file=sys.stderr)
print("Known keys: " + ", ".join(CONFIG_SCHEMA), file=sys.stderr)
return 2
try:
values[args.key] = _validate_config(args.key, args.value)
except (TypeError, ValueError) as exc:
print(f"Invalid value: {exc}", file=sys.stderr)
return 2
payload = {"updated": args.key, "value": values[args.key], "restart_required": True}
moved = _relocation_warning(args.key, values[args.key])
if moved:
payload["warning"] = moved
config.write_user_config(values)
_emit(payload, args.json)
if moved and not args.json:
print(f"\nWARNING: {moved}", file=sys.stderr)
return 0
if args.action == "unset":
if args.key not in CONFIG_SCHEMA:
print(f"Unknown configuration key: {args.key}", file=sys.stderr)
return 2
values.pop(args.key, None)
config.write_user_config(values)
_emit({"removed": args.key, "restart_required": True}, args.json)
return 0
return 2
def _provider_payload() -> dict:
url = settings.ollama_host.rstrip("/")
return {
"provider": settings.provider,
"url": url,
"managed_by_nexus": settings.manage_ollama,
"reachable": _http_ok(url + "/api/tags", timeout=2.0),
}
def cmd_provider(args) -> int:
if args.action == "show":
_emit(_provider_payload(), args.json)
return 0
values = config.read_user_config()
if args.mode == "local":
values["provider"] = "ollama"
try:
values["provider_url"] = _validate_config(
"provider_url", args.url or "http://127.0.0.1:11434"
)
except ValueError as exc:
print(f"Invalid value: {exc}", file=sys.stderr)
return 2
else:
if not args.url:
print("Remote provider setup requires --url", file=sys.stderr)
return 2
try:
values["provider_url"] = _validate_config("provider_url", args.url)
except ValueError as exc:
print(f"Invalid value: {exc}", file=sys.stderr)
return 2
values["provider"] = "ollama-remote"
config.write_user_config(values)
_emit({
"provider": values["provider"],
"url": values["provider_url"],
"restart_required": True,
}, args.json)
return 0
def _check_import(module: str) -> bool:
return importlib.util.find_spec(module) is not None
def _writable(path: Path) -> bool:
try:
path.mkdir(parents=True, exist_ok=True)
probe = path / ".nexus-write-test"
probe.write_text("ok", encoding="utf-8")
probe.unlink()
return True
except OSError:
return False
def diagnostics() -> dict:
checks: list[dict] = []
def add(name: str, ok: bool, detail: str, required: bool = True):
checks.append({
"name": name,
"status": "pass" if ok else ("fail" if required else "warn"),
"detail": detail,
"required": required,
})
add("python", sys.version_info >= (3, 11), sys.version.split()[0])
add("state", _writable(settings.state_dir), str(settings.state_dir))
add("database directory", _writable(settings.memory_db.parent), str(settings.memory_db.parent))
add("web assets", (settings.web_dist_dir / "index.html").is_file(), str(settings.web_dist_dir))
add(
"provider mode",
settings.provider in ("ollama", "ollama-remote"),
settings.provider,
)
add(
"service ports",
all(1 <= port <= 65535 for port in (settings.backend_port, settings.memory_port)),
f"backend={settings.backend_port}, memory={settings.memory_port}",
)
for module in ("fastapi", "uvicorn", "httpx", "pydantic", "yaml"):
add(f"import:{module}", _check_import(module), module)
add("backend", _http_ok(settings.api_url + "/status"), settings.api_url, required=False)
add("memory service", _http_ok(settings.memory_url + "/"), settings.memory_url, required=False)
provider = _provider_payload()
add("provider", provider["reachable"], provider["url"], required=False)
if settings.manage_ollama:
add("ollama executable", bool(services.ollama_bin()), services.ollama_bin() or "not on PATH", required=False)
for label, module in (
("process control", "psutil"),
("vector search", "sqlite_vec"),
("voice transcription", "faster_whisper"),
("PDF documents", "pypdf"),
("Word documents", "docx"),
("web search", "duckduckgo_search"),
):
add(label, _check_import(module), module, required=False)
return {
"ok": not any(c["status"] == "fail" for c in checks),
"version": settings.version,
"install_mode": "checkout" if settings.source_checkout else "wheel",
"platform": sys.platform,
"termux": _is_termux(),
"checks": checks,
}
def _doctor_fix() -> None:
config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
config.init_state()
index = settings.web_dist_dir / "index.html"
npm = shutil.which("npm.cmd" if os.name == "nt" else "npm")
if settings.source_checkout and not index.exists() and npm:
subprocess.run([npm, "run", "build"], cwd=str(settings.frontend_source_dir), check=False)
def cmd_doctor(args) -> int:
if args.fix:
_doctor_fix()
result = diagnostics()
if args.json:
_emit(result, True)
else:
print(f"NexusOS {result['version']} diagnostics ({result['install_mode']})\n")
marks = {"pass": "OK", "warn": "WARN", "fail": "FAIL"}
for check in result["checks"]:
print(f" {marks[check['status']]:<4} {check['name']:<20} {check['detail']}")
print("\nCore runtime is ready." if result["ok"] else "\nCore runtime has required failures.")
return 0 if result["ok"] else 1
def service_status() -> dict:
payload = {}
for key in ("backend", "memory", "frontend"):
svc = services.SERVICES[key]
pid = services.read_pid(svc)
payload[key] = {
"running": services.alive(pid) or _http_ok(svc.url),
"pid": pid if services.alive(pid) else None,
"url": svc.url,
}
payload["provider"] = _provider_payload()
return payload
def cmd_status(args) -> int:
payload = service_status()
if args.json:
_emit(payload, True)
return 0
print("Nexus Service Status:\n")
for key in ("backend", "memory", "frontend"):
info = payload[key]
suffix = f" (PID {info['pid']})" if info["pid"] else ""
print(f" {key:<10} {'RUNNING' if info['running'] else 'STOPPED'}{suffix} {info['url']}")
p = payload["provider"]
print(f" provider {'RUNNING' if p['reachable'] else 'STOPPED'} {p['provider']} @ {p['url']}")
return 0
def cmd_monitor(args) -> int:
from .monitor import run_monitor
return run_monitor(
interval=getattr(args, "interval", 1.5),
once=bool(getattr(args, "once", False) or getattr(args, "json", False)),
json_output=bool(getattr(args, "json", False)),
)
def _target_flag(target: str | None):
return {
"memory": "--memory",
"backend": "--backend",
"frontend": "--frontend",
"ai": "--ai",
}.get(target or "all")
def cmd_start(args) -> int:
services.cmd_start(_target_flag(args.target))
return 0
def cmd_stop(args) -> int:
services.cmd_stop(_target_flag(args.target))
return 0
def cmd_refresh(args) -> int:
services.cmd_stop(None)
services.cmd_start(None)
return 0
def _lan_hostnames(host: str) -> list[str]:
"""Every name/address a --allow-lan bind should accept in a Host header.
A wildcard bind answers on all interfaces, so enumerate them; an explicit
address answers only as itself. The machine hostname comes along because
that is what people actually type."""
import socket
names: list[str] = []
def add(value: str) -> None:
if value and value not in names:
names.append(value)
if host in ("0.0.0.0", "::", "*"):
hostname = socket.gethostname()
add(hostname)
add(hostname.split(".")[0] + ".local")
for family in (socket.AF_INET, socket.AF_INET6):
try:
for info in socket.getaddrinfo(hostname, None, family):
add(info[4][0])
except OSError:
pass
# getaddrinfo(hostname) misses the routable address on hosts that map
# their own name to loopback; a connectionless UDP socket finds it.
for probe, family in (("8.8.8.8", socket.AF_INET), ("2001:4860:4860::8888", socket.AF_INET6)):
sock = socket.socket(family, socket.SOCK_DGRAM)
try:
sock.connect((probe, 80))
add(sock.getsockname()[0])
except OSError:
pass
finally:
sock.close()
else:
add(host.strip("[]"))
# A Host header carries an IPv6 literal bracketed; allow both spellings so
# the check matches however the client wrote it.
for value in list(names):
if ":" in value:
add(f"[{value}]")
return names
def _origin_host(name: str) -> str:
"""Origin-safe spelling: IPv6 literals must be bracketed in a URL."""
if ":" in name and not name.startswith("["):
return f"[{name}]"
return name
def cmd_serve(args) -> int:
host = args.host or settings.bind_host
if host not in ("127.0.0.1", "localhost", "::1") and not args.allow_lan:
print("Refusing an unauthenticated LAN bind. Add --allow-lan to acknowledge the exposure.", file=sys.stderr)
return 2
if _http_ok(f"http://127.0.0.1:{args.port}/"):
print(f"Port {args.port} is already serving HTTP.", file=sys.stderr)
return 2
settings.backend_port = args.port
settings.memory_port = args.memory_port
settings.bind_host = host
settings.api_url = f"http://127.0.0.1:{args.port}"
settings.memory_url = f"http://127.0.0.1:{args.memory_port}"
os.environ["NEXUS_BACKEND_PORT"] = str(args.port)
os.environ["NEXUS_MEMORY_PORT"] = str(args.memory_port)
os.environ["NEXUS_BIND_HOST"] = host
for origin_host in ("localhost", "127.0.0.1"):
for port in (args.port, args.memory_port):
origin = f"http://{origin_host}:{port}"
if origin not in config.ALLOWED_ORIGINS:
config.ALLOWED_ORIGINS.append(origin)
if args.allow_lan:
# Widen to the addresses this bind actually answers on - NOT "*".
# ALLOWED_HOSTS drives TrustedHostMiddleware, which is the DNS-rebinding
# defense: with "*" any site the user browses could resolve a name it
# controls to this machine and drive the unauthenticated API. Naming the
# real addresses keeps that check doing its job. An explicitly exported
# NEXUS_ALLOWED_HOSTS still wins, for anyone who needs the old blanket.
names = _lan_hostnames(host)
for name in names:
if name not in config.ALLOWED_HOSTS:
config.ALLOWED_HOSTS.append(name)
for port in (args.port, args.memory_port):
origin = f"http://{_origin_host(name)}:{port}"
if origin not in config.ALLOWED_ORIGINS:
config.ALLOWED_ORIGINS.append(origin)
os.environ.setdefault("NEXUS_ALLOWED_HOSTS", ",".join(config.ALLOWED_HOSTS))
os.environ.setdefault("NEXUS_ALLOWED_ORIGINS", ",".join(config.ALLOWED_ORIGINS))
print(
"LAN exposure enabled for: " + ", ".join(names)
+ "\nThe REST API is unauthenticated - anyone who can reach this port"
" has full admin and data access."
)
memory_proc = None
memory_log = None
try:
if not args.no_memory and not _http_ok(settings.memory_url + "/"):
log_path = settings.runtime_dir / "memory.log"
log_path.parent.mkdir(parents=True, exist_ok=True)
memory_log = open(log_path, "ab")
memory_proc = subprocess.Popen(
[sys.executable, "-m", "uvicorn", "synapse.memory.service:app",
"--host", host, "--port", str(args.memory_port)],
stdout=memory_log, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL,
)
print(f"Memory service starting on {host}:{args.memory_port} (log: {log_path})")
print(f"NexusOS serving on http://{host}:{args.port}")
import uvicorn
uvicorn.run(
"synapse.main:sio_app", host=host, port=args.port,
reload=bool(args.reload and settings.source_checkout),
log_level=args.log_level,
)
finally:
if memory_proc is not None and memory_proc.poll() is None:
memory_proc.terminate()
try:
memory_proc.wait(timeout=5)
except subprocess.TimeoutExpired:
memory_proc.kill()
if memory_log is not None:
memory_log.close()
return 0
def cmd_open(args) -> int:
if not _http_ok(settings.api_url + "/status") and not args.no_start:
services.cmd_start(None)
url = args.url or settings.api_url
opener = shutil.which("termux-open-url") if _is_termux() else None
opened = False
if opener:
opened = subprocess.run([opener, url], check=False).returncode == 0
else:
opened = webbrowser.open(url)
print(f"{'Opened' if opened else 'NexusOS is available at'} {url}")
return 0
def cmd_web(args) -> int:
"""Preserve ``ncp web`` for desktop checkouts; wheels use the browser UI."""
if settings.source_checkout:
return services.cmd_web()
return cmd_open(argparse.Namespace(url=None, no_start=False))
def cmd_panel(_args) -> int:
if not settings.source_checkout:
print("The legacy Tk control panel is only available in a desktop source install.", file=sys.stderr)
return 2
return services.main(["panel"])
def cmd_backup(args) -> int:
if not settings.source_checkout:
print("Backup is a source-checkout command; wheel state should be backed up from nexus paths.", file=sys.stderr)
return 2
if args.check:
return services.sync_py("backup", "--check")
if args.full:
return services.sync_py("backup", "--full")
return services.sync_py("backup")
def cmd_restore(args) -> int:
if not settings.source_checkout:
print("Restore is a source-checkout command; reinstall the wheel and restore its state directory.", file=sys.stderr)
return 2
return services.cmd_restore("--check" if args.check else None)
def cmd_nvidia_reqs(_args) -> int:
if not settings.source_checkout:
print("nvidia-reqs is only available in a desktop source install.", file=sys.stderr)
return 2
return subprocess.run(
[sys.executable, str(settings.project_root / "bin" / "gen-nvidia-reqs.py")]
).returncode
def cmd_logs(args) -> int:
keys = ("backend", "memory", "frontend") if args.target == "all" else (args.target,)
paths = [services.SERVICES[key].log_file for key in keys]
for path in paths:
print(f"=== {path.name} ===")
services._tail(path, args.lines)
if not args.follow:
return 0
offsets = {path: path.stat().st_size if path.exists() else 0 for path in paths}
try:
while True:
for path in paths:
if not path.exists():
continue
size = path.stat().st_size
if size < offsets[path]:
offsets[path] = 0
if size > offsets[path]:
with open(path, encoding="utf-8", errors="replace") as stream:
stream.seek(offsets[path])
sys.stdout.write(stream.read())
sys.stdout.flush()
offsets[path] = stream.tell()
time.sleep(0.5)
except KeyboardInterrupt:
print()
return 130
def cmd_clean(args) -> int:
for path in (settings.runtime_dir / "pids", settings.runtime_dir / "logs"):
if path.is_dir():
for file in path.glob("*"):
if file.is_file():
file.unlink(missing_ok=True)
for pattern in ("*.log", "*.pid"):
for file in settings.runtime_dir.glob(pattern):
file.unlink(missing_ok=True)
print(f"Cleaned runtime files under {settings.runtime_dir}")
return 0
def cmd_update(args) -> int:
if settings.source_checkout:
services.cmd_update()
return 0
command = [sys.executable, "-m", "pip", "install", "--upgrade", "nexusos-ai"]
if args.pre:
command.append("--pre")
return subprocess.run(command).returncode
def cmd_models(args) -> int:
import httpx
base = settings.ollama_host.rstrip("/")
try:
if args.action == "list":
response = httpx.get(base + "/api/tags", timeout=5.0)
response.raise_for_status()
models = response.json().get("models", [])
if args.json:
_emit(models, True)
elif not models:
print("No models installed.")
else:
for model in models:
print(f"{model.get('name', ''):<36} {model.get('size', 0) / 1024**3:5.1f} GB")
elif args.action == "available":
services.cmd_models("available", None)
elif args.action in ("pull", "install"):
with httpx.stream("POST", base + "/api/pull", json={"name": args.name}, timeout=None) as response:
response.raise_for_status()
for line in response.iter_lines():
if line:
try:
item = json.loads(line)
status = item.get("status") or item.get("error")
if status:
print(status)
except ValueError:
print(line)
elif args.action in ("remove", "rm"):
response = httpx.request("DELETE", base + "/api/delete", json={"name": args.name}, timeout=30.0)
response.raise_for_status()
print(f"Removed {args.name}")
return 0
except httpx.HTTPError as exc:
print(f"Provider request failed at {base}: {exc}", file=sys.stderr)
return 1
def cmd_api(args) -> int:
from . import nexus_api
nexus_api.BASE = args.api_url or settings.api_url
rest = list(args.rest)
if args.command == "chat" and rest[:1] == ["send"]:
rest.pop(0)
if args.command == "history" and rest[:1] == ["list"]:
rest.pop(0)
return nexus_api.main([args.command, *rest], prog=f"nexus {args.command}")
def _add_json(parser) -> None:
parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
def _port(value: str) -> int:
try:
return _validate_config("backend_port", value)
except (TypeError, ValueError) as exc:
raise argparse.ArgumentTypeError(str(exc)) from exc
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="nexus", description="NexusOS local AI runtime and API client")
parser.add_argument("--version", action="version", version=f"NexusOS {settings.version}")
parser.add_argument("--api-url", help="override the NexusOS backend URL for this command")
sub = parser.add_subparsers(dest="command", required=True)
p = sub.add_parser("init", help="create user state and seed default playbooks"); _add_json(p); p.set_defaults(fn=cmd_init)
p = sub.add_parser("paths", help="show resolved package and writable paths"); _add_json(p); p.set_defaults(fn=cmd_paths)
p = sub.add_parser("config", help="manage persistent CLI/runtime configuration")
p.add_argument("action", choices=["list", "get", "set", "unset", "path"])
p.add_argument("key", nargs="?"); p.add_argument("value", nargs="?"); _add_json(p); p.set_defaults(fn=cmd_config)
p = sub.add_parser("provider", help="configure the Ollama-compatible model provider")
provider_sub = p.add_subparsers(dest="action", required=True)
show = provider_sub.add_parser("show"); _add_json(show); show.set_defaults(fn=cmd_provider)
use = provider_sub.add_parser("use"); use.add_argument("mode", choices=["local", "remote"])
use.add_argument("--url"); _add_json(use); use.set_defaults(fn=cmd_provider)
p = sub.add_parser("doctor", help="check the core runtime and optional capabilities")
p.add_argument("--fix", action="store_true"); _add_json(p); p.set_defaults(fn=cmd_doctor)
p = sub.add_parser("status", help="show service and provider status"); _add_json(p); p.set_defaults(fn=cmd_status)
p = sub.add_parser("monitor", help="ASCII dashboard for services, resources, and tool stats")
p.add_argument("--once", action="store_true", help="print one frame and exit")
p.add_argument("--interval", type=float, default=1.5, help="refresh seconds (live mode)")
_add_json(p)
p.set_defaults(fn=cmd_monitor)
p = sub.add_parser("serve", help="run NexusOS in the foreground")
p.add_argument("--host"); p.add_argument("--port", type=_port, default=settings.backend_port)
p.add_argument("--memory-port", type=_port, default=settings.memory_port)
p.add_argument("--no-memory", action="store_true"); p.add_argument("--allow-lan", action="store_true")
p.add_argument("--reload", action="store_true"); p.add_argument("--log-level", default="info")
p.set_defaults(fn=cmd_serve)
for name, fn, help_text in (
("start", cmd_start, "start services in the background"),
("stop", cmd_stop, "stop background services"),
):
p = sub.add_parser(name, help=help_text)
p.add_argument("target", nargs="?", choices=["all", "backend", "memory", "frontend", "ai"], default="all")
p.set_defaults(fn=fn)
sub.add_parser("restart", aliases=["refresh"], help="restart all services").set_defaults(fn=cmd_refresh)
sub.add_parser("kill", help="force-stop NexusOS-owned processes").set_defaults(fn=lambda _a: services.cmd_kill() or 0)
p = sub.add_parser("open", help="open the web interface")
p.add_argument("--url"); p.add_argument("--no-start", action="store_true"); p.set_defaults(fn=cmd_open)
sub.add_parser("web", help="legacy desktop alias for open").set_defaults(fn=cmd_web)
sub.add_parser("panel", help="launch the legacy desktop control panel").set_defaults(fn=cmd_panel)
p = sub.add_parser("logs", help="read or follow service logs")
p.add_argument("target", nargs="?", choices=["all", "backend", "memory", "frontend"], default="all")
p.add_argument("--lines", type=int, choices=range(1, 10001), default=50, metavar="1..10000")
p.add_argument("--follow", "-f", action="store_true"); p.set_defaults(fn=cmd_logs)
sub.add_parser("clean", help="remove runtime logs and stale PID files").set_defaults(fn=cmd_clean)
p = sub.add_parser("update", help="update dependencies or the installed wheel"); p.add_argument("--pre", action="store_true"); p.set_defaults(fn=cmd_update)
p = sub.add_parser("backup", help="back up a desktop source checkout")
p.add_argument("--full", "-f", action="store_true"); p.add_argument("--check", "-c", action="store_true")
p.set_defaults(fn=cmd_backup)
p = sub.add_parser("restore", help="restore a desktop source checkout")
p.add_argument("--check", "-c", action="store_true"); p.set_defaults(fn=cmd_restore)
sub.add_parser("nvidia-reqs", help="regenerate source-checkout NVIDIA requirements").set_defaults(fn=cmd_nvidia_reqs)
p = sub.add_parser("models", help="list, pull, and remove provider models")
model_sub = p.add_subparsers(dest="action", required=True)
item = model_sub.add_parser("list"); _add_json(item); item.set_defaults(fn=cmd_models)
model_sub.add_parser("available", aliases=["search"]).set_defaults(fn=cmd_models, action="available")
item = model_sub.add_parser("pull", aliases=["install"]); item.add_argument("name"); item.set_defaults(fn=cmd_models, action="pull")
item = model_sub.add_parser("remove", aliases=["rm"]); item.add_argument("name"); item.set_defaults(fn=cmd_models, action="remove")
for command in ("chat", "memory", "playbook", "history"):
p = sub.add_parser(command, add_help=False, help=f"use the {command} API from the terminal")
p.add_argument("rest", nargs=argparse.REMAINDER)
p.set_defaults(fn=cmd_api)
return parser
def _normalize_legacy_argv(argv) -> list[str]:
"""Translate the old shell CLI spelling before argparse sees it."""
normalized = list(argv or [])
if normalized == ["help"]:
return ["--help"]
# start/stop only. `logs` registers -f as the short form of --follow, so
# translating it here would silently rewrite `logs -f` to `logs frontend`
# - a tail of the wrong file instead of a follow, with no error.
if normalized and normalized[0] in ("start", "stop"):
normalized[1:] = [LEGACY_TARGETS.get(value, value) for value in normalized[1:]]
elif normalized[:1] == ["logs"]:
normalized[1:] = [
value if value in ("-f", "--follow") else LEGACY_TARGETS.get(value, value)
for value in normalized[1:]
]
if normalized[:2] == ["backup", "full"]:
normalized[1] = "--full"
elif len(normalized) > 1 and normalized[0] == "backup" and normalized[1] in ("check", "--claude"):
normalized[1] = "--check"
elif len(normalized) > 1 and normalized[0] == "restore":
if normalized[1] in ("check", "--claude"):
normalized[1] = "--check"
elif normalized[1] in ("full", "-f", "--full"):
normalized.pop(1)
return normalized
def main(argv=None) -> int:
parser = build_parser()
args = parser.parse_args(_normalize_legacy_argv(argv))
if args.command == "config":
if args.action in ("get", "unset") and not args.key:
parser.error(f"config {args.action} requires KEY")
if args.action == "set" and (not args.key or args.value is None):
parser.error("config set requires KEY VALUE")
try:
result = args.fn(args)
return result if isinstance(result, int) else 0
except KeyboardInterrupt:
print()
return 130
def entrypoint() -> int:
return main(sys.argv[1:])
if __name__ == "__main__":
raise SystemExit(entrypoint())
nexusos_cli/monitor.py
+458
View File
@@ -0,0 +1,458 @@
"""ASCII dashboard for live NexusOS service / tool / resource stats.
No curses, no rich — pure box-drawing + optional ANSI color so it works in
Termux, plain SSH, and Windows Terminal alike. The collector is separate from
the renderer so tests can feed fixtures without a running stack.
"""
from __future__ import annotations
import json
import shutil
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from synapse.nexus_config import settings
from . import ncp as services
# Box drawing — ASCII fallbacks when the terminal can't do Unicode.
_BOX = {
"tl": "┌", "tr": "┐", "bl": "└", "br": "┘",
"h": "─", "v": "│", "l": "├", "r": "┤",
}
_BOX_ASCII = {
"tl": "+", "tr": "+", "bl": "+", "br": "+",
"h": "-", "v": "|", "l": "+", "r": "+",
}
_FILL = "█"
_EMPTY = "░"
_FILL_ASCII = "#"
_EMPTY_ASCII = "-"
def _use_unicode() -> bool:
enc = (getattr(__import__("sys").stdout, "encoding", None) or "").lower()
return "utf" in enc or enc in ("cp65001",)
def _http_ok(url: str, timeout: float = 1.0) -> bool:
try:
urllib.request.urlopen(url, timeout=timeout).read(1)
return True
except urllib.error.HTTPError:
return True
except Exception:
return False
def _provider_payload() -> dict:
url = settings.ollama_host.rstrip("/")
return {
"provider": settings.provider,
"url": url,
"managed_by_nexus": settings.manage_ollama,
"reachable": _http_ok(url + "/api/tags", timeout=2.0),
}
def _service_status() -> dict:
payload = {}
for key in ("backend", "memory", "frontend"):
svc = services.SERVICES[key]
pid = services.read_pid(svc)
payload[key] = {
"running": services.alive(pid) or _http_ok(svc.url),
"pid": pid if services.alive(pid) else None,
"url": svc.url,
}
payload["provider"] = _provider_payload()
return payload
def _get_json(url: str, timeout: float = 1.5) -> Any | None:
try:
with urllib.request.urlopen(url, timeout=timeout) as resp:
return json.loads(resp.read().decode("utf-8", errors="replace"))
except Exception:
return None
def _bar(ratio: float, width: int = 20, unicode: bool = True) -> str:
ratio = max(0.0, min(1.0, float(ratio)))
filled = int(round(ratio * width))
fill = _FILL if unicode else _FILL_ASCII
empty = _EMPTY if unicode else _EMPTY_ASCII
return fill * filled + empty * (width - filled)
def _fmt_bytes(n: float | int | None) -> str:
if n is None:
return "—"
n = float(n)
for unit in ("B", "K", "M", "G", "T"):
if abs(n) < 1024 or unit == "T":
return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
n /= 1024
return f"{n:.1f}T"
def _pid_stats(pids: list[int | None]) -> dict:
"""Aggregate CPU%/RSS for known service PIDs. Soft-depends on psutil."""
live = [int(p) for p in pids if p]
if not live:
return {"cpu_pct": None, "rss": None, "pids": []}
try:
import psutil # type: ignore
except ImportError:
return {"cpu_pct": None, "rss": None, "pids": live}
cpu = 0.0
rss = 0
seen: list[int] = []
for pid in live:
try:
proc = psutil.Process(pid)
cpu += proc.cpu_percent(interval=0.0)
rss += proc.memory_info().rss
seen.append(pid)
except (psutil.Error, ProcessLookupError, ValueError):
continue
return {"cpu_pct": cpu, "rss": rss, "pids": seen}
def _host_stats() -> dict:
try:
import psutil # type: ignore
except ImportError:
return {"cpu_pct": None, "mem_used": None, "mem_total": None, "mem_pct": None}
vm = psutil.virtual_memory()
return {
"cpu_pct": psutil.cpu_percent(interval=0.05),
"mem_used": vm.used,
"mem_total": vm.total,
"mem_pct": vm.percent,
}
def _api_counts(api_url: str) -> dict:
"""Pull cheap inventory counts from the backend when it is up."""
base = api_url.rstrip("/")
out = {
"online": False,
"version": None,
"ollama": None,
"memories": None,
"conversations": None,
"playbooks": None,
"models": None,
"action_tool_policy": None,
}
status = _get_json(base + "/status")
if not isinstance(status, dict):
return out
out["online"] = True
out["version"] = status.get("version")
out["ollama"] = status.get("ollama")
mem = _get_json(base + "/memory")
if isinstance(mem, list):
out["memories"] = len(mem)
elif isinstance(mem, dict) and isinstance(mem.get("memories"), list):
out["memories"] = len(mem["memories"])
conv = _get_json(base + "/conversations")
if isinstance(conv, list):
out["conversations"] = len(conv)
elif isinstance(conv, dict):
items = conv.get("conversations") or conv.get("items") or []
if isinstance(items, list):
out["conversations"] = len(items)
pbs = _get_json(base + "/playbooks")
if isinstance(pbs, list):
out["playbooks"] = len(pbs)
elif isinstance(pbs, dict) and isinstance(pbs.get("playbooks"), list):
out["playbooks"] = len(pbs["playbooks"])
models = _get_json(base + "/models")
if isinstance(models, list):
out["models"] = len(models)
elif isinstance(models, dict):
items = models.get("models") or models.get("items") or []
if isinstance(items, list):
out["models"] = len(items)
settings_payload = _get_json(base + "/settings")
if isinstance(settings_payload, dict):
out["action_tool_policy"] = settings_payload.get("action_tool_policy")
return out
def _toolchain_stats() -> list[dict]:
"""Which run_snippet languages have a host toolchain right now."""
try:
from synapse import code_run
except Exception:
return []
rows = []
for name, spec in code_run.RUN_LANGS.items():
tool = None
try:
tool = spec["tool"]()
except Exception:
tool = None
rows.append({
"lang": name,
"ready": bool(tool),
"tool": tool or None,
"summary": spec.get("summary") or name,
})
return rows
def _recent_tools(log_path: Path, limit: int = 8) -> list[str]:
"""Best-effort scrape of recent tool names from chat.log."""
if not log_path.is_file():
return []
try:
# Read the tail without pulling a multi-MB log into memory.
data = log_path.read_bytes()
if len(data) > 64_000:
data = data[-64_000:]
text = data.decode("utf-8", errors="replace")
except OSError:
return []
found: list[str] = []
for line in reversed(text.splitlines()):
# Chat tool loop yields "__status__<tool>"; logs may also name tools
# in JSON payloads. Keep the match narrow.
if "__status__" in line:
name = line.split("__status__", 1)[-1].strip().split()[0].strip(",\"'")
if name and name not in ("tools",) and name not in found:
found.append(name)
elif '"name":' in line and any(
t in line for t in ("render_preview", "run_snippet", "web_search",
"fetch_url", "remember", "get_time")
):
for t in ("run_snippet", "render_preview", "web_search", "fetch_url",
"remember", "get_time", "search_documents"):
if t in line and t not in found:
found.append(t)
if len(found) >= limit:
break
return found
def collect_snapshot() -> dict:
"""Gather one monitoring frame. Safe when services are down."""
services_payload = _service_status()
pids = [
services_payload.get("backend", {}).get("pid"),
services_payload.get("memory", {}).get("pid"),
services_payload.get("frontend", {}).get("pid"),
]
api = _api_counts(settings.api_url)
return {
"ts": datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds"),
"version": settings.version,
"services": services_payload,
"api": api,
"host": _host_stats(),
"procs": _pid_stats(pids),
"toolchains": _toolchain_stats(),
"recent_tools": _recent_tools(settings.logs_dir / "chat.log"),
"paths": {
"api_url": settings.api_url,
"memory_url": settings.memory_url,
"runtime_dir": str(settings.runtime_dir),
},
}
def _pad(text: str, width: int) -> str:
# Visual width ≈ len for our ASCII/box content (no wide East-Asian chars).
if len(text) > width:
return text[: width - 1] + "…" if width > 1 else text[:width]
return text + " " * (width - len(text))
def _row(box: dict, inner: str, width: int) -> str:
return f"{box['v']} {_pad(inner, width - 4)} {box['v']}"
def _rule(box: dict, width: int, kind: str = "mid") -> str:
h = box["h"] * (width - 2)
if kind == "top":
return f"{box['tl']}{h}{box['tr']}"
if kind == "bot":
return f"{box['bl']}{h}{box['br']}"
return f"{box['l']}{h}{box['r']}"
def _svc_line(name: str, running: bool, detail: str, unicode: bool) -> str:
mark = (_FILL if unicode else _FILL_ASCII) * 3 if running else (_EMPTY if unicode else _EMPTY_ASCII) * 3
state = "UP " if running else "DOWN"
return f"{name:<10} {mark} {state} {detail}"
def render_frame(snapshot: dict, *, width: int | None = None, unicode: bool | None = None) -> str:
"""Turn a snapshot into a single multi-line ASCII panel."""
if unicode is None:
unicode = _use_unicode()
box = _BOX if unicode else _BOX_ASCII
cols = shutil.get_terminal_size((80, 24)).columns if width is None else width
width = max(56, min(100, cols))
lines: list[str] = []
lines.append(_rule(box, width, "top"))
title = f"NexusOS {snapshot.get('version', '')} monitor"
raw_ts = snapshot.get("ts") or ""
# Prefer local clock HH:MM:SS from an ISO stamp; fall back to wall clock.
stamp = ""
if "T" in raw_ts:
try:
stamp = raw_ts.split("T", 1)[1][:8]
except Exception:
stamp = ""
if not stamp:
stamp = datetime.now().strftime("%H:%M:%S")
gap = max(1, width - 4 - len(title) - len(stamp))
header = f"{title}{' ' * gap}{stamp}"
lines.append(_row(box, header, width))
lines.append(_rule(box, width, "mid"))
lines.append(_row(box, "SERVICES", width))
svcs = snapshot.get("services") or {}
for key, label in (("backend", "backend"), ("memory", "memory"), ("frontend", "frontend")):
info = svcs.get(key) or {}
running = bool(info.get("running"))
pid = info.get("pid")
url = info.get("url") or ""
detail = url
if pid:
detail = f"pid {pid} {url}"
lines.append(_row(box, _svc_line(label, running, detail, unicode), width))
provider = svcs.get("provider") or _provider_payload()
pref = f"{provider.get('provider', '?')} @ {provider.get('url', '')}"
lines.append(_row(box, _svc_line("provider", bool(provider.get("reachable")), pref, unicode), width))
lines.append(_rule(box, width, "mid"))
lines.append(_row(box, "RESOURCES", width))
host = snapshot.get("host") or {}
procs = snapshot.get("procs") or {}
cpu = host.get("cpu_pct")
if cpu is not None:
lines.append(_row(
box,
f"host CPU [{_bar(cpu / 100.0, 22, unicode)}] {cpu:5.1f}%",
width,
))
else:
lines.append(_row(box, "host CPU (install psutil for live bars)", width))
mem_pct = host.get("mem_pct")
if mem_pct is not None:
lines.append(_row(
box,
f"host MEM [{_bar(mem_pct / 100.0, 22, unicode)}] "
f"{_fmt_bytes(host.get('mem_used'))} / {_fmt_bytes(host.get('mem_total'))}",
width,
))
proc_cpu = procs.get("cpu_pct")
proc_rss = procs.get("rss")
if proc_cpu is not None or proc_rss is not None:
lines.append(_row(
box,
f"nexus cpu={proc_cpu if proc_cpu is not None else '—':>5} "
f"rss={_fmt_bytes(proc_rss)} pids={','.join(str(p) for p in (procs.get('pids') or [])) or '—'}",
width,
))
lines.append(_rule(box, width, "mid"))
lines.append(_row(box, "DATA / TOOLS", width))
api = snapshot.get("api") or {}
if api.get("online"):
policy = api.get("action_tool_policy") or "—"
lines.append(_row(
box,
f"api UP v{api.get('version') or '?'} ollama={api.get('ollama') or '—'} "
f"tools={policy}",
width,
))
lines.append(_row(
box,
f"memories={_n(api.get('memories'))} "
f"chats={_n(api.get('conversations'))} "
f"playbooks={_n(api.get('playbooks'))} "
f"models={_n(api.get('models'))}",
width,
))
else:
lines.append(_row(box, "api DOWN — start with: nexus start", width))
recent = snapshot.get("recent_tools") or []
lines.append(_row(
box,
"recent " + (", ".join(recent) if recent else "(none in chat.log)"),
width,
))
lines.append(_rule(box, width, "mid"))
lines.append(_row(box, "RUN TOOLCHAINS (run_snippet)", width))
chains = snapshot.get("toolchains") or []
if not chains:
lines.append(_row(box, "(code_run unavailable)", width))
else:
# Pack ready/missing into one or two compact lines.
ready = [c["lang"] for c in chains if c.get("ready")]
missing = [c["lang"] for c in chains if not c.get("ready")]
lines.append(_row(
box,
f"ready {', '.join(ready) if ready else '—'}",
width,
))
lines.append(_row(
box,
f"missing {', '.join(missing) if missing else '—'}",
width,
))
lines.append(_rule(box, width, "bot"))
return "\n".join(lines)
def _n(value) -> str:
return "—" if value is None else str(value)
def run_monitor(*, interval: float = 1.5, once: bool = False, json_output: bool = False) -> int:
"""Print one frame, or refresh in place until interrupted."""
clear = "\033[H\033[J"
first = True
while True:
snap = collect_snapshot()
if json_output:
print(json.dumps(snap, indent=2, sort_keys=True))
else:
frame = render_frame(snap)
if once or not first:
# Replacing the screen keeps the panel stable; first frame of a
# live session also clears so leftover shell output doesn't mix.
if not once:
print(clear + frame, end="", flush=True)
else:
print(frame)
else:
print(clear + frame, end="", flush=True)
first = False
if once:
return 0
try:
time.sleep(max(0.3, float(interval)))
except KeyboardInterrupt:
print()
return 130
nexusos_cli/ncp.py
+935
View File
@@ -0,0 +1,935 @@
#!/usr/bin/env python3
"""ncp - the NexusOS management CLI, one implementation for Linux and Windows.
This replaces the logic that lived in management/nexus-cli.sh. That script was
bash + pkill + fuser + /proc, so the Windows box had no `ncp` at all - the same
split that made bin/install.sh rot until it was rsyncing from a path retired
months earlier. Same fix as bin/sync.py: the portable half is Python, and the
per-platform pieces are small and explicit.
nexus-cli.sh is now a two-line wrapper, so `ncp`, launch_nexus.sh,
bin/restore-linux.sh, controlpanel.py, nexus-popup.py and nexus-app.sh all keep
calling what they always called.
psutil does the process work (cmdlines, pattern sweeps, port owners). It is
declared in requirements-base.txt AND requirements-windows.txt, so both boxes have
it - but it is imported lazily so `ncp backup`/`restore` still run before the
venv exists, exactly as they did when they shelled out to sync.py.
"""
from __future__ import annotations
import json
import os
import shutil
import subprocess
import sys
import time
import urllib.request
from dataclasses import dataclass, field
from pathlib import Path
from synapse import proc_util
from synapse.nexus_config import SOURCE_CHECKOUT, settings
ROOT = settings.project_root
PID_DIR = settings.runtime_dir / "pids"
LOG_DIR = settings.runtime_dir
FRONTEND_DIR = settings.frontend_source_dir
OLLAMA_BIN = ROOT / "ollama" / "bin" / ("ollama.exe" if os.name == "nt" else "ollama")
OLLAMA_MODELS_DIR = settings.models_dir
WINDOWS = os.name == "nt"
_VENV_PYTHON = ROOT / "Promethean" / ("Scripts/python.exe" if WINDOWS else "bin/python3")
PYTHON = Path(os.getenv("NEXUS_PYTHON", "")) if os.getenv("NEXUS_PYTHON") else (
_VENV_PYTHON if _VENV_PYTHON.exists() else Path(sys.executable)
)
PID_DIR.mkdir(parents=True, exist_ok=True)
LOG_DIR.mkdir(parents=True, exist_ok=True)
# The output carries em-dashes and check marks (matching what nexus-cli.sh
# printed). On Windows a redirected stdout defaults to cp1252, which raises
# UnicodeEncodeError on both - so pin UTF-8 rather than degrade the output.
for _stream in (sys.stdout, sys.stderr):
try:
_stream.reconfigure(encoding="utf-8", errors="replace")
except (AttributeError, ValueError):
pass
# -- small helpers -------------------------------------------------------------
def http_ok(url: str, timeout: float = 1.0) -> bool:
"""True if the URL answers at all. Any HTTP status counts - a 404 still
proves something is listening, which is all the port checks care about."""
try:
urllib.request.urlopen(url, timeout=timeout).read(1)
return True
except urllib.error.HTTPError:
return True
except Exception:
return False
def ollama_bin() -> str | None:
"""The bundled binary if we have one, else whatever is on PATH.
Only Linux ships a copy in the repo (bin/fetch-ollama.sh); on Windows the
installer gets Ollama from winget, which puts it in %LOCALAPPDATA%\\Programs
and on PATH. Checking only the bundled path made `ncp doctor` report a red
"Ollama binary missing" on every Windows box, and made `ncp models install`
refuse to run there at all. Mirrors _ollama_bin() in ollama_manager.py."""
if OLLAMA_BIN.exists():
return str(OLLAMA_BIN)
return shutil.which("ollama")
def npm() -> str | None:
"""npm, resolving through nvm. The bash version sourced ~/.nvm/nvm.sh; a
non-login shell has neither, so fall back to globbing the nvm install."""
found = shutil.which("npm") # resolves npm.cmd on Windows
if found:
return found
versions = sorted((Path.home() / ".nvm" / "versions" / "node").glob("*/bin/npm"))
return str(versions[-1]) if versions else None
def _psutil():
try:
import psutil
return psutil
except ImportError:
return None
# -- services ------------------------------------------------------------------
@dataclass
class Service:
key: str
label: str
port: int
cwd: Path
patterns: list
_argv: object = None
pid_file: Path = field(init=False)
log_file: Path = field(init=False)
def __post_init__(self):
self.pid_file = PID_DIR / f"{self.key}.pid"
self.log_file = LOG_DIR / f"{self.key}.log"
@property
def url(self) -> str:
return f"http://localhost:{self.port}/"
def argv(self):
return self._argv() if callable(self._argv) else self._argv
# Bind loopback by default: the backend REST API is unauthenticated, so
# binding 0.0.0.0 handed the full admin+data plane to any host on the LAN. Set
# NEXUS_BIND_HOST=0.0.0.0 to opt into LAN exposure once real auth is in place.
BIND_HOST = settings.bind_host
def _uvicorn(app: str, port: int):
# No --reload. It is a dev-loop flag: uvicorn's reloader runs a supervisor
# that spawns the real server as a CHILD, so every service became two
# processes - and on Windows that child, spawned from a parent with no
# console, got handed a brand new console WINDOW. `ncp web` popped two black
# terminals for what should have been a silent start. launch_nexus.sh still
# passes --reload for the Linux dev loop, where a visible console is the
# point; this launcher is the one users run.
return [str(PYTHON), "-m", "uvicorn", app, "--host", BIND_HOST,
"--port", str(port)]
SERVICES = {
"memory": Service("memory", "NEXUS MEMORY SERVICE", settings.memory_port, settings.state_dir,
["uvicorn synapse.memory"],
lambda: _uvicorn("synapse.memory.service:app", settings.memory_port)),
"backend": Service("backend", "NEXUS BACKEND SERVICE", settings.backend_port, settings.state_dir,
["uvicorn synapse.main"],
lambda: _uvicorn("synapse.main:sio_app", settings.backend_port)),
"frontend": Service("frontend", "NEXUS FRONTEND SERVICE", 5173, FRONTEND_DIR,
["vite --host", "npm run dev"],
lambda: [npm(), "run", "dev", "--", "--host", "0.0.0.0"]),
}
def read_pid(svc: Service):
try:
return int(svc.pid_file.read_text().strip())
except (OSError, ValueError):
return None
def alive(pid) -> bool:
ps = _psutil()
if pid is None:
return False
if ps is not None:
return ps.pid_exists(pid)
# Not os.kill(pid, 0): that reports False for a live process owned by
# another user, and Windows has no signals to fall back on.
return proc_util.pid_alive(pid)
def pid_is_ours(pid, patterns) -> bool:
"""True only if the live PID's command line matches one of the service
patterns. PID files outlive reboots and the OS recycles the number onto an
unrelated process - often a desktop-session one - so a bare liveness check
is not enough. TERMing a recycled PID can log the user out."""
ps = _psutil()
try:
if ps is not None:
cmd = " ".join(ps.Process(pid).cmdline())
else:
cmd = proc_util.pid_cmdline(pid)
except Exception:
return False
return any(p in cmd for p in patterns)
def launch(svc: Service) -> None:
pid = read_pid(svc)
if alive(pid) and pid_is_ours(pid, svc.patterns):
return
argv = svc.argv()
if argv[0] is None:
print(f" {svc.label}: npm not found - install Node, or run ./install.sh")
return
svc.log_file.write_text("")
with open(svc.log_file, "ab") as log:
# Detach so the service outlives this process, on both platforms.
# CREATE_NO_WINDOW, not DETACHED_PROCESS: detached means the process has
# NO console, and Windows then gives a console window to any console
# program it starts in turn. CREATE_NO_WINDOW gives it a console that is
# never shown, which its children inherit - so nothing flashes up.
kwargs = ({"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP
| getattr(subprocess, "CREATE_NO_WINDOW", 0)}
if WINDOWS else {"start_new_session": True})
proc = subprocess.Popen(argv, cwd=str(svc.cwd), stdout=log,
stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL,
**kwargs)
svc.pid_file.write_text(str(proc.pid))
def check(svc: Service) -> bool:
pid = read_pid(svc)
if alive(pid):
print(f"{svc.label} STARTED")
return True
print(f"{svc.label} FAILED TO START")
try:
tail = svc.log_file.read_text(errors="replace").splitlines()[-8:]
for line in tail:
print(f" {line}")
except OSError:
pass
svc.pid_file.unlink(missing_ok=True)
return False
# Poll granularity for both waiters below. 1s steps used to mean every
# start/stop paid up to a full second of dead latency per service on top of
# however long the process actually took - three services in sequence could
# lose several seconds to nothing but sleep(). 0.25s still amounts to one
# cheap local HTTP HEAD every quarter second, not a busy-loop.
_POLL_STEP = 0.25
def wait_for_port(svc: Service, timeout: int = 30) -> bool:
if http_ok(svc.url):
# "READY", not "already running": `ncp start` launches its services and
# only then waits on each, so by the time a service's turn comes it is
# normally up - and reporting "already running" for a service this same
# command started two seconds ago reads like a stale process.
print(f" {svc.label} READY (:{svc.port})")
return True
for _ in range(int(timeout / _POLL_STEP)):
time.sleep(_POLL_STEP)
if http_ok(svc.url):
print(f"{svc.label} STARTED")
return True
print(f" {svc.label} timed out after {timeout}s")
return check(svc)
def wait_for_port_close(port: int, timeout: int = 15) -> bool:
for _ in range(int(timeout / _POLL_STEP)):
if not http_ok(f"http://localhost:{port}/"):
return True
time.sleep(_POLL_STEP)
return False
def kill_matching(patterns, force=False) -> int:
"""The pkill -f sweep: catches reparented grandchildren (npm -> sh -> node
vite), uvicorn --reload workers, and instances started outside this CLI.
Returns how many processes it signalled, so callers can stay quiet when
there was nothing to kill."""
ps = _psutil()
me = os.getpid()
hit = 0
if ps is None:
for pid, cmd in proc_util.iter_processes():
if pid == me or not any(pattern in cmd for pattern in patterns):
continue
if proc_util.terminate_pid(pid, force=force):
hit += 1
return hit
for proc in ps.process_iter(["pid", "cmdline"]):
if proc.info["pid"] == me:
continue
cmd = " ".join(proc.info["cmdline"] or [])
if any(p in cmd for p in patterns):
try:
proc.kill() if force else proc.terminate()
hit += 1
except Exception:
pass
return hit
def kill_port(port: int) -> bool:
"""Whatever holds the port IS the service - this is the backstop that makes
stop reliable regardless of process-tree shape or PID-file accuracy."""
ps = _psutil()
if ps is None:
killed = False
for pid in proc_util.pids_listening_on(port):
if pid != os.getpid() and proc_util.terminate_pid(pid, force=True):
killed = True
return killed
killed = False
try:
conns = ps.net_connections(kind="inet")
except Exception:
return False
for conn in conns:
if conn.laddr and conn.laddr.port == port and conn.status == "LISTEN" and conn.pid:
try:
ps.Process(conn.pid).kill()
killed = True
except Exception:
pass
return killed
def stop_service(svc: Service) -> bool:
"""Three escalating passes, with the PORT as the source of truth for
whether the service is actually down."""
pid = read_pid(svc)
if pid is not None:
if alive(pid) and pid_is_ours(pid, svc.patterns):
ps = _psutil()
try:
if ps is not None:
proc = ps.Process(pid)
for child in proc.children(recursive=True):
try:
child.terminate()
except Exception:
pass
proc.terminate()
else:
# No psutil means no process tree; the kill_matching sweep
# below is what catches reparented children here.
proc_util.terminate_pid(pid)
except Exception:
pass
svc.pid_file.unlink(missing_ok=True)
kill_matching(svc.patterns)
if not wait_for_port_close(svc.port):
kill_port(svc.port)
kill_matching(svc.patterns, force=True)
wait_for_port_close(svc.port)
if http_ok(svc.url):
print(f"{svc.label} STILL RUNNING (:{svc.port}) — try 'ncp kill'")
return False
print(f"{svc.label} STOPPED")
return True
# -- ollama --------------------------------------------------------------------
def start_ollama(background: bool = False) -> None:
"""Driven through the backend endpoint (the path the control panel uses)
rather than launching the binary, because OllamaManager owns model and GPU
selection. Requires the backend to be up.
background=True (`ncp start`): the endpoint returns as soon as `ollama serve`
is up and warms the model in a background task, so boot finishes in seconds
and the model loads concurrently into the first chat.
background=False (`ncp start --ai`): blocks until the model is warmed - weights
read off disk into RAM/VRAM, routinely about a minute - so "started" means the
AI can actually answer."""
if not settings.manage_ollama:
running = http_ok(settings.ollama_host.rstrip("/") + "/api/tags", timeout=3)
print(
f"REMOTE OLLAMA {'REACHABLE' if running else 'UNREACHABLE'} "
f"({settings.ollama_host})"
)
return
print("Starting OLLAMA...")
url = settings.api_url + "/ollama/start" + ("?background=true" if background else "")
req = urllib.request.Request(url, method="POST")
try:
urllib.request.urlopen(req, timeout=180).read(1)
print("NEXUS OLLAMA WARMING (background)" if background else "NEXUS OLLAMA STARTED")
except Exception as e:
print(f" OLLAMA start failed: {e}")
def stop_ollama() -> None:
"""Prefer the backend endpoint for a clean OllamaManager shutdown; if the
backend is already down, kill `ollama serve` directly so it never lingers
holding VRAM/RAM. Must run BEFORE the backend is torn down."""
if not settings.manage_ollama:
print(f"REMOTE OLLAMA IS EXTERNALLY MANAGED ({settings.ollama_host})")
return
req = urllib.request.Request(settings.api_url + "/ollama/stop", method="POST")
try:
urllib.request.urlopen(req, timeout=5).read(1)
print("NEXUS OLLAMA STOPPED")
return
except Exception:
pass
# Silent when there was nothing to stop - the bash version only announced a
# direct kill if `pgrep ollama serve` actually matched, and claiming to have
# stopped a service that was never running is worse than saying nothing.
if kill_matching(["ollama serve"]):
print("NEXUS OLLAMA STOPPED (direct)")
# -- commands ------------------------------------------------------------------
def cmd_start(target) -> None:
if target in ("--backend", "-b"):
launch(SERVICES["backend"]); wait_for_port(SERVICES["backend"])
start_ollama()
elif target in ("--frontend", "-f"):
if not SOURCE_CHECKOUT:
print("Vite source is unavailable in wheel installs; the backend serves the bundled UI.")
return
launch(SERVICES["frontend"]); wait_for_port(SERVICES["frontend"])
elif target in ("--ai", "-a"):
start_ollama()
elif target in (None, "", "all"):
# Bring the UI up first, then kick off Ollama and (on Linux) Vite in the
# background without waiting on either — neither gates the app being
# usable. The backend already serves the built interface/web/dist at
# :8000 on both platforms (single-process design), and that's the URL
# nexus-app.sh/ncp web actually opens; nothing points a user at :5173.
# Vite only exists for whoever is hot-reload-editing the frontend, and
# they'll open :5173 themselves once it's ready - polling for it here
# just delayed "boot done" for a benefit nobody in the critical path
# gets. Skipped outright on Windows, where it's not part of the normal
# workflow at all and is the slow part of `ncp stop` to boot (npm's
# cmd.exe -> node -> esbuild tree doesn't die from a plain terminate()
# and falls through to the ~30s force-kill path). Still available on
# demand via `ncp start --frontend`.
t0 = time.perf_counter()
launch(SERVICES["backend"])
wait_for_port(SERVICES["backend"])
t_services = time.perf_counter()
start_ollama(background=True)
if SOURCE_CHECKOUT and not WINDOWS:
launch(SERVICES["frontend"])
t_bg = time.perf_counter()
print("\nBoot timing:")
print(f" backend : {t_services - t0:5.1f}s")
print(f" ollama + frontend (bg kickoff) : {t_bg - t_services:5.1f}s")
print(f" total to interactive : {t_bg - t0:5.1f}s")
else:
show_help()
def cmd_stop(target) -> None:
if target in ("--backend", "-b"):
stop_ollama(); stop_service(SERVICES["backend"])
elif target in ("--frontend", "-f"):
stop_service(SERVICES["frontend"])
elif target in ("--ai", "-a"):
stop_ollama()
elif target in (None, "", "all"):
stop_ollama()
stop_service(SERVICES["backend"])
stop_service(SERVICES["frontend"])
else:
show_help()
def cmd_kill() -> None:
print("Force-killing all Nexus processes...")
targets = [
(settings.backend_port, "SYNAPSE"),
(settings.memory_port, "MEMORY"),
(5173, "INTERFACE"),
]
patterns = ["uvicorn synapse", "npm run dev", "vite --host"]
if settings.manage_ollama:
targets.append((11434, "OLLAMA"))
patterns.append("ollama serve")
for port, name in targets:
if kill_port(port):
print(f" KILLED: {name} (:{port})")
else:
print(f" NOT RUNNING: {name} (:{port})")
kill_matching(patterns, force=True)
for pid_file in PID_DIR.glob("*.pid"):
pid_file.unlink(missing_ok=True)
print("Done.")
def cmd_status() -> None:
print("Nexus Service Status:\n")
def one(name, svc):
pid = read_pid(svc)
if alive(pid):
print(f" {name}: RUNNING (PID {pid})")
elif http_ok(svc.url):
print(f" {name}: RUNNING (port :{svc.port}, PID stale — consider ncp kill)")
else:
print(f" {name}: STOPPED")
print("Backend:")
one("Synapse ", SERVICES["backend"])
print("\nFrontend:")
one("Vite ", SERVICES["frontend"])
print("\nModel server:")
running = http_ok(settings.ollama_host.rstrip("/") + "/api/tags")
mode = "remote" if not settings.manage_ollama else "local"
print(f" Ollama ({mode}) : {'RUNNING' if running else 'STOPPED'} ({settings.ollama_host})")
def _tail(path: Path, n: int) -> None:
try:
for line in path.read_text(errors="replace").splitlines()[-n:]:
print(line)
except OSError:
print(f" (no log at {path})")
LOG_HEADINGS = {"backend": "BACKEND", "frontend": "FRONTEND"}
def cmd_logs(target) -> None:
named = {"--frontend": "frontend", "-f": "frontend",
"--backend": "backend", "-b": "backend"}
if target in named:
key = named[target]
print(f"=== {LOG_HEADINGS[key]} LOGS ===")
_tail(SERVICES[key].log_file, 50)
elif target in (None, "", "all"):
for i, key in enumerate(("backend", "frontend")):
if i:
print()
print(f"=== {LOG_HEADINGS[key]} LOGS ===")
_tail(SERVICES[key].log_file, 30)
else:
print(f"Unknown logs target: '{target}'")
print("Usage: ncp logs [frontend|backend|all]")
def _apply_fixes() -> None:
"""Opt-in safe repairs (ncp doctor --fix). Only idempotent, non-destructive
actions: build the UI, install deps, fetch the Ollama binary. Anything that
could lose data or needs a decision is left to the user with a hint."""
print("\nApplying safe fixes...\n")
did = False
web, npm_path = FRONTEND_DIR, npm()
if not PYTHON.exists():
print(" ✘ Promethean venv missing — run ./install.sh to build it (skipped: heavy).")
else:
importable = subprocess.run(
[str(PYTHON), "-c", "from synapse.main import sio_app"],
cwd=str(ROOT), capture_output=True).returncode == 0
if not importable:
print(" Backend import failed — reinstalling Python dependencies...")
sys.path.insert(0, str(ROOT / "bin"))
import importlib.util
spec = importlib.util.spec_from_file_location("sync", ROOT / "bin" / "sync.py")
sync = importlib.util.module_from_spec(spec)
spec.loader.exec_module(sync)
subprocess.run([str(PYTHON), "-m", "pip", "install", "-r", sync.requirements()], cwd=str(ROOT))
did = True
if npm_path and web.is_dir() and not (web / "node_modules").is_dir():
print(" node_modules missing — running npm install...")
subprocess.run([npm_path, "install"], cwd=str(web))
did = True
if npm_path and web.is_dir() and not (web / "dist" / "index.html").exists():
print(" Built UI missing — running npm run build...")
subprocess.run([npm_path, "run", "build"], cwd=str(web))
did = True
if not ollama_bin() and os.name != "nt" and (ROOT / "bin" / "fetch-ollama.sh").exists():
print(" Ollama binary missing — fetching...")
subprocess.run(["bash", str(ROOT / "bin" / "fetch-ollama.sh")])
did = True
print("\n" + ("Fixes applied — re-run 'ncp doctor' to confirm." if did
else "Nothing to fix (all safe-repairable checks already pass)."))
def cmd_doctor(fix: bool = False) -> None:
def mark(ok, good, bad):
print(f" {'✔' if ok else '✘'} {good if ok else bad}")
print("Running Nexus Diagnostics...\n")
print("Checking directories...")
mark(ROOT.is_dir(), "Nexus root found", "Missing Nexus root")
mark(FRONTEND_DIR.is_dir(), "Frontend directory found", "Missing frontend directory")
print("\nChecking Python venv...")
if PYTHON.exists():
ver = subprocess.run([str(PYTHON), "--version"], capture_output=True,
text=True).stdout.strip()
mark(True, f"Promethean venv found ({ver})", "")
else:
mark(False, "", f"Promethean venv missing at {PYTHON}")
print("\nChecking Node & npm...")
def version(exe):
if not exe:
return ""
try:
return subprocess.run([exe, "-v"], capture_output=True, text=True).stdout.strip()
except OSError:
return ""
def node_ok(ver: str) -> bool:
# Vite needs Node 20.19+ (or 22.12+); Debian's apt 'nodejs' is EOL 18.
try:
parts = ver.lstrip("v").split(".")
major, minor = int(parts[0]), int(parts[1])
except (ValueError, IndexError):
return False
return major >= 21 or (major == 20 and minor >= 19)
node, npm_path = shutil.which("node"), npm()
node_ver = version(node)
mark(bool(node), f"Node installed ({node_ver})", "Node missing")
if node:
mark(node_ok(node_ver),
f"Node version OK ({node_ver} >= 20.19, Vite requirement)",
f"Node {node_ver} too old for Vite (needs 20.19+). Install Node 20 "
f"(re-run ./install.sh, or NodeSource), then rebuild with: ncp update")
mark(bool(npm_path), f"npm installed ({version(npm_path)})", "npm missing")
mark((FRONTEND_DIR / "node_modules").is_dir(),
"Frontend node_modules installed",
"Frontend node_modules missing (run: ncp update)")
print("\nChecking Uvicorn...")
uvicorn_ok = subprocess.run([str(PYTHON), "-m", "uvicorn", "--version"],
capture_output=True).returncode == 0
mark(uvicorn_ok, "Uvicorn installed", "Uvicorn missing")
def importable(stmt):
return subprocess.run([str(PYTHON), "-c", stmt], cwd=str(ROOT),
capture_output=True).returncode == 0
print("\nChecking backend service...")
mark(importable("from synapse.main import sio_app"),
"Backend module importable", "Backend module failed to import")
print("\nChecking memory...")
mark((ROOT / "synapse" / "memory").is_dir(),
"Memory module directory found", "Missing memory module directory")
mark(importable("from synapse.memory.curator import extract_for_conversation"),
"Memory curator importable", "Memory curator failed to import")
mark(os.access(ROOT / "synapse" / "memory", os.W_OK),
"Memory database directory writable", "Memory database directory not writable")
print("\nChecking Ollama...")
_obin = ollama_bin()
mark(bool(_obin), f"Ollama binary found ({_obin})",
f"Ollama binary missing (not at {OLLAMA_BIN}, not on PATH)")
mark(OLLAMA_MODELS_DIR.is_dir(), f"Ollama models directory found ({OLLAMA_MODELS_DIR})",
f"Ollama models directory missing at {OLLAMA_MODELS_DIR}")
print()
cmd_status()
if fix:
_apply_fixes()
def cmd_update() -> None:
print("Updating Project Nexus...\n")
print("Skipping git pull — update only refreshes dependencies.\n")
# Same overlay choice sync.py makes, so update and restore cannot install
# different PyTorch builds on the same host.
sys.path.insert(0, str(ROOT / "bin"))
import importlib.util
spec = importlib.util.spec_from_file_location("sync", ROOT / "bin" / "sync.py")
sync = importlib.util.module_from_spec(spec)
spec.loader.exec_module(sync)
req = sync.requirements()
print(f"Updating backend Python dependencies ({req})...")
subprocess.run([str(PYTHON), "-m", "pip", "install", "-r", req], cwd=str(ROOT))
print("\nUpdating frontend dependencies...")
npm_path = npm()
if npm_path and FRONTEND_DIR.is_dir():
subprocess.run([npm_path, "install"], cwd=str(FRONTEND_DIR))
else:
print("npm or frontend directory missing — skipping npm install.")
print("\nRunning post-update diagnostics...")
cmd_doctor()
def cmd_upgrade() -> int:
"""Pull + rebuild + restart the backend. This is what the web UI's "install
update" button runs, so it must be spawned DETACHED from the backend - it
stops the very server that asked for it.
Ollama is deliberately left alone (stop_service, not cmd_stop): it is a
separate process on :11434, the restore does not touch a present binary, and
reloading a multi-GB model is the slowest part of a restart.
"""
print("Stopping backend...")
stop_service(SERVICES["backend"])
# --no-desktop: an in-app update should not rewrite XFCE panels/theme.
rc = sync_py("restore", "--no-desktop")
print("\nRestarting backend...")
launch(SERVICES["backend"])
ok = wait_for_port(SERVICES["backend"])
print("Backend is back up." if ok else "Backend did not come back - see runtime/backend.log")
return rc if ok else 1
def cmd_clean() -> None:
print("Cleaning Nexus runtime files...\n")
print("Removing PID files...")
for f in PID_DIR.glob("*.pid"):
f.unlink(missing_ok=True)
print("Removing logs...")
for f in LOG_DIR.glob("*.log"):
f.unlink(missing_ok=True)
print("Removing Python cache...")
for d in ROOT.rglob("__pycache__"):
shutil.rmtree(d, ignore_errors=True)
print("Removing Node/Vite cache...")
for d in FRONTEND_DIR.rglob(".vite"):
shutil.rmtree(d, ignore_errors=True)
print("\nCleanup complete.")
MODEL_CATALOG = [
("gemma3:1b", "~815 MB", "Google Gemma 3 — fast, lightweight"),
("gemma3:4b", "~3.3 GB", "Google Gemma 3 — balanced"),
("gemma3:12b", "~8.1 GB", "Google Gemma 3 — capable"),
("llama3.2:1b", "~1.3 GB", "Meta Llama 3.2 — fast, lightweight"),
("llama3.2:3b", "~2.0 GB", "Meta Llama 3.2 — compact, capable"),
("llama3.1:8b", "~4.7 GB", "Meta Llama 3.1 — strong general use"),
("mistral:latest", "~4.1 GB", "Mistral 7B — solid all-rounder"),
("mistral-nemo", "~7.1 GB", "Mistral Nemo 12B — strong reasoning"),
("qwen2.5:3b", "~2.0 GB", "Alibaba Qwen 2.5 — great at code"),
("qwen2.5:7b", "~4.7 GB", "Alibaba Qwen 2.5 — strong coder"),
("phi4-mini", "~2.5 GB", "Microsoft Phi-4 Mini — efficient"),
("phi4:14b", "~8.9 GB", "Microsoft Phi-4 — strong reasoning"),
("deepseek-r1:7b", "~4.7 GB", "DeepSeek R1 — reasoning model"),
("deepseek-r1:14b", "~9.0 GB", "DeepSeek R1 — strong reasoning"),
("codellama:7b", "~3.8 GB", "Meta Code Llama — code focused"),
("nomic-embed-text", "~274 MB", "Text embeddings model"),
]
def cmd_models(action, name) -> None:
if action == "list":
if not http_ok(settings.ollama_host.rstrip("/") + "/api/tags"):
print("Ollama is not running. Start the backend first with: ncp start -b")
return
raw = urllib.request.urlopen(settings.ollama_host.rstrip("/") + "/api/tags", timeout=5).read()
models = json.loads(raw).get("models", [])
print("Installed models:\n")
if not models:
print(" No models installed.")
return
for m in models:
mb = m["size"] // 1024 // 1024
size = f"{mb / 1024:.1f} GB" if mb >= 1024 else f"{mb} MB"
print(f" {m['name']:<35} {size}")
elif action in ("available", "search"):
print("Available models (via Ollama library):\n")
print(f" {'MODEL':<30} {'SIZE':<10} DESCRIPTION")
print(f" {'-----':<30} {'----':<10} -----------")
for model, size, desc in MODEL_CATALOG:
print(f" {model:<30} {size:<10} {desc}")
print("\nInstall any model with: ncp models install <model>")
print("Browse more at: https://ollama.com/library")
elif action == "install":
if not name:
print("Usage: ncp models install <model>")
print("Run 'ncp models available' to see options.")
return
obin = ollama_bin()
if not obin:
print(f"Ollama binary not found at {OLLAMA_BIN}, and no 'ollama' on PATH")
return
print(f"Pulling '{name}' into {OLLAMA_MODELS_DIR} ...\n")
subprocess.run([obin, "pull", name],
env={**os.environ, "OLLAMA_MODELS": str(OLLAMA_MODELS_DIR)})
print("\nDone. Run 'ncp models list' to verify.")
else:
print("Usage: ncp models <list|available|install <model>>")
def sync_py(*args) -> int:
"""sync.py is stdlib-only, so system python works before the venv exists."""
py = str(PYTHON) if PYTHON.exists() else sys.executable
return subprocess.run([py, str(ROOT / "bin" / "sync.py"), *args]).returncode
def cmd_restore(flag) -> int:
if flag in ("-c", "--claude", "check"):
return sync_py("restore", "--check") # dry run: no prompt, changes nothing
print("This pulls the latest backup from Gitea and rebuilds the environment")
print("(venv, npm, theme, panel). Local commits must be pushed or stashed first.")
if input("Continue? [y/N] ").strip().lower() != "y":
print("Restore cancelled.")
return 0
return sync_py("restore")
def cmd_web() -> int:
"""Per-platform UI launcher. On Linux nexus-app.sh already raises an existing
window, acts as a viewer when the stack is up, and only stops services it
started. Windows uses the pywebview window launch_nexus.ps1 opens."""
if WINDOWS:
if not http_ok(SERVICES["backend"].url):
launch(SERVICES["backend"])
wait_for_port(SERVICES["backend"])
return subprocess.run([str(PYTHON), str(ROOT / "bin" / "nexus_window.py")]).returncode
return subprocess.run([str(ROOT / "management" / "nexus-app.sh")]).returncode
def show_help() -> None:
print("""Nexus Command Tree
Usage: ncp <command> [options]
Commands:
panel Launch the Nexus Control Panel (tkinter)
web Open the web interface (starts the stack if needed)
chat <message> Send a message, stream the reply
memory list List memory facts
add <text> Add a fact (--section <name>)
rm <id> Delete a fact by id
playbook list List playbooks (* = active)
show <id> Print a playbook's goal + instructions
history [query] Recent conversations (optional keyword)
start Start ALL Nexus services (backend + frontend)
--frontend,-f Start only the frontend
--backend, -b Start only the backend
--ai, -a Start only the AI (Ollama); `start`/`start -b` already include it
stop Stop ALL Nexus services
--frontend,-f Stop only the frontend
--backend, -b Stop only the backend
kill Force-kill all Nexus processes by port (nuclear option)
refresh Restart all services
status Show service status
logs Show logs for all services
--frontend,-f Frontend logs
--backend, -b Backend logs
doctor [--fix] Run Nexus diagnostics (--fix applies safe repairs)
update Update Nexus dependencies
upgrade Pull, rebuild and restart the backend (what the UI's update button runs)
clean Remove runtime files and caches
models
list List installed models
available Show models available to install
install <name> Pull a model into Nexus
backup Backup Nexus to Gitea (git commit + push)
backup -f, full Backup + snapshot live desktop wiring/notes
backup -c Dry run: what a backup would commit/push
restore Restore Nexus from Gitea (git pull + rebuild)
restore -c Dry run: what a restore would apply
help, -h Show this help message""")
def main(argv) -> int:
cmd = argv[0] if argv else ""
rest = argv[1:]
arg = rest[0] if rest else None
if cmd in ("help", "-h", ""):
show_help()
elif cmd == "panel":
return subprocess.run([str(PYTHON), str(ROOT / "management" / "controlpanel.py")]).returncode
elif cmd == "web":
return cmd_web()
elif cmd in ("chat", "memory", "playbook", "history"):
return subprocess.run([str(PYTHON), str(ROOT / "management" / "nexus_api.py"),
cmd, *rest]).returncode
elif cmd == "start":
cmd_start(arg)
elif cmd == "stop":
cmd_stop(arg)
elif cmd == "refresh":
cmd_stop(None)
cmd_start(None)
elif cmd == "kill":
cmd_kill()
elif cmd == "status":
cmd_status()
elif cmd == "logs":
cmd_logs(arg)
elif cmd == "doctor":
cmd_doctor(fix="--fix" in rest)
elif cmd == "update":
cmd_update()
elif cmd == "upgrade":
return cmd_upgrade()
elif cmd == "clean":
cmd_clean()
elif cmd == "nvidia-reqs":
return subprocess.run([str(PYTHON), str(ROOT / "bin" / "gen-nvidia-reqs.py")]).returncode
elif cmd == "backup":
if arg in ("-f", "full"):
return sync_py("backup", "--full")
if arg in ("-c", "--claude", "check"):
return sync_py("backup", "--check")
if arg in (None, ""):
return sync_py("backup")
print("Usage: ncp backup [-f|full|-c]")
elif cmd == "restore":
if arg in (None, "", "-f", "full", "-c", "--claude", "check"):
return cmd_restore(arg)
print("Usage: ncp restore [-c]")
elif cmd == "models":
cmd_models(arg, rest[1] if len(rest) > 1 else None)
else:
print(f"Unknown Nexus command: '{cmd}'")
print("Use 'ncp help' for available commands.")
return 0
if __name__ == "__main__":
try:
sys.exit(main(sys.argv[1:]))
except KeyboardInterrupt:
# Ctrl+C is how you quit `ncp web` - it waits on the UI window. Without
# this it printed a six-frame traceback ending in WaitForSingleObject,
# which reads as a crash rather than "you pressed Ctrl+C". 130 is the
# conventional exit status for SIGINT.
print()
sys.exit(130)
nexusos_cli/nexus_api.py
+146
View File
@@ -0,0 +1,146 @@
#!/usr/bin/env python3
"""Backend for `ncp` subcommands (chat/memory/playbook/history).
Not a second CLI — `ncp` is the only entrypoint. This just hits the same REST
API the web UI uses, so the terminal matches the general features. httpx and
argparse only (both already present); no curses, no framework.
"""
import argparse
import json
import sys
import httpx
from synapse.nexus_config import settings
BASE = settings.api_url
def _client():
return httpx.Client(base_url=BASE, timeout=None)
def _die_if_down(exc: Exception):
if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)):
sys.exit(f"Backend not reachable at {BASE}. Start it: ncp start -b")
raise exc
def iter_chunks(lines):
"""Yield ('kind', payload) from raw SSE lines. kind is 'chunk' for reply
text, else the event name ('meta'/'done'/'error'/'title'/...). Pure so the
stream parsing is unit-testable without a live server (see test_nexus_api.py)."""
event = "message"
for line in lines:
if line == "": # blank line ends an event block
event = "message"
continue
if line.startswith("event:"):
event = line[6:].strip()
elif line.startswith("data:"):
data = line[5:].strip()
if event in ("message", ""):
yield "chunk", json.loads(data) # server json-encodes each token
else:
yield event, data
def cmd_chat(args):
body = {"message": " ".join(args.message)}
if args.model:
body["model"] = args.model
try:
with _client() as c, c.stream("POST", "/chat/stream", json=body) as r:
r.raise_for_status()
for kind, payload in iter_chunks(r.iter_lines()):
if kind == "chunk":
sys.stdout.write(payload)
sys.stdout.flush()
elif kind == "escalating":
sys.stderr.write("\n[escalating to Claude…]\n")
elif kind == "error":
sys.exit("\n" + json.loads(payload).get("detail", "chat failed"))
elif kind == "done":
break
print()
except Exception as e:
_die_if_down(e)
def cmd_memory(args):
try:
with _client() as c:
if args.action == "list":
items = c.get("/memory").json()["items"]
if not items:
print("No memory facts.")
return
section = None
for m in items:
if m["section"] != section:
section = m["section"]
print(f"\n## {section}")
print(f" {m['id'][:8]} {m['text']}")
elif args.action == "add":
m = c.post("/memory", json={"text": " ".join(args.rest),
"section": args.section}).json()
print(f"added {m['id'][:8]} to {m['section']}")
elif args.action == "rm":
c.delete(f"/memory/{args.rest[0]}").raise_for_status()
print("deleted")
except Exception as e:
_die_if_down(e)
def cmd_playbook(args):
try:
with _client() as c:
if args.action == "list":
pbs = c.get("/playbooks").json()["playbooks"]
for i, p in enumerate(pbs):
mark = "* " if i == 0 else " " # first = active system prompt
tags = f" [{', '.join(p['tags'])}]" if p["tags"] else ""
print(f"{mark}{p['id'][:8]} {p['title']}{tags}")
elif args.action == "show":
p = c.get(f"/playbooks/{args.rest[0]}").json()
print(f"# {p['title']}\n\nGoal: {p['goal']}\n\n{p['instructions']}")
except Exception as e:
_die_if_down(e)
def cmd_history(args):
try:
with _client() as c:
params = {"q": args.query} if args.query else {}
convs = c.get("/conversations", params=params).json()["conversations"]
for cv in convs[:args.limit]:
title = cv.get("title") or cv.get("preview") or "(untitled)"
print(f" {cv['id'][:8]} {title}")
except Exception as e:
_die_if_down(e)
def main(argv=None, prog="nexus"):
p = argparse.ArgumentParser(prog=prog)
sub = p.add_subparsers(dest="cmd", required=True)
c = sub.add_parser("chat"); c.add_argument("message", nargs="+")
c.add_argument("--model"); c.set_defaults(fn=cmd_chat)
m = sub.add_parser("memory"); m.add_argument("action", choices=["list", "add", "rm"])
m.add_argument("rest", nargs="*"); m.add_argument("--section", default="General")
m.set_defaults(fn=cmd_memory)
pb = sub.add_parser("playbook"); pb.add_argument("action", choices=["list", "show"])
pb.add_argument("rest", nargs="*"); pb.set_defaults(fn=cmd_playbook)
h = sub.add_parser("history"); h.add_argument("query", nargs="?")
h.add_argument("--limit", type=int, default=20); h.set_defaults(fn=cmd_history)
args = p.parse_args(argv)
result = args.fn(args)
return result if isinstance(result, int) else 0
if __name__ == "__main__":
main()