A local-first multi-agent app development platform, built on PenguinHarness
import { afterEach, describe, expect, it, vi } from "vitest";
import path from "node:path";
import { Command } from "commander";
import { DEFAULT_SERVER_PORT } from "@adelie/core";
import {
DEFAULT_HOST,
DEFAULT_PORT,
browserCommand,
appPagePath,
browserUrl,
cliEntryFor,
describeReadinessFailure,
registerServeCommands,
resolvePort,
supervisorDecision,
waitForReady,
} from "../src/commands/serve.js";
import { getMessages } from "../src/i18n.js";
describe("resolvePort (option > env var > default 4000)", () => {
it("derives DEFAULT_PORT from core's DEFAULT_SERVER_PORT", () => {
expect(DEFAULT_PORT).toBe(DEFAULT_SERVER_PORT);
});
it("uses the default 4000 when neither is given", () => {
expect(DEFAULT_PORT).toBe(4000);
expect(resolvePort(undefined, undefined)).toBe(4000);
expect(resolvePort(undefined, "")).toBe(4000); // an empty string counts as unset
});
it("takes the env var when only the env var is set", () => {
expect(resolvePort(undefined, "8080")).toBe(8080);
});
it("the option beats the env var", () => {
expect(resolvePort("9000", "8080")).toBe(9000);
});
it("throws on invalid values (non-integer / out of range)", () => {
expect(() => resolvePort("abc", undefined)).toThrow(/abc/);
expect(() => resolvePort("3.14", undefined)).toThrow();
expect(() => resolvePort("-1", undefined)).toThrow();
expect(() => resolvePort("65536", undefined)).toThrow();
expect(() => resolvePort(undefined, "not-a-port")).toThrow(/not-a-port/);
});
});
describe("browserCommand (picks the open command per platform)", () => {
const url = "http://127.0.0.1:7364/";
it("darwin → open", () => {
expect(browserCommand("darwin", url)).toEqual({ command: "open", args: [url] });
});
it("win32 -> cmd /c start (empty title placeholder before the URL)", () => {
expect(browserCommand("win32", url)).toEqual({
command: "cmd",
args: ["/c", "start", "", url],
});
});
it("other platforms (linux etc.) -> xdg-open", () => {
expect(browserCommand("linux", url)).toEqual({ command: "xdg-open", args: [url] });
expect(browserCommand("freebsd", url)).toEqual({ command: "xdg-open", args: [url] });
});
});
describe("browserUrl (wildcard listen addresses map to 127.0.0.1)", () => {
it("a regular host is joined as-is", () => {
expect(browserUrl(DEFAULT_HOST, 7364)).toBe("http://127.0.0.1:7364/");
expect(browserUrl("192.168.1.2", 8080)).toBe("http://192.168.1.2:8080/");
});
it("the browser URL uses 127.0.0.1 for 0.0.0.0 / ::", () => {
expect(browserUrl("0.0.0.0", 7364)).toBe("http://127.0.0.1:7364/");
expect(browserUrl("::", 7364)).toBe("http://127.0.0.1:7364/");
});
});
describe("registerServeCommands (command registration)", () => {
it("registers the server and web top-level commands; web defaults to open=true (--no-open turns it off)", () => {
const program = new Command();
registerServeCommands(program, getMessages("en"));
const names = program.commands.map((c) => c.name());
expect(names).toContain("server");
expect(names).toContain("web");
const web = program.commands.find((c) => c.name() === "web")!;
expect(web.opts().open).toBe(true);
});
});
describe("cliEntryFor (the entry advertised for the web self-update)", () => {
it("advertises only entries plain node can re-run (.js/.mjs/.cjs), resolved absolute", () => {
// Expectations go through path.resolve too: on win32 an absolute POSIX-style input
// gains a drive prefix and backslashes, and the contract is "resolved", not a literal.
expect(cliEntryFor("/opt/penguin/lib/dist/index.js")).toBe(
path.resolve("/opt/penguin/lib/dist/index.js"),
);
expect(cliEntryFor("/x/cli.MJS")).toBe(path.resolve("/x/cli.MJS"));
expect(cliEntryFor("/x/cli.cjs")).toBe(path.resolve("/x/cli.cjs"));
});
it("refuses a tsx dev entry and a missing argv[1] (the endpoint then reports unsupported)", () => {
expect(cliEntryFor("/repo/packages/cli/src/index.ts")).toBeNull();
expect(cliEntryFor(undefined)).toBeNull();
expect(cliEntryFor("")).toBeNull();
});
});
describe("supervisorDecision (the service child's exit → respawn or exit)", () => {
it("relaunches the service only on the restart code, and only while not stopping", () => {
expect(supervisorDecision({ code: 75, signal: null }, false)).toEqual({ action: "respawn" });
// The supervisor was told to stop (Ctrl+C reached it too): the child's last word is moot.
expect(supervisorDecision({ code: 75, signal: null }, true)).toEqual({
action: "exit",
code: 75,
});
});
it("passes every other exit through, and reads a signal death as failure", () => {
expect(supervisorDecision({ code: 0, signal: null }, false)).toEqual({
action: "exit",
code: 0,
});
expect(supervisorDecision({ code: 3, signal: null }, false)).toEqual({
action: "exit",
code: 3,
});
expect(supervisorDecision({ code: null, signal: "SIGKILL" }, false)).toEqual({
action: "exit",
code: 1,
});
expect(supervisorDecision({ code: null, signal: null }, true)).toEqual({
action: "exit",
code: 0,
});
});
});
describe("readiness probe diagnostics", () => {
afterEach(() => {
vi.restoreAllMocks();
});
it("reports a successful HTTP response as ready regardless of its status", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(null, { status: 503 }));
await expect(waitForReady("http://127.0.0.1:7364/", 0, 0)).resolves.toEqual({
ready: true,
});
});
it("keeps polling after failed probes and reports ready once a response arrives", async () => {
vi.spyOn(globalThis, "fetch")
.mockRejectedValueOnce(new TypeError("fetch failed"))
.mockResolvedValue(new Response(null, { status: 200 }));
await expect(waitForReady("http://127.0.0.1:7364/", 5_000, 0)).resolves.toEqual({
ready: true,
});
});
it("reports ready for a probe whose body was left errored, without a stray rejection", async () => {
// The 1s AbortSignal on each probe produces exactly this: headers arrived, then the
// connection died (or the timeout fired) before anyone read the body, so the stream is
// errored and its cancel() rejects. A CLI with no unhandled-rejection handler would die.
const errored = new Response(
new ReadableStream<Uint8Array>({
start(controller) {
controller.error(new Error("The operation was aborted due to timeout"));
},
}),
{ status: 200 },
);
vi.spyOn(globalThis, "fetch").mockResolvedValue(errored);
const seen: unknown[] = [];
const onRejection = (reason: unknown) => seen.push(reason);
process.on("unhandledRejection", onRejection);
try {
await expect(waitForReady("http://127.0.0.1:7364/", 0, 0)).resolves.toEqual({ ready: true });
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
expect(seen).toEqual([]);
} finally {
process.off("unhandledRejection", onRejection);
}
});
it("retains the nested undici error from the last failed probe", async () => {
const cause = Object.assign(new Error("Connect Timeout Error"), {
code: "UND_ERR_CONNECT_TIMEOUT",
});
vi.spyOn(globalThis, "fetch").mockRejectedValue(
Object.assign(new TypeError("fetch failed"), { cause }),
);
await expect(waitForReady("http://127.0.0.1:7364/", 0, 0)).resolves.toEqual({
ready: false,
failure: {
kind: "timeout",
detail: "UND_ERR_CONNECT_TIMEOUT: Connect Timeout Error",
},
});
});
it.each([
["ECONNREFUSED", "refused"],
["ECONNRESET", "reset"],
["EACCES", "permission"],
["ENOTFOUND", "dns"],
] as const)("classifies %s failures as %s", (code, kind) => {
expect(describeReadinessFailure(Object.assign(new Error("probe failed"), { code }))).toEqual({
kind,
detail: `${code}: probe failed`,
});
});
it("classifies the probe's own 1s abort (DOMException TimeoutError) as a timeout", () => {
expect(
describeReadinessFailure(
new DOMException("The operation was aborted due to timeout", "TimeoutError"),
),
).toEqual({
kind: "timeout",
detail: "TimeoutError: The operation was aborted due to timeout",
});
});
it("digs the connect error out of an empty-message AggregateError (multi-address host)", () => {
const aggregate = Object.assign(
new AggregateError([
Object.assign(new Error("connect ECONNREFUSED ::1:7364"), { code: "ECONNREFUSED" }),
Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:7364"), { code: "ECONNREFUSED" }),
]),
{ code: "ECONNREFUSED" },
);
const error = Object.assign(new TypeError("fetch failed"), { cause: aggregate });
expect(describeReadinessFailure(error)).toEqual({
kind: "refused",
detail: "ECONNREFUSED: connect ECONNREFUSED ::1:7364",
});
});
it("includes actionable localized firewall guidance for connection timeouts", () => {
const detail = "UND_ERR_CONNECT_TIMEOUT: Connect Timeout Error";
const url = "http://127.0.0.1:7364/";
for (const lang of ["en", "zh"] as const) {
const timeout = getMessages(lang).webProbeFailed(url, detail, "timeout", 7364);
// Actionable means naming the port the user has to let through, not just reporting a
// timeout; the probe error stays visible either way.
expect(timeout, lang).toContain("7364");
expect(timeout, lang).toContain(detail);
// The kind picks the hint: a timeout must not read like a refused connection.
expect(timeout, lang).not.toBe(
getMessages(lang).webProbeFailed(url, detail, "refused", 7364),
);
}
});
});
describe("appPagePath (--app <project>/<agent>/<workflow>[/<tab>])", () => {
it("maps the spec to the Web App's full-page route, segments encoded", () => {
expect(appPagePath("default_project/default_agent/todo")).toBe(
"app/default_project/default_agent/todo",
);
expect(appPagePath("p 1/a/w")).toBe("app/p%201/a/w");
// A workflow contributes its tabs; a fourth segment names one by its key.
expect(appPagePath("p/a/todo/stats")).toBe("app/p/a/todo/stats");
});
it("refuses anything but three or four non-empty segments", () => {
for (const bad of ["todo", "p/a", "p/a/w/x/y", "p//w", "/a/w", "p/a/w/"]) {
expect(() => appPagePath(bad)).toThrow(/Invalid --app/);
}
});
});