Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
// Integration tests for /api/v1/sys/update — the route that REPLACES THE CODE THE
// WHOLE COCKPIT RUNS. It shipped with no test at all, which is the wrong end of the
// risk scale to leave uncovered: a regression here does not render a panel wrong,
// it pulls and rebuilds the running deployment.
//
// The route's own job is thin and entirely about refusing: auth, then the boolean,
// then handing off. lib/host/self-update is stubbed so these exercise the WIRING —
// that a signed-out caller gets nothing, that a refusal is a 4xx carrying its
// sentence, and that both outcomes reach the audit trail (this action is the one an
// operator would most want to find in ~/.mso/audit.log afterwards).
import { beforeEach, describe, expect, it, vi } from "vitest";
const authed = { current: true };
vi.mock("@/lib/agent/server", () => ({
verifyAuth: vi.fn(async () => authed.current),
}));
const getStatus = vi.fn();
const startUpdate = vi.fn();
vi.mock("@/lib/host/self-update", () => ({
getUpdateStatus: (...args: unknown[]) => getStatus(...args),
startUpdate: (...args: unknown[]) => startUpdate(...args),
}));
const auditMock = vi.fn();
const limited = vi.hoisted(() => ({ value: false }));
vi.mock("@/lib/host/limits-api", () => ({ rateLimited: () => limited.value }));
vi.mock("@/lib/host/audit-api", () => ({
audit: (...args: unknown[]) => auditMock(...args),
}));
const { GET, POST } = await import("./route");
const { HostError } = await import("@/lib/host/host-error");
const status = (over: Record<string, unknown> = {}) => ({
supported: true,
reason: null,
current: "abc1234",
currentSubject: "feat: x",
buildSha: "abc1234",
pendingBuild: false,
ahead: 0,
behind: 2,
commits: [],
dirty: false,
running: false,
remoteChecked: true,
log: "",
...over,
});
const get = (url = "http://localhost/api/v1/sys/update") => new Request(url);
const post = (body: unknown) =>
new Request("http://localhost/api/v1/sys/update", {
method: "POST",
body: JSON.stringify(body),
headers: { "content-type": "application/json" },
});
beforeEach(() => {
authed.current = true;
limited.value = false;
vi.stubEnv("OS_PUBLIC_ORIGIN", "http://localhost");
getStatus.mockReset().mockResolvedValue(status());
startUpdate.mockReset().mockResolvedValue(status({ running: true }));
auditMock.mockReset();
});
describe("/api/v1/sys/update", () => {
it("tells a signed-out caller nothing, on either verb", async () => {
authed.current = false;
expect((await GET(get())).status).toBe(401);
expect((await POST(post({}))).status).toBe(401);
// Not merely unauthorised — it must not have looked at the host either.
expect(getStatus).not.toHaveBeenCalled();
expect(startUpdate).not.toHaveBeenCalled();
});
it("never fetches the remote on GET, even with a legacy check flag", async () => {
await GET(get());
expect(getStatus).toHaveBeenLastCalledWith(false);
await GET(get("http://localhost/api/v1/sys/update?check=1"));
expect(getStatus).toHaveBeenLastCalledWith(false);
// `?check=0` is what the panel polls with WHILE an update runs — a git fetch
// every 3s during a build is pure noise.
await GET(get("http://localhost/api/v1/sys/update?check=0"));
expect(getStatus).toHaveBeenLastCalledWith(false);
});
it("requires an explicit same-origin POST and limits remote refreshes", async () => {
for (const origin of [null, "http://evil.test"]) {
const req = post({ action: "check" }); if (origin) req.headers.set("origin", origin);
expect((await POST(req)).status).toBe(403);
}
expect(getStatus).not.toHaveBeenCalled(); expect(startUpdate).not.toHaveBeenCalled();
const request = () => { const req = post({ action: "check" }); req.headers.set("origin", "http://localhost"); return req; };
expect((await POST(request())).status).toBe(200);
expect(getStatus).toHaveBeenCalledWith(true); expect(startUpdate).not.toHaveBeenCalled();
expect(auditMock).toHaveBeenCalledWith(expect.objectContaining({ action: "sys.update", target: "check", ok: true }));
getStatus.mockClear(); limited.value = true;
expect((await POST(request())).status).toBe(429); expect(getStatus).not.toHaveBeenCalled();
});
it("passes rebuildOnly through only when it is exactly true", async () => {
await POST(post({ rebuildOnly: true }));
expect(startUpdate).toHaveBeenLastCalledWith(true, undefined);
// A truthy string from a hand-rolled client must not silently mean "rebuild".
await POST(post({ rebuildOnly: "yes" }));
expect(startUpdate).toHaveBeenLastCalledWith(false, undefined);
await POST(post({}));
expect(startUpdate).toHaveBeenLastCalledWith(false, undefined);
});
it("accepts only the channel enum and ignores anything ref-shaped", async () => {
await POST(post({ channel: "main" }));
expect(startUpdate).toHaveBeenLastCalledWith(false, "main");
await POST(post({ channel: "stable" }));
expect(startUpdate).toHaveBeenLastCalledWith(false, "stable");
// A ref, a tag or a command is not a channel: fall back to the stored pref.
for (const channel of ["origin/main", "v1.2.3", "main --force", "--rebuild-only", 3, null]) {
await POST(post({ channel }));
expect(startUpdate).toHaveBeenLastCalledWith(false, undefined);
}
});
it("surfaces a refusal as its sentence, not as a 500", async () => {
startUpdate.mockRejectedValue(new HostError("already up to date"));
const res = await POST(post({}));
expect(res.status).toBe(400);
expect((await res.json()).error).toContain("already up to date");
});
it("audits both the start and the refusal", async () => {
await POST(post({}));
expect(auditMock).toHaveBeenCalledWith(expect.objectContaining({ action: "sys.update", ok: true }));
auditMock.mockReset();
startUpdate.mockRejectedValue(new HostError("an update is already running"));
await POST(post({}));
// A failed attempt is the more interesting line in the log, not the less.
expect(auditMock).toHaveBeenCalledWith(expect.objectContaining({ action: "sys.update", ok: false }));
});
it("does not audit a read", async () => {
await GET(get());
expect(auditMock).not.toHaveBeenCalled();
});
});