@syengup/friday-channel-next 0.1.26 → 0.1.28

package/dist/src/version.d.ts

@@ -0,0 +1,5 @@
+export declare const PLUGIN_VERSION: string;
+/** npm package name, used for the upgrade spec and registry lookup. */
+export declare const PLUGIN_PACKAGE_NAME = "@syengup/friday-channel-next";
+/** Plugin id as registered with OpenClaw (used to read the install record). */
+export declare const PLUGIN_ID = "friday-next";

package/dist/src/version.js

@@ -0,0 +1,37 @@
+/**
+ * Plugin self-version.
+ *
+ * Resolved at module load by reading this package's own package.json relative to
+ * the compiled module URL. `tsc` does NOT copy package.json into `dist/`, and a
+ * JSON `import` would rewrite to a non-existent `dist/package.json`, so we read
+ * the real file from disk and walk a couple of candidate paths. Falls back to a
+ * hardcoded constant if the file can't be located (keep in sync with package.json).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** Keep in sync with package.json "version" as a last-resort fallback. */
+const FALLBACK_VERSION = "0.1.28";
+function resolvePluginVersion() {
+    // dist layout: <root>/dist/src/version.js → ../../package.json = <root>/package.json
+    // source layout (vitest/jiti): <root>/src/version.ts → ../package.json = <root>/package.json
+    const candidates = ["../../package.json", "../package.json"];
+    for (const rel of candidates) {
+        try {
+            const path = fileURLToPath(new URL(rel, import.meta.url));
+            const raw = readFileSync(path, "utf8");
+            const pkg = JSON.parse(raw);
+            if (pkg.name === "@syengup/friday-channel-next" && typeof pkg.version === "string" && pkg.version) {
+                return pkg.version;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return FALLBACK_VERSION;
+}
+export const PLUGIN_VERSION = resolvePluginVersion();
+/** npm package name, used for the upgrade spec and registry lookup. */
+export const PLUGIN_PACKAGE_NAME = "@syengup/friday-channel-next";
+/** Plugin id as registered with OpenClaw (used to read the install record). */
+export const PLUGIN_ID = "friday-next";

package/index.ts

@@ -15,6 +15,7 @@ import {
   resolveFridayDeviceIdForSessionKey,
 } from "./src/friday-session.js";
 import { setFridayAgentForwardRuntime } from "./src/agent-forward-runtime.js";
+import { setUpgradeRuntime } from "./src/upgrade-runtime.js";
 import { getOpenClawAgentRunContext } from "./src/agent-run-context-bridge.js";
 import { accumulateRunUsage } from "./src/agent/run-usage-accumulator.js";
 import { createFridayNextLogger } from "./src/logging.js";
@@ -86,6 +87,7 @@ export default defineChannelPluginEntry({
   setRuntime: setFridayNextRuntime,
   registerFull: (api: OpenClawPluginApi) => {
     setFridayAgentForwardRuntime(api);
+    setUpgradeRuntime(api);
     const sameApi = lastApiRoutesRegistered?.deref() === api;
     if (!sameApi) {
       lastApiRoutesRegistered = new WeakRef(api);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syengup/friday-channel-next",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "OpenClaw Friday Next Apple channel plugin",
   "license": "MIT",
   "type": "module",

package/src/http/handlers/files.ts

@@ -328,6 +328,7 @@ export function guessMimeType(filename: string): string {
     ".jpeg": "image/jpeg",
     ".gif": "image/gif",
     ".webp": "image/webp",
+    ".ico": "image/x-icon",
     ".heic": "image/heic",
     ".pdf": "application/pdf",
     ".mp4": "video/mp4",

package/src/http/handlers/health.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { extractBearerToken } from "../middleware/auth.js";
 import { loadNodePairingModule } from "../../agent/node-pairing-bridge.js";
 import { createFridayNextLogger } from "../../logging.js";
+import { PLUGIN_VERSION } from "../../version.js";
 
 const REQUIRED_NODE_CAPS = ["location", "canvas"];
 const REQUIRED_NODE_COMMANDS = [
@@ -34,6 +35,7 @@ export interface HealthCheckResult {
   timestamp: number;
   deviceId: string;
   nodeDeviceId: string;
+  pluginVersion: string;
   nodePairing?: HealthComponentStatus;
   repairActions?: RepairAction[];
 }
@@ -64,6 +66,7 @@ export async function handleHealth(req: IncomingMessage, res: ServerResponse): P
     timestamp: Date.now(),
     deviceId,
     nodeDeviceId,
+    pluginVersion: PLUGIN_VERSION,
   };
 
   const log = createFridayNextLogger("health");

package/src/http/handlers/link-preview.test.ts

@@ -0,0 +1,242 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+vi.mock("node:dns/promises", () => ({
+  default: { lookup: vi.fn() },
+}));
+
+import dns from "node:dns/promises";
+import { handleLinkPreview } from "./link-preview.js";
+import { resetLinkPreviewCacheForTest, type LinkPreviewPayload } from "../../link-preview/preview-service.js";
+import { setAttachmentsDirForTest } from "./files.js";
+import { clearFridayNextRuntime, setFridayNextRuntime } from "../../runtime.js";
+
+const lookupMock = vi.mocked(dns.lookup);
+
+class MockRes extends EventEmitter {
+  statusCode = 0;
+  headers: Record<string, string> = {};
+  body = "";
+  setHeader(name: string, value: string): void {
+    this.headers[name.toLowerCase()] = value;
+  }
+  end(body?: string): void {
+    if (body) this.body += body;
+    this.emit("finish");
+  }
+}
+
+function makeReq(query: string | null, token: string | null = "tok"): IncomingMessage {
+  return {
+    method: "GET",
+    url: query == null ? "/friday-next/link-preview" : `/friday-next/link-preview?url=${encodeURIComponent(query)}`,
+    headers: token ? { authorization: `Bearer ${token}` } : {},
+  } as unknown as IncomingMessage;
+}
+
+async function invoke(req: IncomingMessage): Promise<MockRes> {
+  const res = new MockRes();
+  await handleLinkPreview(req, res as unknown as ServerResponse);
+  return res;
+}
+
+const PAGE_HTML = `<html><head>
+  <meta property="og:title" content="Hello Page">
+  <meta property="og:description" content="A description">
+  <meta property="og:site_name" content="Example Site">
+  <meta property="og:image" content="https://example.com/cover.png">
+</head></html>`;
+
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0, 0]);
+
+let tmpDir: string;
+
+beforeEach(() => {
+  resetLinkPreviewCacheForTest();
+  lookupMock.mockReset();
+  lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }] as never);
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "link-preview-test-"));
+  setAttachmentsDirForTest(tmpDir);
+  setFridayNextRuntime({
+    config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },
+  } as never);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  setAttachmentsDirForTest(null);
+  clearFridayNextRuntime();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("handleLinkPreview", () => {
+  it("405 on non-GET", async () => {
+    const res = new MockRes();
+    await handleLinkPreview({ method: "POST", url: "/friday-next/link-preview", headers: {} } as never, res as never);
+    expect(res.statusCode).toBe(405);
+  });
+
+  it("401 without bearer token", async () => {
+    const res = await invoke(makeReq("https://example.com/", null));
+    expect(res.statusCode).toBe(401);
+  });
+
+  it("400 when url param is missing or not http(s)", async () => {
+    expect((await invoke(makeReq(null))).statusCode).toBe(400);
+    expect((await invoke(makeReq("ftp://example.com/x"))).statusCode).toBe(400);
+    expect((await invoke(makeReq("not a url"))).statusCode).toBe(400);
+  });
+
+  it("403 blocked_url for private targets", async () => {
+    const res = await invoke(makeReq("http://192.168.1.1/admin"));
+    expect(res.statusCode).toBe(403);
+    expect(JSON.parse(res.body).error).toBe("blocked_url");
+  });
+
+  it("200 with full preview payload and re-hosted cover image", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.includes("cover.png")) {
+          return new Response(PNG_BYTES, { status: 200, headers: { "content-type": "image/png" } });
+        }
+        return new Response(PAGE_HTML, { status: 200, headers: { "content-type": "text/html; charset=utf-8" } });
+      }),
+    );
+    const res = await invoke(makeReq("https://example.com/article"));
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body) as { ok: boolean; preview: LinkPreviewPayload };
+    expect(body.ok).toBe(true);
+    expect(body.preview.title).toBe("Hello Page");
+    expect(body.preview.description).toBe("A description");
+    expect(body.preview.siteName).toBe("Example Site");
+    expect(body.preview.url).toBe("https://example.com/article");
+    expect(body.preview.finalUrl).toBe("https://example.com/article");
+    expect(body.preview.imageUrl).toMatch(/^\/friday-next\/files\/.+\.png$/);
+    expect(typeof body.preview.fetchedAt).toBe("number");
+    // 封面图确实落盘
+    const token = decodeURIComponent(body.preview.imageUrl!.split("/").pop()!);
+    expect(fs.existsSync(path.join(tmpDir, token))).toBe(true);
+  });
+
+  it("200 with imageUrl null when the cover download fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.includes("cover.png")) return new Response("nope", { status: 404 });
+        return new Response(PAGE_HTML, { status: 200, headers: { "content-type": "text/html" } });
+      }),
+    );
+    const res = await invoke(makeReq("https://example.com/article"));
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).preview.imageUrl).toBeNull();
+  });
+
+  it("falls back siteName to hostname when og:site_name is absent", async () => {
+    const html = `<meta property="og:title" content="T">`;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response(html, { status: 200, headers: { "content-type": "text/html" } })),
+    );
+    const res = await invoke(makeReq("https://example.com/x"));
+    expect(JSON.parse(res.body).preview.siteName).toBe("example.com");
+  });
+
+  it("200 minimal hostname card when a reachable page has no OG metadata", async () => {
+    // 可达但无 OG/title → 退到 hostname 卡片(不再折叠)。
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("<html><body>plain</body></html>", { status: 200, headers: { "content-type": "text/html" } })),
+    );
+    const res = await invoke(makeReq("https://example.com/bare"));
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).preview.title).toBe("example.com");
+  });
+
+  it("ICO favicon re-hosted into iconUrl", async () => {
+    const ICO_BYTES = new Uint8Array([0x00, 0x00, 0x01, 0x00, 0x01, 0, 0, 0, 0, 0, 0, 0]);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.includes("favicon")) {
+          return new Response(ICO_BYTES, { status: 200, headers: { "content-type": "image/x-icon" } });
+        }
+        return new Response(`<meta property="og:title" content="Titled">`, { status: 200, headers: { "content-type": "text/html" } });
+      }),
+    );
+    const res = await invoke(makeReq("https://example.com/p"));
+    const preview = JSON.parse(res.body).preview as LinkPreviewPayload;
+    expect(preview.iconUrl).toMatch(/^\/friday-next\/files\/.+\.ico$/);
+    const token = decodeURIComponent(preview.iconUrl!.split("/").pop()!);
+    expect(fs.existsSync(path.join(tmpDir, token))).toBe(true);
+  });
+
+  it("200 minimal card for a bot-blocked page whose favicon.ico is reachable (zhihu-style)", async () => {
+    const ICO_BYTES = new Uint8Array([0x00, 0x00, 0x01, 0x00, 0x01, 0, 0, 0, 0, 0, 0, 0]);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: URL | string) => {
+        const url = String(input);
+        if (url.endsWith("/favicon.ico")) {
+          return new Response(ICO_BYTES, { status: 200, headers: { "content-type": "image/vnd.microsoft.icon" } });
+        }
+        return new Response("blocked", { status: 403, headers: { "content-type": "text/html" } }); // page blocks bots
+      }),
+    );
+    const res = await invoke(makeReq("https://www.zhihu.com/question/123"));
+    expect(res.statusCode).toBe(200);
+    const preview = JSON.parse(res.body).preview as LinkPreviewPayload;
+    expect(preview.title).toBe("www.zhihu.com");
+    expect(preview.iconUrl).toMatch(/^\/friday-next\/files\/.+\.ico$/);
+    expect(preview.imageUrl).toBeNull();
+  });
+
+  it("502 fetch_failed for a dead domain (page and favicon both fail)", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 404 })));
+    const res = await invoke(makeReq("https://dead.example.com/x"));
+    expect(res.statusCode).toBe(502);
+    expect(JSON.parse(res.body).error).toBe("fetch_failed");
+  });
+
+  it("502 fetch_failed on non-2xx and non-HTML responses", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 500 })));
+    expect((await invoke(makeReq("https://example.com/down"))).statusCode).toBe(502);
+
+    resetLinkPreviewCacheForTest();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("{}", { status: 200, headers: { "content-type": "application/json" } })),
+    );
+    expect((await invoke(makeReq("https://example.com/api"))).statusCode).toBe(502);
+  });
+
+  it("serves the second request from cache without refetching", async () => {
+    const fetchMock = vi.fn(async () => new Response(`<meta property="og:title" content="Cached">`, {
+      status: 200,
+      headers: { "content-type": "text/html" },
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+    await invoke(makeReq("https://example.com/cached"));
+    const afterFirst = fetchMock.mock.calls.length;
+    const second = await invoke(makeReq("https://example.com/cached"));
+    expect(second.statusCode).toBe(200);
+    expect(JSON.parse(second.body).preview.title).toBe("Cached");
+    expect(fetchMock).toHaveBeenCalledTimes(afterFirst); // cached → no extra network
+  });
+
+  it("negative-caches failures", async () => {
+    const fetchMock = vi.fn(async () => new Response("nope", { status: 500 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await invoke(makeReq("https://example.com/flaky"));
+    const afterFirst = fetchMock.mock.calls.length;
+    await invoke(makeReq("https://example.com/flaky"));
+    expect(fetchMock).toHaveBeenCalledTimes(afterFirst); // negative-cached → no refetch
+  });
+});

package/src/http/handlers/link-preview.ts

@@ -0,0 +1,47 @@
+/**
+ * GET /friday-next/link-preview?url=<percent-encoded http(s) URL>
+ *
+ * Returns Open Graph metadata for a page link so the app can render a preview card without
+ * ever contacting the third-party site itself. Cover images are re-hosted under
+ * /friday-next/files/ by the preview service.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { getLinkPreview, type LinkPreviewError } from "../../link-preview/preview-service.js";
+import { extractBearerToken } from "../middleware/auth.js";
+
+const ERROR_STATUS: Record<LinkPreviewError, number> = {
+  invalid_url: 400,
+  blocked_url: 403,
+  no_metadata: 422,
+  fetch_failed: 502,
+};
+
+export async function handleLinkPreview(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (req.method !== "GET") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+  if (!extractBearerToken(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+    return true;
+  }
+
+  const url = new URL(req.url ?? "/", "http://localhost").searchParams.get("url")?.trim();
+  if (!url) {
+    res.statusCode = 400;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ ok: false, error: "invalid_url" }));
+    return true;
+  }
+
+  const result = await getLinkPreview(url);
+  res.statusCode = result.ok ? 200 : ERROR_STATUS[result.error];
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(result));
+  return true;
+}

package/src/http/handlers/messages.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { handleMessages } from "./messages.js";
+import { handleMessages, composeBodyWithMediaRefs } from "./messages.js";
 import { clearFridayNextRuntime, setFridayNextRuntime } from "../../runtime.js";
 import {
   __resetMockFridayDispatchForTests,
@@ -23,6 +23,24 @@ class MockRes extends EventEmitter {
   }
 }
 
+describe("composeBodyWithMediaRefs", () => {
+  it("returns trimmed text alone when no media refs", () => {
+    expect(composeBodyWithMediaRefs("  hi  ", [])).toBe("hi");
+  });
+
+  it("joins text and media refs with a blank line", () => {
+    expect(composeBodyWithMediaRefs("hi", ["[media attached: file:///a]"])).toBe(
+      "hi\n\n[media attached: file:///a]",
+    );
+  });
+
+  it("omits the leading blank line when text is empty (attachment-only)", () => {
+    expect(composeBodyWithMediaRefs("", ["[media attached: file:///a]", "[media attached: file:///b]"])).toBe(
+      "[media attached: file:///a]\n[media attached: file:///b]",
+    );
+  });
+});
+
 describe("handleMessages dispatch context (owner fields)", () => {
   afterEach(() => {
     clearFridayNextRuntime();
@@ -70,6 +88,62 @@ describe("handleMessages dispatch context (owner fields)", () => {
     expect(capturedCtx!.From).toBe(want);
   });
 
+  it("accepts attachment-only messages (empty text + attachments) and dispatches", async () => {
+    setFridayNextRuntime({
+      config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },
+    } as never);
+
+    let dispatched = false;
+    const dispatchCalled = new Promise<void>((resolve) => {
+      __setMockFridayDispatchForTests(() => {
+        dispatched = true;
+        resolve();
+        return Promise.resolve();
+      });
+    });
+
+    const req = new PassThrough() as unknown as IncomingMessage;
+    req.method = "POST";
+    req.headers = { authorization: "Bearer tok" };
+    const res = new MockRes() as unknown as ServerResponse;
+    const p = handleMessages(req, res);
+
+    req.end(
+      JSON.stringify({
+        deviceId: "AA11",
+        text: "",
+        attachments: ["att-1"],
+        sessionKey: "default",
+      }),
+    );
+
+    await p;
+    await dispatchCalled;
+
+    expect((res as unknown as MockRes).statusCode).toBe(202);
+    expect(dispatched).toBe(true);
+  });
+
+  it("rejects messages with neither text nor attachments", async () => {
+    setFridayNextRuntime({
+      config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },
+    } as never);
+
+    const req = new PassThrough() as unknown as IncomingMessage;
+    req.method = "POST";
+    req.headers = { authorization: "Bearer tok" };
+    const res = new MockRes() as unknown as ServerResponse;
+    const p = handleMessages(req, res);
+
+    req.end(
+      JSON.stringify({ deviceId: "AA11", text: "   ", attachments: [], sessionKey: "default" }),
+    );
+
+    await p;
+
+    expect((res as unknown as MockRes).statusCode).toBe(400);
+  });
+
   it("adds fridayNext mediaKind metadata for audio deliver payload", async () => {
     setFridayNextRuntime({
       config: { loadConfig: () => ({ gateway: { auth: { token: "tok" } }, channels: {} }) },

package/src/http/handlers/messages.ts

@@ -362,6 +362,16 @@ export interface FridayMessagePayload {
   thinkingLevel?: string;
 }
 
+/**
+ * 把可选文本与媒体引用拼成给 agent 的最终 body。纯附件（文本为空）场景下
+ * 不能带前导空行，否则 agent 收到的是 `\n\n[media…]`——故拆成可测纯函数。
+ */
+export function composeBodyWithMediaRefs(text: string, mediaRefs: string[]): string {
+  const trimmed = text.trim();
+  if (mediaRefs.length === 0) return trimmed;
+  return trimmed ? `${trimmed}\n\n${mediaRefs.join("\n")}` : mediaRefs.join("\n");
+}
+
 async function buildBodyForAgentWithAttachments(text: string, attachmentIds: string[]): Promise<string> {
   if (attachmentIds.length === 0) return text.trim();
 
@@ -376,8 +386,7 @@ async function buildBodyForAgentWithAttachments(text: string, attachmentIds: str
     }
   }
 
-  if (mediaRefs.length === 0) return text.trim();
-  return `${text.trim()}\n\n${mediaRefs.join("\n")}`;
+  return composeBodyWithMediaRefs(text, mediaRefs);
 }
 
 export async function handleMessages(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
@@ -428,15 +437,18 @@ export async function handleMessages(req: IncomingMessage, res: ServerResponse):
     return true;
   }
 
-  if (!text || !text.trim()) {
-    log("BAD_REQUEST", normalizedDeviceId, undefined, "missing text", "warn");
+  // 允许"只发附件、不发文本"：text 与 attachments 不能同时为空，但任一非空即放行。
+  const hasText = Boolean(text && text.trim());
+  const hasAttachments = Array.isArray(attachments) && attachments.length > 0;
+  if (!hasText && !hasAttachments) {
+    log("BAD_REQUEST", normalizedDeviceId, undefined, "missing text and attachments", "warn");
     res.statusCode = 400;
     res.setHeader("Content-Type", "application/json");
-    res.end(JSON.stringify({ error: "Missing required field: text" }));
+    res.end(JSON.stringify({ error: "Missing required field: text or attachments" }));
     return true;
   }
 
-  const trimmedText = text.trim();
+  const trimmedText = (text ?? "").trim();
   touchFridayInbound();
 
   const isSlashCommand = trimmedText.startsWith("/");
@@ -492,7 +504,7 @@ export async function handleMessages(req: IncomingMessage, res: ServerResponse):
   sseEmitter.trackDeviceForRun(normalizedDeviceId, runId);
   registerRunRoute({ runId, deviceId: normalizedDeviceId, sessionKey: baseSessionKey });
 
-  const bodyForAgent = await buildBodyForAgentWithAttachments(text, attachments);
+  const bodyForAgent = await buildBodyForAgentWithAttachments(trimmedText, attachments);
 
   const msgContext = {
     Body: trimmedText,

package/src/http/handlers/plugin-info.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { extractBearerToken } from "../middleware/auth.js";
+import { PLUGIN_VERSION } from "../../version.js";
+import {
+  fetchLatestVersion,
+  getInstallSource,
+  semverGreater,
+} from "../../plugin-install-info.js";
+
+export interface PluginInfoResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  installSource: string;
+  /** True when the install is npm-managed (the only auto-upgradable source). */
+  canAutoUpgrade: boolean;
+  /** True when a newer version is published AND the install can be auto-upgraded. */
+  upgradable: boolean;
+}
+
+export async function handlePluginInfo(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (req.method !== "GET") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+  if (!extractBearerToken(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Unauthorized: bearer token mismatch" }));
+    return true;
+  }
+
+  const installSource = getInstallSource();
+  const canAutoUpgrade = installSource === "npm";
+  const latestVersion = await fetchLatestVersion(Date.now());
+  const upgradable = canAutoUpgrade && semverGreater(latestVersion, PLUGIN_VERSION);
+
+  const result: PluginInfoResult = {
+    currentVersion: PLUGIN_VERSION,
+    latestVersion,
+    installSource,
+    canAutoUpgrade,
+    upgradable,
+  };
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(result));
+  return true;
+}