diff --git a/README.md b/README.md index e0dba2b..9efaa0e 100644 --- a/README.md +++ b/README.md @@ -193,6 +193,17 @@ The custom server in `server.mjs` also handles websocket upgrades for: Those upgrade paths are protected by the same auth cookie as the HTTP routes. +## Remote Controller Nodes + +The Wizards page includes **Spawn a Controller Node** for preparing a small OpenShell Control install on another VPS. This is intended for topologies where the browser-facing dashboard and the OpenShell gateway/sandbox hosts are not the same machine. + +The wizard supports two deployment paths: + +- **Manual Deploy** generates an SSH/bootstrap script, controller `.env` block, parent-controller URL, node shared secret, OpenShell/OpenClaw routing settings, and readiness checks. +- **Autodeploy** connects to the remote host over SSH using a one-time password supplied in the browser, optionally runs the bootstrap with sudo, installs a systemd service when available, and returns bounded stdout/stderr plus the observed host-key fingerprint. + +Autodeploy does not store the SSH password or write it into generated scripts. For host-key safety, provide an expected SHA256 host-key fingerprint or explicitly select trust-on-first-deploy on a trusted management network. After the controller is running, use its local OpenShell CLI context to manage the sandboxes reachable from that VPS. + ## Inference Endpoints Inference endpoint configuration is development-stage. diff --git a/app/api/controller-node/deploy/route.ts b/app/api/controller-node/deploy/route.ts new file mode 100644 index 0000000..e173344 --- /dev/null +++ b/app/api/controller-node/deploy/route.ts @@ -0,0 +1,174 @@ +import { NextResponse } from "next/server" +import { Client } from "ssh2" +import { buildControllerNodePlan, type ControllerPlanRequest } from "@/app/lib/controllerNodePlan" +import { upsertControllerNode } from "@/app/lib/controllerNodeRegistry" + +export const runtime = "nodejs" + +type DeployRequest = ControllerPlanRequest & { + remoteHost?: unknown + remotePort?: unknown + remoteUser?: unknown + remotePassword?: unknown + allowSudo?: unknown + acceptUnknownHostKey?: unknown + expectedHostKeySha256?: unknown +} + +const SAFE_REMOTE_USER = /^[a-z_][a-z0-9_-]{0,31}$/i +const MAX_OUTPUT_BYTES = 160_000 + +function text(value: unknown, fallback = "") { + return typeof value === "string" ? value.trim() : fallback +} + +function port(value: unknown) { + const parsed = Number.parseInt(String(value ?? "22"), 10) + return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : 22 +} + +function appendBounded(current: string, chunk: Buffer | string) { + const next = current + String(chunk) + return next.length > MAX_OUTPUT_BYTES ? next.slice(next.length - MAX_OUTPUT_BYTES) : next +} + +function normalizeFingerprint(value: string) { + return value.trim().replace(/^SHA256:/i, "") +} + +function runRemoteDeploy(params: { + host: string + port: number + username: string + password: string + script: string + allowSudo: boolean + acceptUnknownHostKey: boolean + expectedHostKeySha256: string +}) { + return new Promise<{ stdout: string; stderr: string; hostKeySha256: string | null }>((resolve, reject) => { + const conn = new Client() + let stdout = "" + let stderr = "" + let hostKeySha256: string | null = null + let settled = false + + const finish = (error?: Error) => { + if (settled) return + settled = true + conn.end() + if (error) reject(error) + else resolve({ stdout: stdout.trim(), stderr: stderr.trim(), hostKeySha256 }) + } + + const timer = setTimeout(() => { + finish(new Error("Remote deploy timed out after 10 minutes")) + }, 10 * 60 * 1000) + + conn + .on("ready", () => { + const command = params.allowSudo ? "sudo -S -p '' bash -s" : "bash -s" + conn.exec(command, { pty: params.allowSudo }, (error, stream) => { + if (error) { + clearTimeout(timer) + finish(error) + return + } + + stream + .on("close", (code: number | null, signal: string | null) => { + clearTimeout(timer) + if (code === 0) { + finish() + } else { + finish(new Error(`Remote deploy failed with exit code ${code ?? "unknown"}${signal ? ` signal ${signal}` : ""}`)) + } + }) + .on("data", (chunk: Buffer) => { + stdout = appendBounded(stdout, chunk) + }) + + stream.stderr.on("data", (chunk: Buffer) => { + stderr = appendBounded(stderr, chunk) + }) + + if (params.allowSudo) stream.write(`${params.password}\n`) + stream.end(`${params.script}\n`) + }) + }) + .on("error", (error) => { + clearTimeout(timer) + finish(error) + }) + .connect({ + host: params.host, + port: params.port, + username: params.username, + password: params.password, + readyTimeout: 30000, + hostHash: "sha256", + hostVerifier: (hashedKey: string) => { + hostKeySha256 = hashedKey + const expected = normalizeFingerprint(params.expectedHostKeySha256) + if (expected) return hashedKey === expected + return params.acceptUnknownHostKey + }, + }) + }) +} + +export async function POST(request: Request) { + try { + const body = (await request.json().catch(() => ({}))) as DeployRequest + const remoteHost = text(body.remoteHost, text(body.controllerHost)) + const remoteUser = text(body.remoteUser) + const remotePassword = typeof body.remotePassword === "string" ? body.remotePassword : "" + const expectedHostKeySha256 = text(body.expectedHostKeySha256) + const acceptUnknownHostKey = Boolean(body.acceptUnknownHostKey) + const allowSudo = Boolean(body.allowSudo) + + if (!remoteHost) throw new Error("remoteHost is required") + if (!remoteUser || !SAFE_REMOTE_USER.test(remoteUser)) throw new Error("remoteUser must be a valid Linux username") + if (!remotePassword) throw new Error("remotePassword is required for autodeploy") + if (!expectedHostKeySha256 && !acceptUnknownHostKey) { + throw new Error("Provide expectedHostKeySha256 or explicitly allow trust-on-first-deploy.") + } + + const plan = buildControllerNodePlan({ + ...body, + controllerHost: text(body.controllerHost, remoteHost), + }) + const deployed = await runRemoteDeploy({ + host: remoteHost, + port: port(body.remotePort), + username: remoteUser, + password: remotePassword, + script: plan.commands.localBootstrap, + allowSudo, + acceptUnknownHostKey, + expectedHostKeySha256, + }) + await upsertControllerNode({ + id: plan.controller.name, + name: plan.controller.name, + host: plan.controller.host, + url: plan.controller.url, + role: "controller-node", + }) + + return NextResponse.json({ + ok: true, + ...plan, + controller: plan.controller, + hostKeySha256: deployed.hostKeySha256, + stdout: deployed.stdout, + stderr: deployed.stderr, + note: allowSudo + ? "Autodeploy completed using sudo. The controller service was installed when systemd was available." + : "Autodeploy completed without sudo. Start the controller manually if systemd service installation was skipped.", + }) + } catch (error) { + const message = error instanceof Error ? error.message : "Failed to autodeploy controller node" + return NextResponse.json({ ok: false, error: message }, { status: 400 }) + } +} diff --git a/app/api/controller-node/plan/route.ts b/app/api/controller-node/plan/route.ts new file mode 100644 index 0000000..5d0be8c --- /dev/null +++ b/app/api/controller-node/plan/route.ts @@ -0,0 +1,21 @@ +import { NextResponse } from "next/server" +import { buildControllerNodePlan, type ControllerPlanRequest } from "@/app/lib/controllerNodePlan" +import { upsertControllerNode } from "@/app/lib/controllerNodeRegistry" + +export async function POST(request: Request) { + try { + const body = (await request.json().catch(() => ({}))) as ControllerPlanRequest + const plan = buildControllerNodePlan(body) + await upsertControllerNode({ + id: plan.controller.name, + name: plan.controller.name, + host: plan.controller.host, + url: plan.controller.url, + role: "controller-node", + }) + return NextResponse.json({ ok: true, ...plan }) + } catch (error) { + const message = error instanceof Error ? error.message : "Failed to build controller node plan" + return NextResponse.json({ ok: false, error: message }, { status: 400 }) + } +} diff --git a/app/api/controller-node/registry/route.ts b/app/api/controller-node/registry/route.ts new file mode 100644 index 0000000..a9320fb --- /dev/null +++ b/app/api/controller-node/registry/route.ts @@ -0,0 +1,36 @@ +import { NextResponse } from "next/server" +import { listControllerNodes, renameControllerNode, upsertControllerNode } from "@/app/lib/controllerNodeRegistry" + +export async function GET() { + try { + return NextResponse.json({ nodes: await listControllerNodes() }) + } catch (error) { + const message = error instanceof Error ? error.message : "Failed to load controller nodes" + return NextResponse.json({ error: message }, { status: 500 }) + } +} + +export async function POST(request: Request) { + try { + const body = await request.json().catch(() => ({})) + const action = typeof body?.action === "string" ? body.action : "upsert" + + if (action === "rename") { + const node = await renameControllerNode(String(body?.nodeId || ""), String(body?.name || "")) + return NextResponse.json({ node, nodes: await listControllerNodes() }) + } + + const node = await upsertControllerNode({ + id: body?.id, + name: body?.name, + host: body?.host, + url: body?.url, + role: body?.role, + }) + + return NextResponse.json({ node, nodes: await listControllerNodes() }) + } catch (error) { + const message = error instanceof Error ? error.message : "Failed to update controller nodes" + return NextResponse.json({ error: message }, { status: 400 }) + } +} diff --git a/app/api/openapi/route.ts b/app/api/openapi/route.ts new file mode 100644 index 0000000..ed83600 --- /dev/null +++ b/app/api/openapi/route.ts @@ -0,0 +1,16 @@ +import { NextResponse } from "next/server" +import { buildOpenApiSpec } from "@/app/lib/openapiSpec" + +function baseUrlFromRequest(request: Request) { + const forwardedProto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim() + const forwardedHost = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim() + const host = forwardedHost || request.headers.get("host") + if (!host) return "" + + const protocol = forwardedProto || new URL(request.url).protocol.replace(":", "") || "http" + return `${protocol}://${host}` +} + +export async function GET(request: Request) { + return NextResponse.json(buildOpenApiSpec(baseUrlFromRequest(request))) +} diff --git a/app/components/HelpPanel.tsx b/app/components/HelpPanel.tsx index b1515d4..fd7df8f 100644 --- a/app/components/HelpPanel.tsx +++ b/app/components/HelpPanel.tsx @@ -134,11 +134,37 @@ export default function HelpPanel({ sandboxes }: { sandboxes: SandboxInventoryIt
-

Operator Guide

-

Help

-

- Quick reference for running sandboxes, moving files, preserving work, and cloning a prepared environment. -

+
+
+

Operator Guide

+

Help

+

+ Quick reference for running sandboxes, moving files, preserving work, and cloning a prepared environment. +

+
+ + Open Swagger + +
+
+ +
+
+
+

API Reference

+

+ Swagger opens the controller-node API reference in a separate page, including OpenAPI JSON, endpoint details, schemas, and example payloads. +

+
+
+ + Swagger Page + + + OpenAPI JSON + +
+
diff --git a/app/components/Sidebar.tsx b/app/components/Sidebar.tsx index daf2412..b5c3cea 100644 --- a/app/components/Sidebar.tsx +++ b/app/components/Sidebar.tsx @@ -1,5 +1,16 @@ "use client" +import { useEffect, useMemo, useState } from "react" + +type ControllerNodeRecord = { + id: string + name: string + host: string + url: string + role: "local" | "controller-node" + status: "configured" | "local" +} + interface SidebarProps { sandboxesRunning: number sandboxesTotal: number @@ -19,6 +30,8 @@ interface SidebarProps { terminalDisabled?: boolean } +const SELECTED_CONTROLLER_NODE_KEY = "openshell-control-selected-node" + export default function Sidebar({ sandboxesRunning, sandboxesTotal, @@ -37,6 +50,80 @@ export default function Sidebar({ onLogout, terminalDisabled = false, }: SidebarProps) { + const [controllerNodes, setControllerNodes] = useState([]) + const [selectedNodeId, setSelectedNodeId] = useState("local") + const [nodeMenuOpen, setNodeMenuOpen] = useState(false) + const [friendlyNameDraft, setFriendlyNameDraft] = useState("") + const [friendlyNameSaving, setFriendlyNameSaving] = useState(false) + const [friendlyNameMessage, setFriendlyNameMessage] = useState("") + + const selectedNode = useMemo( + () => controllerNodes.find((node) => node.id === selectedNodeId) || controllerNodes[0] || null, + [controllerNodes, selectedNodeId], + ) + const hasRemoteNodes = controllerNodes.some((node) => node.role === "controller-node") + + useEffect(() => { + const stored = window.localStorage.getItem(SELECTED_CONTROLLER_NODE_KEY) + if (stored) setSelectedNodeId(stored) + }, []) + + useEffect(() => { + let cancelled = false + const loadControllerNodes = () => { + fetch("/api/controller-node/registry", { cache: "no-store" }) + .then((response) => response.json()) + .then((data) => { + if (cancelled) return + const nodes = Array.isArray(data.nodes) ? data.nodes : [] + setControllerNodes(nodes) + if (nodes.length > 1) setNodeMenuOpen(true) + setSelectedNodeId((current) => nodes.some((node: ControllerNodeRecord) => node.id === current) ? current : nodes[0]?.id || "local") + }) + .catch(() => { + if (!cancelled) setControllerNodes([]) + }) + } + + loadControllerNodes() + window.addEventListener("controller-nodes-changed", loadControllerNodes) + return () => { + cancelled = true + window.removeEventListener("controller-nodes-changed", loadControllerNodes) + } + }, []) + + useEffect(() => { + if (!selectedNode) return + setFriendlyNameDraft(selectedNode.name) + window.localStorage.setItem(SELECTED_CONTROLLER_NODE_KEY, selectedNode.id) + }, [selectedNode]) + + async function saveFriendlyName() { + if (!selectedNode || friendlyNameSaving) return + try { + setFriendlyNameSaving(true) + setFriendlyNameMessage("") + const response = await fetch("/api/controller-node/registry", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + action: "rename", + nodeId: selectedNode.id, + name: friendlyNameDraft, + }), + }) + const data = await response.json() + if (!response.ok) throw new Error(data.error || "Failed to save node name") + setControllerNodes(Array.isArray(data.nodes) ? data.nodes : []) + setFriendlyNameMessage("Saved") + } catch (error) { + setFriendlyNameMessage(error instanceof Error ? error.message : "Failed to save") + } finally { + setFriendlyNameSaving(false) + } + } + const navItemClass = (active = false, danger = false) => `w-full flex items-center gap-3 rounded px-3 py-2.5 text-left transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--nvidia-green)] max-lg:min-w-24 max-lg:flex-col max-lg:justify-center max-lg:gap-1 max-lg:px-2 max-lg:py-2 ${ active ? danger @@ -47,21 +134,85 @@ export default function Sidebar({ return (
) diff --git a/app/lib/controllerNodePlan.ts b/app/lib/controllerNodePlan.ts new file mode 100644 index 0000000..9c0e071 --- /dev/null +++ b/app/lib/controllerNodePlan.ts @@ -0,0 +1,268 @@ +import { randomBytes } from "node:crypto" + +export type ControllerPlanRequest = { + controllerName?: unknown + controllerHost?: unknown + sshTarget?: unknown + installDir?: unknown + repoUrl?: unknown + dashboardPort?: unknown + terminalPort?: unknown + openclawUrl?: unknown + openClawDashboardUrl?: unknown + openshellGateway?: unknown + parentControllerUrl?: unknown + existingToken?: unknown +} + +export type ControllerNodePlan = { + controller: { + name: string + host: string + url: string + sshTarget: string + installDir: string + repoUrl: string + parentControllerUrl: string + dashboardPort: number + terminalPort: number + } + env: string + serviceUnit: string + commands: { + ssh: string + localBootstrap: string + start: string + terminal: string + } + checks: string[] +} + +const DEFAULT_REPO_URL = process.env.OPENSHELL_CONTROL_REPO_URL || "https://github.com/mmckeen-nv/openshell_controller.git" +const SAFE_NAME = /^[a-z0-9][a-z0-9-]{1,62}$/i +const SAFE_HOST = /^[a-z0-9.-]+$/i +const SAFE_SSH_TARGET = /^([a-z0-9._-]+@)?[a-z0-9.-]+(:[0-9]{1,5})?$/i + +function text(value: unknown, fallback = "") { + return typeof value === "string" ? value.trim() : fallback +} + +function numberValue(value: unknown, fallback: number) { + const parsed = Number.parseInt(String(value ?? ""), 10) + return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback +} + +export function shellSingleQuote(value: string) { + return `'${value.replace(/'/g, "'\\''")}'` +} + +function sshBootstrapInvocation(target: string) { + const match = target.match(/^((?:[a-z0-9._-]+@)?[a-z0-9.-]+)(?::([0-9]{1,5}))?$/i) + if (!match) throw new Error("sshTarget must look like user@host or user@host:port") + const [, host, targetPort] = match + return targetPort ? `ssh -p ${targetPort} ${shellSingleQuote(host)}` : `ssh ${shellSingleQuote(host)}` +} + +function validateUrl(value: string, label: string) { + if (/^git@[a-z0-9.-]+:[a-z0-9._/-]+\.git$/i.test(value)) return value + if (/^ssh:\/\/[^\s]+$/i.test(value)) return value + try { + const parsed = new URL(value) + if (parsed.protocol === "https:" || parsed.protocol === "http:") return value + } catch { + // handled below + } + throw new Error(`${label} must be an http(s), ssh, or git SSH URL`) +} + +function validateHttpUrl(value: string, label: string) { + try { + const parsed = new URL(value) + if (parsed.protocol === "https:" || parsed.protocol === "http:") return value.replace(/\/$/, "") + } catch { + // handled below + } + throw new Error(`${label} must be an http(s) URL`) +} + +function validateInstallDir(value: string) { + if (!value || value.includes("\0") || value.includes("\n")) throw new Error("installDir is invalid") + if (!value.startsWith("/")) throw new Error("installDir must be an absolute path") + return value.replace(/\/$/, "") +} + +function controllerToken(value: unknown) { + const existing = text(value) + if (existing) { + if (!/^[a-zA-Z0-9._~:-]{20,256}$/.test(existing)) throw new Error("existingToken contains unsupported characters") + return existing + } + return randomBytes(32).toString("base64url") +} + +function buildEnvBlock(input: { + controllerName: string + parentControllerUrl: string + token: string + dashboardPort: number + terminalPort: number + openclawUrl: string + openshellGateway: string +}) { + const registry = JSON.stringify({ + nodes: [ + { + id: input.controllerName, + name: input.controllerName, + url: `http://127.0.0.1:${input.dashboardPort}`, + role: "controller-node", + }, + ], + }) + + return [ + `CONTROLLER_NODE_ID=${input.controllerName}`, + `CONTROLLER_NODE_PARENT_URL=${input.parentControllerUrl}`, + `CONTROLLER_NODE_SHARED_SECRET=${input.token}`, + `NEXT_PUBLIC_DASHBOARD_PORT=${input.dashboardPort}`, + "NEXT_PUBLIC_API_BASE=", + "NEXT_PUBLIC_ENABLE_SANDBOX_OPERATIONS=true", + `OPENSHELL_GATEWAY=${input.openshellGateway}`, + "OPEN_SHELL_CONTAINER=openshell-control", + "TERMINAL_SERVER_AUTOSTART=true", + `TERMINAL_SERVER_PORT=${input.terminalPort}`, + `OPENCLAW_DASHBOARD_URL=${input.openclawUrl}`, + `OPENCLAW_INSTANCE_REGISTRY_JSON=${registry}`, + ].join("\n") +} + +function serviceUnit(installDir: string) { + return `[Unit] +Description=OpenShell Controller Node +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=${installDir} +EnvironmentFile=${installDir}/.env.local +ExecStart=/usr/bin/npm run start +Restart=always +RestartSec=5 +User=root + +[Install] +WantedBy=multi-user.target +` +} + +export function buildControllerNodePlan(input: ControllerPlanRequest = {}): ControllerNodePlan { + const controllerName = text(input.controllerName, "remote-controller-01").toLowerCase() + if (!SAFE_NAME.test(controllerName)) throw new Error("controllerName must be 2-63 letters, numbers, or hyphens") + + const host = text(input.controllerHost) + if (!host || !SAFE_HOST.test(host)) throw new Error("controllerHost must be a hostname or IP address") + + const installDir = validateInstallDir(text(input.installDir, "/opt/openshell-control")) + const repoUrl = validateUrl(text(input.repoUrl, DEFAULT_REPO_URL), "repoUrl") + const dashboardPort = numberValue(input.dashboardPort, 3000) + const terminalPort = numberValue(input.terminalPort, 3011) + const openclawUrl = validateHttpUrl(text(input.openclawUrl, text(input.openClawDashboardUrl, "http://localhost:3002")), "openclawUrl") + const openshellGateway = text(input.openshellGateway, "local") + if (!/^[a-z0-9._:-]+$/i.test(openshellGateway)) throw new Error("openshellGateway contains unsupported characters") + const parentControllerUrl = validateHttpUrl(text(input.parentControllerUrl, "http://localhost:3000"), "parentControllerUrl") + const token = controllerToken(input.existingToken) + const sshTarget = text(input.sshTarget, host) + if (!SAFE_SSH_TARGET.test(sshTarget)) throw new Error("sshTarget must look like user@host or user@host:port") + const envBlock = buildEnvBlock({ + controllerName, + parentControllerUrl, + token, + dashboardPort, + terminalPort, + openclawUrl, + openshellGateway, + }) + const unit = serviceUnit(installDir) + const remoteBootstrap = `#!/usr/bin/env bash +set -euo pipefail + +INSTALL_DIR=${shellSingleQuote(installDir)} +REPO_URL=${shellSingleQuote(repoUrl)} +DASHBOARD_PORT=${dashboardPort} +TERMINAL_PORT=${terminalPort} + +for binary in git node npm; do + if ! command -v "$binary" >/dev/null 2>&1; then + echo "Missing required binary: $binary" >&2 + echo "Install Node.js 20+, npm, and git before running this bootstrap." >&2 + exit 1 + fi +done + +mkdir -p "$(dirname "$INSTALL_DIR")" +if [ -d "$INSTALL_DIR/.git" ]; then + git -C "$INSTALL_DIR" fetch --depth=1 origin + git -C "$INSTALL_DIR" pull --ff-only +else + git clone --depth=1 "$REPO_URL" "$INSTALL_DIR" +fi + +cd "$INSTALL_DIR" +./install.sh --no-build --no-audit + +cat > .env.controller-node <<'ENV_CONTROLLER_NODE' +${envBlock} +ENV_CONTROLLER_NODE + +touch .env.local +TMP_ENV="$(mktemp)" +grep -Ev '^(CONTROLLER_NODE_ID|CONTROLLER_NODE_PARENT_URL|CONTROLLER_NODE_SHARED_SECRET|NEXT_PUBLIC_DASHBOARD_PORT|NEXT_PUBLIC_API_BASE|NEXT_PUBLIC_ENABLE_SANDBOX_OPERATIONS|OPENSHELL_GATEWAY|OPEN_SHELL_CONTAINER|TERMINAL_SERVER_AUTOSTART|TERMINAL_SERVER_PORT|OPENCLAW_DASHBOARD_URL|OPENCLAW_INSTANCE_REGISTRY_JSON)=' .env.local > "$TMP_ENV" || true +cat "$TMP_ENV" .env.controller-node > .env.local +rm -f "$TMP_ENV" +chmod 600 .env.local .env.controller-node + +npm run build + +if command -v systemctl >/dev/null 2>&1 && [ -w /etc/systemd/system ]; then + cat > /etc/systemd/system/openshell-controller-node.service <<'SYSTEMD' +${unit} +SYSTEMD + systemctl daemon-reload + systemctl enable --now openshell-controller-node.service + systemctl restart openshell-controller-node.service +else + echo "Systemd service was not installed. Start manually with: npm run start -- --hostname 0.0.0.0 --port $DASHBOARD_PORT" +fi + +echo "Controller node ready at http://${host}:$DASHBOARD_PORT" +echo "OpenShell CLI is installed in $INSTALL_DIR and can manage sandboxes reachable from this VPS." +` + + return { + controller: { + name: controllerName, + host, + url: `http://${host}:${dashboardPort}`, + sshTarget, + installDir, + repoUrl, + parentControllerUrl, + dashboardPort, + terminalPort, + }, + env: envBlock, + serviceUnit: unit, + commands: { + ssh: `${sshBootstrapInvocation(sshTarget)} 'bash -s' <<'REMOTE_CONTROLLER'\n${remoteBootstrap}\nREMOTE_CONTROLLER`, + localBootstrap: remoteBootstrap, + start: `cd ${shellSingleQuote(installDir)} && npm run start -- --hostname 0.0.0.0 --port ${dashboardPort}`, + terminal: `TERMINAL_SERVER_PORT=${terminalPort} npm run terminal-server`, + }, + checks: [ + `curl -fsS http://${host}:${dashboardPort}/api/controller-node/health`, + `curl -fsS ${openclawUrl}/api/instances`, + `ssh ${host} 'cd ${shellSingleQuote(installDir)} && npm run status'`, + ], + } +} diff --git a/app/lib/controllerNodeRegistry.ts b/app/lib/controllerNodeRegistry.ts new file mode 100644 index 0000000..a1672b5 --- /dev/null +++ b/app/lib/controllerNodeRegistry.ts @@ -0,0 +1,156 @@ +import { mkdir, readFile, writeFile } from "node:fs/promises" +import { hostname } from "node:os" +import path from "node:path" + +export type ControllerNodeRecord = { + id: string + name: string + host: string + url: string + role: "local" | "controller-node" + status: "configured" | "local" + updatedAt: string +} + +type StoreShape = { + nodes: Record +} + +const STORE_DIR = process.env.OPENSHELL_CONTROL_STATE_DIR || path.join(process.cwd(), ".runtime") +const STORE_PATH = path.join(STORE_DIR, "controller-nodes.json") +const SAFE_ID = /^[a-z0-9][a-z0-9._:-]{0,127}$/i + +function now() { + return new Date().toISOString() +} + +function text(value: unknown, fallback = "") { + return typeof value === "string" && value.trim() ? value.trim() : fallback +} + +function slugify(value: string) { + return value + .trim() + .toLowerCase() + .replace(/[^a-z0-9._:-]+/g, "-") + .replace(/^-+|-+$/g, "") + .slice(0, 128) +} + +function localControllerNode(): ControllerNodeRecord { + const port = process.env.NEXT_PUBLIC_DASHBOARD_PORT || process.env.PORT || "3000" + const url = process.env.OPENSHELL_CONTROL_PUBLIC_URL || `http://localhost:${port}` + return { + id: "local", + name: process.env.OPENSHELL_CONTROL_FRIENDLY_NAME || "Local Controller", + host: hostname(), + url, + role: "local", + status: "local", + updatedAt: now(), + } +} + +function emptyStore(): StoreShape { + return { nodes: {} } +} + +function normalizeNode(input: Partial, existing?: ControllerNodeRecord | null): ControllerNodeRecord { + const host = text(input.host, existing?.host || "") + const url = text(input.url, existing?.url || (host ? `http://${host}:3000` : "")) + const id = slugify(text(input.id, existing?.id || host || url)) + if (!id || !SAFE_ID.test(id)) throw new Error("controller node id is invalid") + if (!host) throw new Error("controller node host is required") + if (!url) throw new Error("controller node url is required") + + return { + id, + name: text(input.name, existing?.name || host), + host, + url, + role: input.role === "local" ? "local" : "controller-node", + status: input.status === "local" ? "local" : "configured", + updatedAt: now(), + } +} + +function parseEnvNodes() { + const raw = process.env.OPENSHELL_CONTROLLER_NODES_JSON || process.env.OPENCLAW_INSTANCE_REGISTRY_JSON + if (!raw?.trim()) return [] + + try { + const parsed = JSON.parse(raw) + const entries = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.nodes) ? parsed.nodes : [] + return entries + .map((entry: unknown) => { + if (!entry || typeof entry !== "object") return null + const record = entry as Record + const url = text(record.url, text(record.controlUiOrigin, text(record.dashboardUrl))) + const host = text(record.host, url ? new URL(url).hostname : "") + if (!host || !url) return null + return normalizeNode({ + id: text(record.id, host), + name: text(record.name, text(record.label, host)), + host, + url, + role: record.role === "local" ? "local" : "controller-node", + }) + }) + .filter((entry: ControllerNodeRecord | null): entry is ControllerNodeRecord => Boolean(entry)) + } catch { + return [] + } +} + +async function readStore(): Promise { + try { + const raw = await readFile(STORE_PATH, "utf8") + const parsed = JSON.parse(raw) + if (!parsed || typeof parsed !== "object" || !parsed.nodes || typeof parsed.nodes !== "object") return emptyStore() + return { nodes: parsed.nodes } + } catch { + return emptyStore() + } +} + +async function writeStore(store: StoreShape) { + await mkdir(STORE_DIR, { recursive: true, mode: 0o700 }) + await writeFile(STORE_PATH, JSON.stringify(store, null, 2), { mode: 0o600 }) +} + +export async function listControllerNodes() { + const store = await readStore() + const merged = new Map() + const local = localControllerNode() + merged.set(local.id, { ...local, ...store.nodes[local.id], role: "local", status: "local" }) + + for (const node of parseEnvNodes()) { + merged.set(node.id, { ...node, ...store.nodes[node.id] }) + } + for (const node of Object.values(store.nodes)) { + merged.set(node.id, node) + } + + return Array.from(merged.values()).sort((a, b) => { + if (a.role === "local") return -1 + if (b.role === "local") return 1 + return a.name.localeCompare(b.name) + }) +} + +export async function upsertControllerNode(input: Partial) { + const store = await readStore() + const id = slugify(text(input.id, input.host || input.url || "")) + const existing = id ? store.nodes[id] : null + const node = normalizeNode(input, existing) + store.nodes[node.id] = node + await writeStore(store) + return node +} + +export async function renameControllerNode(nodeId: string, name: string) { + const nodes = await listControllerNodes() + const existing = nodes.find((node) => node.id === slugify(nodeId)) + if (!existing) throw new Error("controller node was not found") + return upsertControllerNode({ ...existing, name }) +} diff --git a/app/lib/openapiSpec.ts b/app/lib/openapiSpec.ts new file mode 100644 index 0000000..ac22b2e --- /dev/null +++ b/app/lib/openapiSpec.ts @@ -0,0 +1,361 @@ +export function buildOpenApiSpec(baseUrl = "") { + const serverUrl = baseUrl || "http://localhost:3000" + + return { + openapi: "3.1.0", + info: { + title: "OpenShell Control API", + version: "0.1.0", + description: "Controller-node deployment and registry APIs for OpenShell Control.", + }, + servers: [ + { + url: serverUrl, + description: "Current OpenShell Control instance", + }, + ], + security: [{ sessionCookie: [] }], + tags: [ + { + name: "Controller Nodes", + description: "Plan, deploy, register, and rename remote OpenShell Control controller nodes.", + }, + ], + paths: { + "/api/controller-node/plan": { + post: { + tags: ["Controller Nodes"], + summary: "Generate a remote controller-node launch kit", + description: "Builds a bootstrap script, environment block, systemd unit, and readiness checks for a remote controller node. The generated node is also registered locally.", + operationId: "createControllerNodePlan", + requestBody: { + required: true, + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ControllerPlanRequest" }, + examples: { + manual: { + summary: "Manual deploy plan", + value: { + controllerName: "remote-controller-01", + controllerHost: "203.0.113.10", + sshTarget: "ubuntu@203.0.113.10", + installDir: "/opt/openshell-control", + repoUrl: "https://github.com/mmckeen-nv/openshell_controller.git", + dashboardPort: 3000, + terminalPort: 3011, + openClawDashboardUrl: "http://127.0.0.1:18789/", + openshellGateway: "nemoclaw", + parentControllerUrl: "http://localhost:3100", + }, + }, + }, + }, + }, + }, + responses: { + "200": { + description: "Launch kit generated", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ControllerPlanResponse" }, + }, + }, + }, + "400": { $ref: "#/components/responses/BadRequest" }, + "401": { $ref: "#/components/responses/Unauthorized" }, + }, + }, + }, + "/api/controller-node/deploy": { + post: { + tags: ["Controller Nodes"], + summary: "Autodeploy a controller node over SSH", + description: "Connects to a VPS over SSH, optionally elevates with sudo, runs the generated bootstrap, and registers the node locally. The remote password is used once and is not persisted.", + operationId: "autodeployControllerNode", + requestBody: { + required: true, + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ControllerDeployRequest" }, + examples: { + sudo: { + summary: "Autodeploy with sudo and pinned host key", + value: { + controllerName: "remote-controller-01", + controllerHost: "203.0.113.10", + parentControllerUrl: "http://localhost:3100", + remoteHost: "203.0.113.10", + remotePort: 22, + remoteUser: "ubuntu", + remotePassword: "one-time-password", + allowSudo: true, + expectedHostKeySha256: "SHA256:replace-with-remote-host-fingerprint", + }, + }, + }, + }, + }, + }, + responses: { + "200": { + description: "Remote deploy completed", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ControllerDeployResponse" }, + }, + }, + }, + "400": { $ref: "#/components/responses/BadRequest" }, + "401": { $ref: "#/components/responses/Unauthorized" }, + }, + }, + }, + "/api/controller-node/registry": { + get: { + tags: ["Controller Nodes"], + summary: "List managed controller nodes", + operationId: "listControllerNodes", + responses: { + "200": { + description: "Managed nodes", + content: { + "application/json": { + schema: { + type: "object", + properties: { + nodes: { + type: "array", + items: { $ref: "#/components/schemas/ControllerNode" }, + }, + }, + required: ["nodes"], + }, + }, + }, + }, + "401": { $ref: "#/components/responses/Unauthorized" }, + }, + }, + post: { + tags: ["Controller Nodes"], + summary: "Register or rename a controller node", + description: "Upserts a controller node, or renames an existing node when action is rename.", + operationId: "updateControllerNodeRegistry", + requestBody: { + required: true, + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ControllerRegistryRequest" }, + examples: { + rename: { + summary: "Rename a node", + value: { + action: "rename", + nodeId: "remote-controller-01", + name: "Lab VPS East", + }, + }, + }, + }, + }, + }, + responses: { + "200": { + description: "Registry updated", + content: { + "application/json": { + schema: { + type: "object", + properties: { + node: { $ref: "#/components/schemas/ControllerNode" }, + nodes: { + type: "array", + items: { $ref: "#/components/schemas/ControllerNode" }, + }, + }, + required: ["node", "nodes"], + }, + }, + }, + }, + "400": { $ref: "#/components/responses/BadRequest" }, + "401": { $ref: "#/components/responses/Unauthorized" }, + }, + }, + }, + "/api/openapi": { + get: { + tags: ["Controller Nodes"], + summary: "Fetch the OpenAPI document", + operationId: "getOpenApiSpec", + responses: { + "200": { + description: "OpenAPI 3.1 document", + content: { + "application/json": { + schema: { + type: "object", + additionalProperties: true, + }, + }, + }, + }, + }, + }, + }, + }, + components: { + securitySchemes: { + sessionCookie: { + type: "apiKey", + in: "cookie", + name: process.env.OPENSHELL_CONTROL_COOKIE_NAME || "openshell_control_session", + }, + }, + responses: { + BadRequest: { + description: "Invalid request", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ErrorResponse" }, + }, + }, + }, + Unauthorized: { + description: "Authentication required", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/ErrorResponse" }, + }, + }, + }, + }, + schemas: { + ErrorResponse: { + type: "object", + properties: { + ok: { type: "boolean", example: false }, + error: { type: "string" }, + }, + required: ["error"], + }, + ControllerNode: { + type: "object", + properties: { + id: { type: "string", example: "remote-controller-01" }, + name: { type: "string", example: "Lab VPS East" }, + host: { type: "string", example: "203.0.113.10" }, + url: { type: "string", format: "uri", example: "http://203.0.113.10:3000" }, + role: { type: "string", enum: ["local", "controller-node"] }, + status: { type: "string", enum: ["local", "configured"] }, + updatedAt: { type: "string", format: "date-time" }, + }, + required: ["id", "name", "host", "url", "role", "status", "updatedAt"], + }, + ControllerPlanRequest: { + type: "object", + properties: { + controllerName: { type: "string", example: "remote-controller-01" }, + controllerHost: { type: "string", example: "203.0.113.10" }, + sshTarget: { type: "string", example: "ubuntu@203.0.113.10" }, + installDir: { type: "string", example: "/opt/openshell-control" }, + repoUrl: { type: "string", example: "https://github.com/mmckeen-nv/openshell_controller.git" }, + dashboardPort: { type: "integer", minimum: 1, maximum: 65535, example: 3000 }, + terminalPort: { type: "integer", minimum: 1, maximum: 65535, example: 3011 }, + openClawDashboardUrl: { type: "string", format: "uri", example: "http://127.0.0.1:18789/" }, + openshellGateway: { type: "string", example: "nemoclaw" }, + parentControllerUrl: { type: "string", format: "uri", example: "http://localhost:3100" }, + existingToken: { type: "string", description: "Optional existing controller shared secret." }, + }, + required: ["controllerHost"], + }, + ControllerDeployRequest: { + allOf: [ + { $ref: "#/components/schemas/ControllerPlanRequest" }, + { + type: "object", + properties: { + remoteHost: { type: "string", example: "203.0.113.10" }, + remotePort: { type: "integer", minimum: 1, maximum: 65535, example: 22 }, + remoteUser: { type: "string", example: "ubuntu" }, + remotePassword: { type: "string", format: "password" }, + allowSudo: { type: "boolean", default: false }, + acceptUnknownHostKey: { type: "boolean", default: false }, + expectedHostKeySha256: { type: "string", example: "SHA256:replace-with-remote-host-fingerprint" }, + }, + required: ["remoteUser", "remotePassword"], + }, + ], + }, + ControllerPlanResponse: { + type: "object", + properties: { + ok: { type: "boolean", example: true }, + controller: { + type: "object", + additionalProperties: true, + }, + env: { type: "string" }, + serviceUnit: { type: "string" }, + commands: { + type: "object", + properties: { + ssh: { type: "string" }, + localBootstrap: { type: "string" }, + start: { type: "string" }, + terminal: { type: "string" }, + }, + required: ["ssh", "localBootstrap", "start", "terminal"], + }, + checks: { + type: "array", + items: { type: "string" }, + }, + }, + required: ["ok", "controller", "env", "serviceUnit", "commands", "checks"], + }, + ControllerDeployResponse: { + allOf: [ + { $ref: "#/components/schemas/ControllerPlanResponse" }, + { + type: "object", + properties: { + hostKeySha256: { type: ["string", "null"] }, + stdout: { type: "string" }, + stderr: { type: "string" }, + note: { type: "string" }, + }, + required: ["hostKeySha256", "stdout", "stderr", "note"], + }, + ], + }, + ControllerRegistryRequest: { + oneOf: [ + { + type: "object", + properties: { + action: { type: "string", const: "rename" }, + nodeId: { type: "string" }, + name: { type: "string" }, + }, + required: ["action", "nodeId", "name"], + }, + { + type: "object", + properties: { + action: { type: "string", const: "upsert" }, + id: { type: "string" }, + name: { type: "string" }, + host: { type: "string" }, + url: { type: "string", format: "uri" }, + role: { type: "string", enum: ["local", "controller-node"] }, + }, + required: ["host", "url"], + }, + ], + }, + }, + }, + } +} diff --git a/app/swagger/page.tsx b/app/swagger/page.tsx new file mode 100644 index 0000000..affa689 --- /dev/null +++ b/app/swagger/page.tsx @@ -0,0 +1,114 @@ +import Link from "next/link" +import { buildOpenApiSpec } from "@/app/lib/openapiSpec" + +type OpenApiSpec = ReturnType + +function methodClass(method: string) { + const normalized = method.toLowerCase() + if (normalized === "get") return "border-blue-500/40 bg-blue-500/10 text-blue-300" + if (normalized === "post") return "border-[var(--nvidia-green)]/50 bg-[var(--nvidia-green)]/10 text-[var(--nvidia-green)]" + return "border-[var(--border-subtle)] bg-[var(--background-tertiary)] text-[var(--foreground-dim)]" +} + +function operationRows(spec: OpenApiSpec) { + return Object.entries(spec.paths).flatMap(([path, methods]) => + Object.entries(methods).map(([method, operation]) => ({ + path, + method, + operation, + })), + ) +} + +export default function SwaggerPage() { + const spec = buildOpenApiSpec() + const rows = operationRows(spec) + + return ( +
+
+
+
+
+

OpenAPI 3.1

+

Swagger

+

+ Controller-node API reference for generating launch kits, autodeploying remote nodes, and managing friendly names. +

+
+
+ + Dashboard + + + OpenAPI JSON + +
+
+
+ +
+
+

Title

+

{spec.info.title}

+
+
+

Version

+

{spec.info.version}

+
+
+

Auth

+

session cookie

+
+
+ +
+
+

Endpoints

+

Expandable operations generated from the local OpenAPI spec.

+
+
+ {rows.map(({ path, method, operation }) => ( +
+ + + + {method} + + {path} + + {operation.summary} + +
+

{operation.description || operation.summary}

+
+
+

Operation

+
{JSON.stringify(operation, null, 2)}
+
+
+

Curl

+
{`${method.toUpperCase()} ${path}\nContent-Type: application/json\nCookie: ${spec.components.securitySchemes.sessionCookie.name}=...`}
+
+
+
+
+ ))} +
+
+ +
+

Schemas

+
+ {Object.entries(spec.components.schemas).map(([name, schema]) => ( +
+ {name} +
{JSON.stringify(schema, null, 2)}
+
+ ))} +
+
+
+
+ ) +} diff --git a/next.config.mjs b/next.config.mjs index fb438d1..a176c57 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -1,4 +1,6 @@ /** @type {import('next').NextConfig} */ -const nextConfig = {} +const nextConfig = { + serverExternalPackages: ["ssh2"], +} -export default nextConfig \ No newline at end of file +export default nextConfig diff --git a/package-lock.json b/package-lock.json index 61b85ef..889a6e6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -15,6 +15,7 @@ "react": "^18.3.1", "react-dom": "^18.3.1", "react-use": "^17.5.0", + "ssh2": "^1.17.0", "ws": "^8.20.0", "xterm": "^5.3.0", "xterm-addon-fit": "^0.8.0", @@ -25,6 +26,7 @@ "@types/node": "^20.16.13", "@types/react": "^18.3.11", "@types/react-dom": "^18.3.1", + "@types/ssh2": "^1.15.5", "autoprefixer": "^10.4.20", "eslint": "^8.57.1", "eslint-config-next": "^15.5.15", @@ -1040,6 +1042,33 @@ "@types/react": "^18.0.0" } }, + "node_modules/@types/ssh2": { + "version": "1.15.5", + "resolved": "https://registry.npmjs.org/@types/ssh2/-/ssh2-1.15.5.tgz", + "integrity": "sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "^18.11.18" + } + }, + "node_modules/@types/ssh2/node_modules/@types/node": { + "version": "18.19.130", + "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz", + "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~5.26.4" + } + }, + "node_modules/@types/ssh2/node_modules/undici-types": { + "version": "5.26.5", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz", + "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==", + "dev": true, + "license": "MIT" + }, "node_modules/@typescript-eslint/eslint-plugin": { "version": "8.58.0", "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.58.0.tgz", @@ -1711,6 +1740,15 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/asn1": { + "version": "0.2.6", + "resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz", + "integrity": "sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==", + "license": "MIT", + "dependencies": { + "safer-buffer": "~2.1.0" + } + }, "node_modules/ast-types-flow": { "version": "0.0.8", "resolved": "https://registry.npmjs.org/ast-types-flow/-/ast-types-flow-0.0.8.tgz", @@ -1838,6 +1876,15 @@ "node": ">=6.0.0" } }, + "node_modules/bcrypt-pbkdf": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz", + "integrity": "sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==", + "license": "BSD-3-Clause", + "dependencies": { + "tweetnacl": "^0.14.3" + } + }, "node_modules/binary-extensions": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz", @@ -1933,6 +1980,15 @@ "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" } }, + "node_modules/buildcheck": { + "version": "0.0.7", + "resolved": "https://registry.npmjs.org/buildcheck/-/buildcheck-0.0.7.tgz", + "integrity": "sha512-lHblz4ahamxpTmnsk+MNTRWsjYKv965MwOrSJyeD588rR3Jcu7swE+0wN5F+PbL5cjgu/9ObkhfzEPuofEMwLA==", + "optional": true, + "engines": { + "node": ">=10.0.0" + } + }, "node_modules/bytes": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", @@ -2206,6 +2262,20 @@ "url": "https://opencollective.com/express" } }, + "node_modules/cpu-features": { + "version": "0.0.10", + "resolved": "https://registry.npmjs.org/cpu-features/-/cpu-features-0.0.10.tgz", + "integrity": "sha512-9IkYqtX3YHPCzoVg1Py+o9057a3i0fp7S530UWokCSaFVTc7CwXPRiOjRjBQQ18ZCNafx78YfnG+HALxtVmOGA==", + "hasInstallScript": true, + "optional": true, + "dependencies": { + "buildcheck": "~0.0.6", + "nan": "^2.19.0" + }, + "engines": { + "node": ">=10.0.0" + } + }, "node_modules/cross-spawn": { "version": "7.0.6", "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", @@ -4707,6 +4777,13 @@ "thenify-all": "^1.0.0" } }, + "node_modules/nan": { + "version": "2.26.2", + "resolved": "https://registry.npmjs.org/nan/-/nan-2.26.2.tgz", + "integrity": "sha512-0tTvBTYkt3tdGw22nrAy50x7gpbGCCFH3AFcyS5WiUu7Eu4vWlri1woE6qHBSfy11vksDqkiwjOnlR7WV8G1Hw==", + "license": "MIT", + "optional": true + }, "node_modules/nano-css": { "version": "5.6.2", "resolved": "https://registry.npmjs.org/nano-css/-/nano-css-5.6.2.tgz", @@ -5241,7 +5318,6 @@ "version": "8.5.10", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz", "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==", - "dev": true, "funding": [ { "type": "opencollective", @@ -6212,6 +6288,23 @@ "node": ">=0.10.0" } }, + "node_modules/ssh2": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/ssh2/-/ssh2-1.17.0.tgz", + "integrity": "sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==", + "hasInstallScript": true, + "dependencies": { + "asn1": "^0.2.6", + "bcrypt-pbkdf": "^1.0.2" + }, + "engines": { + "node": ">=10.16.0" + }, + "optionalDependencies": { + "cpu-features": "~0.0.10", + "nan": "^2.23.0" + } + }, "node_modules/stable-hash": { "version": "0.0.5", "resolved": "https://registry.npmjs.org/stable-hash/-/stable-hash-0.0.5.tgz", @@ -6733,6 +6826,12 @@ "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", "license": "0BSD" }, + "node_modules/tweetnacl": { + "version": "0.14.5", + "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz", + "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==", + "license": "Unlicense" + }, "node_modules/type-check": { "version": "0.4.0", "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", diff --git a/package.json b/package.json index a0d0374..37ea0c2 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ "react": "^18.3.1", "react-dom": "^18.3.1", "react-use": "^17.5.0", + "ssh2": "^1.17.0", "ws": "^8.20.0", "xterm": "^5.3.0", "xterm-addon-fit": "^0.8.0", @@ -28,6 +29,7 @@ "@types/node": "^20.16.13", "@types/react": "^18.3.11", "@types/react-dom": "^18.3.1", + "@types/ssh2": "^1.15.5", "autoprefixer": "^10.4.20", "eslint": "^8.57.1", "eslint-config-next": "^15.5.15", diff --git a/tests/controller-node-wizard-check.mjs b/tests/controller-node-wizard-check.mjs new file mode 100644 index 0000000..0857eed --- /dev/null +++ b/tests/controller-node-wizard-check.mjs @@ -0,0 +1,56 @@ +import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' +import path from 'node:path' + +const root = process.cwd() + +const [wizardSource, sidebarSource, planRouteSource, deployRouteSource, registryRouteSource, planLibSource, registryLibSource] = await Promise.all([ + readFile(path.join(root, 'app/components/WizardPanel.tsx'), 'utf8'), + readFile(path.join(root, 'app/components/Sidebar.tsx'), 'utf8'), + readFile(path.join(root, 'app/api/controller-node/plan/route.ts'), 'utf8'), + readFile(path.join(root, 'app/api/controller-node/deploy/route.ts'), 'utf8'), + readFile(path.join(root, 'app/api/controller-node/registry/route.ts'), 'utf8'), + readFile(path.join(root, 'app/lib/controllerNodePlan.ts'), 'utf8'), + readFile(path.join(root, 'app/lib/controllerNodeRegistry.ts'), 'utf8'), +]) + +assert.match(wizardSource, /Spawn a Controller Node/, 'wizard must expose a controller-node workflow') +assert.match(wizardSource, /Generate Launch Kit/, 'controller workflow must generate a launch kit') +assert.match(wizardSource, /Manual Deploy/, 'wizard must expose manual deploy mode') +assert.match(wizardSource, /Autodeploy/, 'wizard must expose autodeploy mode') +assert.match(wizardSource, /\/api\/controller-node\/plan/, 'wizard must call the controller-node plan API') +assert.match(wizardSource, /\/api\/controller-node\/deploy/, 'wizard must call the controller-node deploy API') +assert.match(wizardSource, /SSH Password/, 'autodeploy must collect a password for one-time SSH use') +assert.match(wizardSource, /Allow sudo/, 'autodeploy must require explicit sudo permission') +assert.match(wizardSource, /Trust first host key/, 'autodeploy must expose explicit host-key trust') +assert.match(wizardSource, /OPENCLAW_DASHBOARD_URL|OpenClaw Dashboard URL/, 'wizard must collect the remote OpenClaw upstream') +assert.match(wizardSource, /OPENSHELL_GATEWAY|OpenShell Gateway/, 'wizard must collect the remote OpenShell gateway context') +assert.match(wizardSource, /Controller Env/, 'wizard must expose the generated controller environment') +assert.match(wizardSource, /Readiness Checks/, 'wizard must show remote readiness checks') +assert.match(wizardSource, /aria-expanded=\{controllerWizardOpen\}/, 'controller node wizard must render as an accordion') +assert.match(wizardSource, /aria-expanded=\{cloneWizardOpen\}/, 'clone wizard must render as an accordion') + +assert.match(planRouteSource, /buildControllerNodePlan/, 'plan API must use shared controller plan builder') +assert.match(planRouteSource, /upsertControllerNode/, 'plan API must register generated controller nodes') +assert.match(planLibSource, /OPENCLAW_INSTANCE_REGISTRY_JSON/, 'plan builder must configure the OpenClaw instance registry') +assert.match(planLibSource, /CONTROLLER_NODE_PARENT_URL/, 'plan builder must configure parent controller connectivity') +assert.match(planLibSource, /CONTROLLER_NODE_SHARED_SECRET/, 'plan builder must generate a node shared secret') +assert.match(planLibSource, /TERMINAL_SERVER_AUTOSTART=true/, 'plan builder must enable the terminal sidecar for controller nodes') +assert.match(planLibSource, /openshell-controller-node\.service/, 'plan builder must include a production service unit when systemd is available') +assert.match(planLibSource, /npm run build/, 'plan builder must produce a complete install/build command') +assert.match(planLibSource, /OpenShell CLI is installed/, 'plan builder must return operational readiness checks') +assert.match(deployRouteSource, /ssh2/, 'deploy API must use server-side SSH for autodeploy') +assert.match(deployRouteSource, /remotePassword/, 'deploy API must accept one-time remote password input') +assert.match(deployRouteSource, /sudo -S/, 'deploy API must support explicit sudo elevation') +assert.match(deployRouteSource, /expectedHostKeySha256/, 'deploy API must support host-key fingerprint verification') +assert.match(deployRouteSource, /acceptUnknownHostKey/, 'deploy API must require explicit trust-on-first-deploy') +assert.match(sidebarSource, /OpenShell Control/, 'sidebar must keep the OpenShell Control header') +assert.match(sidebarSource, /\/api\/controller-node\/registry/, 'sidebar must load managed controller nodes') +assert.match(sidebarSource, /Friendly Name/, 'sidebar must allow friendly names for controller nodes') +assert.match(sidebarSource, /Managed Node/, 'sidebar must expose a managed-node selector') +assert.match(registryRouteSource, /listControllerNodes/, 'registry API must expose controller nodes') +assert.match(registryRouteSource, /renameControllerNode/, 'registry API must support friendly-name updates') +assert.match(registryLibSource, /OPENSHELL_CONTROLLER_NODES_JSON|OPENCLAW_INSTANCE_REGISTRY_JSON/, 'registry must detect configured remote controller nodes') +assert.doesNotMatch(`${planRouteSource}\n${deployRouteSource}\n${planLibSource}\n${registryLibSource}`, /\/home\/nvidia|\/Users\/markmckeen/, 'controller node code must not bake in developer machine paths') + +console.log('controller-node-wizard-check: PASS controller node wizard assertions') diff --git a/tests/swagger-openapi-check.mjs b/tests/swagger-openapi-check.mjs new file mode 100644 index 0000000..8e72ba7 --- /dev/null +++ b/tests/swagger-openapi-check.mjs @@ -0,0 +1,30 @@ +import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' +import path from 'node:path' + +const root = process.cwd() + +const [specSource, routeSource, pageSource, sidebarSource, helpSource] = await Promise.all([ + readFile(path.join(root, 'app/lib/openapiSpec.ts'), 'utf8'), + readFile(path.join(root, 'app/api/openapi/route.ts'), 'utf8'), + readFile(path.join(root, 'app/swagger/page.tsx'), 'utf8'), + readFile(path.join(root, 'app/components/Sidebar.tsx'), 'utf8'), + readFile(path.join(root, 'app/components/HelpPanel.tsx'), 'utf8'), +]) + +assert.match(specSource, /openapi:\s*"3\.1\.0"/, 'OpenAPI spec must declare version 3.1.0') +assert.match(specSource, /\/api\/controller-node\/plan/, 'spec must document controller plan endpoint') +assert.match(specSource, /\/api\/controller-node\/deploy/, 'spec must document controller deploy endpoint') +assert.match(specSource, /\/api\/controller-node\/registry/, 'spec must document controller registry endpoint') +assert.match(specSource, /ControllerDeployRequest/, 'spec must include autodeploy request schema') +assert.match(specSource, /sessionCookie/, 'spec must document session cookie auth') +assert.match(routeSource, /buildOpenApiSpec/, 'OpenAPI API route must return generated spec') +assert.match(pageSource, /OpenAPI JSON/, 'Swagger page must link to the JSON spec') +assert.match(pageSource, /Endpoints/, 'Swagger page must render endpoint docs') +assert.match(pageSource, /Schemas/, 'Swagger page must render schema docs') +assert.doesNotMatch(sidebarSource, /href="\/swagger"/, 'Swagger must not be a top-level sidebar item') +assert.match(helpSource, /API Reference/, 'Help must expose an API reference section') +assert.match(helpSource, /href="\/swagger"/, 'Help must link to the Swagger page') +assert.match(helpSource, /target="_blank"/, 'Help must open Swagger in a separate page') + +console.log('swagger-openapi-check: PASS swagger/openapi assertions')