A local-first multi-agent app development platform, built on PenguinHarness
fix(cli): report web readiness probe failures (#169)
Laodouuue05dea536b4b
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.tsindex 30cf3332..b9288bae 100644--- a/packages/cli/src/commands/serve.ts+++ b/packages/cli/src/commands/serve.ts@@ -18,7 +18,16 @@ import { spawn } from "node:child_process";import path from "node:path";import { DEFAULT_SERVER_PORT } from "@prismshadow/penguin-core";import type { Command } from "commander";-import type { Messages } from "../i18n.js";+import type { Messages, WebProbeFailureKind } from "../i18n.js";++/** Why the readiness poll gave up: failure class plus a one-line diagnostic from the last probe. */+export interface ReadinessFailure {+ kind: WebProbeFailureKind;+ detail: string;+}++/** Result of `waitForReady`: ready, or timed out with the retained last probe failure. */+export type ReadinessResult = { ready: true } | { ready: false; failure: ReadinessFailure };/** Default service port — core's DEFAULT_SERVER_PORT (7364), the single source of truth. */export const DEFAULT_PORT = DEFAULT_SERVER_PORT;@@ -96,9 +105,103 @@ async function startServer(opts: {return { host, port };}-/** Polls the service root path until it responds (any HTTP response counts as ready); keeps waiting on connection failure, returns false on timeout. */-async function waitForReady(url: string, timeoutMs = 15_000, intervalMs = 300): Promise<boolean> {+function errorProperty(+ value: unknown,+ property: "cause" | "code" | "errors" | "message" | "name",+): unknown {+ if ((typeof value !== "object" && typeof value !== "function") || value === null) {+ return undefined;+ }+ return (value as Record<string, unknown>)[property];+}++/**+ * Turns Node/undici's nested `fetch failed` errors into a stable one-line diagnostic.+ * The useful code usually lives on `error.cause` rather than the top-level TypeError.+ * Exported for unit tests.+ */+export function describeReadinessFailure(error: unknown): ReadinessFailure {+ const chain: unknown[] = [];+ const seen = new Set<unknown>();+ let current: unknown = error;+ while (current !== undefined && current !== null && !seen.has(current)) {+ chain.push(current);+ seen.add(current);+ // Follow `cause` first; an AggregateError (e.g. localhost resolving to several+ // addresses, all refused) keeps the real connect errors in `errors` instead.+ const cause = errorProperty(current, "cause");+ if (cause !== undefined && cause !== null) {+ current = cause;+ continue;+ }+ const errors = errorProperty(current, "errors");+ current = Array.isArray(errors) ? errors[0] : undefined;+ }++ const code = chain+ .map((item) => errorProperty(item, "code"))+ .find((value): value is string => typeof value === "string" && value.length > 0);+ const selected = [...chain].reverse().find((item) => {+ const value = errorProperty(item, "message");+ // Skip empty messages: an AggregateError's own message is "" and would mask real text.+ return typeof value === "string" && value.length > 0;+ });+ const messageValue = selected === undefined ? undefined : errorProperty(selected, "message");+ const nameValue = selected === undefined ? undefined : errorProperty(selected, "name");+ const message =+ typeof messageValue === "string" && messageValue.length > 0+ ? messageValue+ : typeof error === "string"+ ? error+ : "Unknown readiness probe error";+ const name = typeof nameValue === "string" && nameValue !== "Error" ? nameValue : undefined;+ const detail =+ code !== undefined+ ? `${code}: ${message}`+ : name !== undefined+ ? `${name}: ${message}`+ : message;+ const signature = chain+ .flatMap((item) => [+ errorProperty(item, "code"),+ errorProperty(item, "name"),+ errorProperty(item, "message"),+ ])+ .filter((value): value is string => typeof value === "string")+ .join(" ")+ .toUpperCase();++ let kind: WebProbeFailureKind = "unknown";+ if (signature.includes("ECONNREFUSED")) kind = "refused";+ else if (+ signature.includes("ETIMEDOUT") ||+ signature.includes("TIMEOUT") ||+ signature.includes("ABORTERROR")+ ) {+ kind = "timeout";+ } else if (+ signature.includes("ECONNRESET") ||+ signature.includes("UND_ERR_SOCKET") ||+ signature.includes("EPIPE")+ ) {+ kind = "reset";+ } else if (signature.includes("EACCES") || signature.includes("EPERM")) {+ kind = "permission";+ } else if (signature.includes("ENOTFOUND") || signature.includes("EAI_AGAIN")) {+ kind = "dns";+ }++ return { kind, detail };+}++/** Polls the service root path until it responds (any HTTP response counts as ready); retains the last connection failure for diagnostics on timeout. Exported for unit tests. */+export async function waitForReady(+ url: string,+ timeoutMs = 15_000,+ intervalMs = 300,+): Promise<ReadinessResult> {const deadline = Date.now() + timeoutMs;+ let lastError: unknown;for (;;) {try {// Each probe is capped at 1s: if the port is held by a non-HTTP program, the@@ -109,11 +212,14 @@ async function waitForReady(url: string, timeoutMs = 15_000, intervalMs = 300):// so treat that 302 as ready rather than chasing it to a name that may resolve to ::1.const res = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(1000) });void res.body?.cancel();- return true;- } catch {- // The service isn't listening yet (or this probe timed out): keep polling.+ return { ready: true };+ } catch (error) {+ // The service isn't listening yet (or this probe timed out): retain the reason and keep polling.+ lastError = error;+ }+ if (Date.now() >= deadline) {+ return { ready: false, failure: describeReadinessFailure(lastError) };}- if (Date.now() >= deadline) return false;await new Promise((resolve) => setTimeout(resolve, intervalMs));}}@@ -149,9 +255,11 @@ export function registerServeCommands(program: Command, t: Messages): void {.action(async (opts: { port?: string; host?: string; open: boolean }) => {const { host, port } = await startServer(opts);const url = browserUrl(host, port);- const ready = await waitForReady(url);- if (!ready) {- process.stdout.write(`${t.webTimeout(url)}\n`);+ const readiness = await waitForReady(url);+ if (!readiness.ready) {+ process.stderr.write(+ `${t.webProbeFailed(url, readiness.failure.detail, readiness.failure.kind, port)}\n`,+ );return;}process.stdout.write(`${t.webReady(url)}\n`);diff --git a/packages/cli/src/i18n.ts b/packages/cli/src/i18n.tsindex 9b6edcdf..092bd078 100644--- a/packages/cli/src/i18n.ts+++ b/packages/cli/src/i18n.ts@@ -9,6 +9,10 @@/** UI language. */export type Language = "en" | "zh";+/** Readiness probe failure classes; selects which hint `webProbeFailed` appends. */+export type WebProbeFailureKind =+ "timeout" | "refused" | "reset" | "permission" | "dns" | "unknown";+/** Resolve the language from the env var; `zh` matches exactly, everything else falls back to English (see comment #2). */export function resolveLanguage(): Language {const v = (process.env.PENGUIN_LANG ?? "").trim().toLowerCase();@@ -219,8 +223,8 @@ export interface Messages {vaultListEmpty(): string;/** URL prompt once the `penguin web` service is ready. */webReady(url: string): string;- /** Manual-open prompt after the `penguin web` ready-poll times out (15s). */- webTimeout(url: string): string;+ /** Diagnostic shown after the `penguin web` ready-poll times out (15s). */+ webProbeFailed(url: string, detail: string, kind: WebProbeFailureKind, port: number): string;}function headerEn(@@ -451,7 +455,22 @@ const en: Messages = {vaultListTitle: () => "Vault environment variables (values masked):",vaultListEmpty: () => "The vault is empty. Add one with `penguin config vault set`.",webReady: (url) => `Web UI ready: ${url}`,- webTimeout: (url) => `Server is not responding yet; open ${url} manually once it is ready.`,+ webProbeFailed: (url, detail, kind, port) => {+ const hint = {+ timeout:+ `The connection timed out. Check whether a firewall or security application is blocking it. ` ++ `Allow PenguinHarness to communicate on local port ${port}.`,+ refused:+ "Nothing accepted the connection. Check whether the server exited or HOST/PORT points somewhere else.",+ reset:+ "The connection closed before an HTTP response. Check local security software and retry.",+ permission:+ "The operating system denied the connection. Check firewall or security policy permissions.",+ dns: "The host name could not be resolved. Check --host or HOST.",+ unknown: `Open ${url} manually after the server is ready.`,+ }[kind];+ return `Server readiness check failed for ${url}.\nLast probe error: ${detail}\n${hint}`;+ },};const zh: Messages = {@@ -645,7 +664,17 @@ const zh: Messages = {vaultListTitle: () => "vault 环境变量(值已掩码):",vaultListEmpty: () => "vault 为空。用 `penguin config vault set` 添加。",webReady: (url) => `Web 界面已就绪:${url}`,- webTimeout: (url) => `服务尚未就绪,请稍后手动打开 ${url}。`,+ webProbeFailed: (url, detail, kind, port) => {+ const hint = {+ timeout: `连接超时。请检查防火墙或安全软件是否拦截。请允许 PenguinHarness 在本机端口 ${port} 上通信。`,+ refused: "没有进程接受连接。请检查服务是否已经退出,或 HOST/PORT 是否指向了其他地址。",+ reset: "连接在收到 HTTP 响应前已关闭。请检查本机安全软件后重试。",+ permission: "操作系统拒绝了连接。请检查防火墙或安全策略权限。",+ dns: "无法解析主机名。请检查 --host 或 HOST。",+ unknown: `请在服务就绪后手动打开 ${url}。`,+ }[kind];+ return `服务探活失败:${url}\n最后一次探测错误:${detail}\n${hint}`;+ },};/** Get the message set for a language. */diff --git a/packages/cli/test/serve.test.ts b/packages/cli/test/serve.test.tsindex b67cb235..ebdf15eb 100644--- a/packages/cli/test/serve.test.ts+++ b/packages/cli/test/serve.test.ts@@ -1,4 +1,4 @@-import { describe, expect, it } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import path from "node:path";import { Command } from "commander";import { DEFAULT_SERVER_PORT } from "@prismshadow/penguin-core";@@ -8,8 +8,10 @@ import {browserCommand,browserUrl,cliEntryFor,+ describeReadinessFailure,registerServeCommands,resolvePort,+ waitForReady,} from "../src/commands/serve.js";import { getMessages } from "../src/i18n.js";@@ -93,3 +95,93 @@ describe("cliEntryFor (the entry advertised for the web self-update)", () => {expect(cliEntryFor("")).toBeNull();});});++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("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";+ expect(+ getMessages("en").webProbeFailed("http://127.0.0.1:7364/", detail, "timeout", 7364),+ ).toContain("Allow PenguinHarness to communicate on local port 7364");+ expect(+ getMessages("zh").webProbeFailed("http://127.0.0.1:7364/", detail, "timeout", 7364),+ ).toContain("请允许 PenguinHarness 在本机端口 7364 上通信");+ });+});