@sjawhar/opencode-legion-envoy 0.1.1 → 0.1.2

package/dist/index.js

@@ -12339,13 +12339,21 @@ function tool(input) {
 tool.schema = exports_external;
 
 // src/port.ts
-import { execFileSync } from "child_process";
-function resolvePort(serverUrl, exec = execFileSync) {
+import { execFile } from "child_process";
+var defaultExec = (command, args, options) => new Promise((resolve, reject) => {
+  execFile(command, args, { encoding: options.encoding }, (error45, stdout) => {
+    if (error45)
+      reject(error45);
+    else
+      resolve(stdout);
+  });
+});
+async function resolvePort(serverUrl, exec = defaultExec) {
   const urlPort = Number.parseInt(serverUrl.port, 10);
   if (Number.isFinite(urlPort) && urlPort > 0)
     return urlPort;
   try {
-    const output = exec("ss", ["-tlnp"], { encoding: "utf-8" });
+    const output = await exec("ss", ["-tlnp"], { encoding: "utf-8" });
     for (const line of output.split(`
 `)) {
       if (!line.includes(`pid=${process.pid}`))
@@ -12365,8 +12373,12 @@ function resolvePort(serverUrl, exec = execFileSync) {
 
 // src/index.ts
 var root = process.env.ENVOY_URL ?? "http://127.0.0.1:9020";
+var CALL_TIMEOUT_MS = 5000;
 async function call(path, init) {
-  const res = await fetch(`${root}${path}`, init);
+  const res = await fetch(`${root}${path}`, {
+    ...init,
+    signal: init?.signal ?? AbortSignal.timeout(CALL_TIMEOUT_MS)
+  });
   const text = await res.text();
   if (!res.ok)
     throw new Error(text || `${res.status}`);
@@ -12376,6 +12388,7 @@ var src_default = async (input) => {
   const registryDir = process.env.OC_REGISTRY;
   let activeSessionID = null;
   let _activeFile = null;
+  let resolvedPort = null;
   const registryFile = (sessionID) => registryDir ? `${registryDir}/${sessionID}.json` : null;
   const update = (sessionID, patch) => {
     const file2 = registryFile(sessionID);
@@ -12395,18 +12408,21 @@ var src_default = async (input) => {
     } catch {}
   };
   let portWarningLogged = false;
-  const currentPort = () => {
-    const port = resolvePort(input.serverUrl);
+  const refreshPort = async () => {
+    const port = await resolvePort(input.serverUrl);
     if (!port && !portWarningLogged) {
       portWarningLogged = true;
       console.error(`[envoy-plugin] Could not resolve serve port: serverUrl=${input.serverUrl.href}, pid=${process.pid}`);
     }
-    if (port)
+    if (port) {
       portWarningLogged = false;
+      resolvedPort = port;
+    }
     return port;
   };
-  const syncPort = (sessionID) => {
-    const value = currentPort();
+  const currentPort = () => resolvedPort;
+  const syncPort = async (sessionID) => {
+    const value = await refreshPort();
     if (!value)
       return false;
     if (sessionID)
@@ -12415,7 +12431,9 @@ var src_default = async (input) => {
   };
   const fetchSession = async (sessionID) => {
     try {
-      const res = await fetch(`${input.serverUrl}/session/${sessionID}`);
+      const res = await fetch(`${input.serverUrl}/session/${sessionID}`, {
+        signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
+      });
       if (!res.ok)
         return null;
       const session = await res.json();
@@ -12426,11 +12444,14 @@ var src_default = async (input) => {
   };
   const registryFiles = new Set;
   if (registryDir) {
-    syncPort();
     const timer = setInterval(() => {
-      if (syncPort(activeSessionID ?? undefined))
-        clearInterval(timer);
+      syncPort(activeSessionID ?? undefined).then((resolved) => {
+        if (resolved)
+          clearInterval(timer);
+      });
     }, 1000);
+    timer.unref();
+    syncPort().catch(() => {});
     const heartbeatInterval = setInterval(() => {
       if (!activeSessionID)
         return;
@@ -12449,6 +12470,7 @@ var src_default = async (input) => {
       }).catch(() => {});
     }, 2 * 60 * 1000);
     process.on("exit", () => {
+      clearInterval(timer);
       clearInterval(heartbeatInterval);
       for (const f of registryFiles) {
         try {
@@ -12460,7 +12482,7 @@ var src_default = async (input) => {
   return {
     event: registryDir ? async ({ event }) => {
       if (activeSessionID)
-        syncPort(activeSessionID);
+        syncPort(activeSessionID).catch(() => {});
       if (event.type === "session.status" && event.properties?.status?.type === "busy") {
         const sessionID = event.properties?.sessionID;
         if (sessionID && sessionID !== activeSessionID) {
@@ -12469,7 +12491,7 @@ var src_default = async (input) => {
           const session = await fetchSession(sessionID);
           if (session)
             update(sessionID, { session });
-          syncPort(sessionID);
+          await syncPort(sessionID);
           const port = currentPort();
           if (port) {
             call("/v1/interests/subscribe", {
@@ -12502,9 +12524,9 @@ var src_default = async (input) => {
     } : undefined,
     tool: {
       envoy_subscribe: tool({
-        description: "Subscribe this session to Envoy notification topics. Use exact NATS-style topic strings such as notifications.agent.<session_id>, notifications.github.<owner>.<repo>.pr, notifications.github.<owner>.<repo>.issue, notifications.github.<owner>.<repo>.comment, notifications.github.<owner>.<repo>.ci, notifications.slack.<team_id>.<channel_id>.message, or notifications.slack.<team_id>.<channel_id>.mention. Use this when a session should RECEIVE future events.",
+        description: "Subscribe this session to Envoy notification topics. GitHub topics are resource-scoped: notifications.github.<owner>.<repo>.pr.<number>, notifications.github.<owner>.<repo>.issue.<number>.comment, etc. Use NATS wildcards for broad subscriptions: notifications.github.<owner>.<repo>.pr.> (all PR events). Other topics: notifications.agent.<session_id>, notifications.slack.<team_id>.<channel_id>.message, notifications.slack.<team_id>.<channel_id>.mention. Use this when a session should RECEIVE future events.",
         args: {
-          topics: tool.schema.array(tool.schema.string()).describe("NATS-style topic patterns to subscribe to. Examples: notifications.agent.ses_123, notifications.github.trajectory-labs-pbc.agent-c.pr, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention")
+          topics: tool.schema.array(tool.schema.string()).describe("NATS-style topic patterns to subscribe to. GitHub topics include resource number: notifications.github.owner.repo.pr.123 (PR state), notifications.github.owner.repo.pr.123.comment (PR comments), notifications.github.owner.repo.issue.456.> (all events on issue). Use > wildcard for broad matching. Other examples: notifications.agent.ses_123, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention")
         },
         async execute(args, ctx) {
           ctx.metadata({ title: "Envoy subscribe" });

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sjawhar/legion"
+  },
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target bun --format esm",

package/src/__tests__/index.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+// Suppress console.error during tests
+const originalError = console.error;
+beforeEach(() => {
+  console.error = mock(() => {});
+});
+afterEach(() => {
+  console.error = originalError;
+});
+
+describe("envoy plugin init", () => {
+  it("returns immediately without blocking on port resolution or Envoy calls", async () => {
+    // Simulate NATS/Envoy being unavailable — plugin init must still complete fast
+    const originalEnvoyUrl = process.env.ENVOY_URL;
+    const originalRegistry = process.env.OC_REGISTRY;
+    process.env.ENVOY_URL = "http://127.0.0.1:59999"; // Non-existent
+    process.env.OC_REGISTRY = undefined;
+
+    try {
+      const pluginModule = await import("../index");
+      const initPlugin = pluginModule.default;
+
+      const start = performance.now();
+      const hooks = await initPlugin({ serverUrl: new URL("http://127.0.0.1:13381") } as never);
+      const elapsed = performance.now() - start;
+
+      // Plugin init must complete in under 1 second regardless of NATS state
+      expect(elapsed).toBeLessThan(1000);
+      expect(hooks.tool).toBeDefined();
+      expect(hooks.tool.envoy_subscribe).toBeDefined();
+      expect(hooks.tool.envoy_unsubscribe).toBeDefined();
+      expect(hooks.tool.envoy_list).toBeDefined();
+      expect(hooks.tool.envoy_send).toBeDefined();
+      expect(hooks.tool.envoy_publish).toBeDefined();
+    } finally {
+      process.env.ENVOY_URL = originalEnvoyUrl;
+      process.env.OC_REGISTRY = originalRegistry;
+    }
+  });
+
+  it("call() includes a timeout to prevent hanging on unresponsive Envoy", async () => {
+    // The call function has AbortSignal.timeout — verify it doesn't hang
+    // We test this indirectly: a tool call to non-existent Envoy should reject within timeout
+    const originalEnvoyUrl = process.env.ENVOY_URL;
+    const originalRegistry = process.env.OC_REGISTRY;
+    process.env.ENVOY_URL = "http://127.0.0.1:59999";
+    process.env.OC_REGISTRY = undefined;
+
+    try {
+      const pluginModule = await import("../index");
+      const initPlugin = pluginModule.default;
+      const hooks = await initPlugin({ serverUrl: new URL("http://127.0.0.1:13381") } as never);
+
+      const start = performance.now();
+      try {
+        await hooks.tool.envoy_list.execute({}, {
+          sessionID: "ses_test",
+          directory: "/tmp",
+          metadata: () => {},
+        } as never);
+      } catch {
+        // Expected to fail — Envoy is not running
+      }
+      const elapsed = performance.now() - start;
+
+      // Should fail fast due to connection refused, not hang indefinitely
+      expect(elapsed).toBeLessThan(6000);
+    } finally {
+      process.env.ENVOY_URL = originalEnvoyUrl;
+      process.env.OC_REGISTRY = originalRegistry;
+    }
+  });
+});

package/src/__tests__/port.test.ts

@@ -2,9 +2,9 @@ import { describe, expect, it, mock } from "bun:test";
 import { resolvePort } from "../port";
 
 describe("resolvePort", () => {
-  const noopExec = (() => {
+  const noopExec = (async () => {
     throw new Error("ss not available");
-  }) as typeof import("node:child_process").execFileSync;
+  }) as Parameters<typeof resolvePort>[1];
 
   const ssOutput = (pid: number, port: number) =>
     [
@@ -14,93 +14,111 @@ describe("resolvePort", () => {
     ].join("\n");
 
   describe("URL port extraction", () => {
-    it("returns port from standard non-default URL", () => {
-      expect(resolvePort(new URL("http://127.0.0.1:4096"), noopExec)).toBe(4096);
+    it("returns port from standard non-default URL", async () => {
+      expect(await resolvePort(new URL("http://127.0.0.1:4096"), noopExec)).toBe(4096);
     });
 
-    it("returns port for high serve ports", () => {
-      expect(resolvePort(new URL("http://127.0.0.1:13381"), noopExec)).toBe(13381);
+    it("returns port for high serve ports", async () => {
+      expect(await resolvePort(new URL("http://127.0.0.1:13381"), noopExec)).toBe(13381);
     });
 
-    it("returns port for localhost URLs", () => {
-      expect(resolvePort(new URL("http://localhost:4096"), noopExec)).toBe(4096);
+    it("returns port for localhost URLs", async () => {
+      expect(await resolvePort(new URL("http://localhost:4096"), noopExec)).toBe(4096);
     });
 
-    it("returns port for IPv6 URLs", () => {
-      expect(resolvePort(new URL("http://[::1]:4096"), noopExec)).toBe(4096);
+    it("returns port for IPv6 URLs", async () => {
+      expect(await resolvePort(new URL("http://[::1]:4096"), noopExec)).toBe(4096);
+    });
+
+    it("skips exec entirely when URL port is valid", async () => {
+      const exec = mock(async () => ssOutput(process.pid, 9999));
+      expect(await resolvePort(new URL("http://127.0.0.1:4096"), exec as never)).toBe(4096);
+      expect(exec).not.toHaveBeenCalled();
     });
   });
 
   describe("ss fallback", () => {
-    it("uses ss when URL has no port (default HTTP)", () => {
-      const exec = mock(() => ssOutput(process.pid, 4096));
-      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+    it("uses ss when URL has no port (default HTTP)", async () => {
+      const exec = mock(async () => ssOutput(process.pid, 4096));
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
       expect(exec).toHaveBeenCalledWith("ss", ["-tlnp"], { encoding: "utf-8" });
     });
 
-    it("uses ss when URL port is 0", () => {
+    it("uses ss when URL port is 0", async () => {
       // URL("http://127.0.0.1:0").port is "0", which is not > 0
-      const exec = mock(() => ssOutput(process.pid, 13381));
-      expect(resolvePort(new URL("http://127.0.0.1:0"), exec as never)).toBe(13381);
+      const exec = mock(async () => ssOutput(process.pid, 13381));
+      expect(await resolvePort(new URL("http://127.0.0.1:0"), exec as never)).toBe(13381);
     });
 
-    it("ignores ss lines with different PIDs", () => {
-      const exec = mock(() => ssOutput(99999, 4096));
-      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
+    it("ignores ss lines with different PIDs", async () => {
+      const exec = mock(async () => ssOutput(99999, 4096));
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
     });
 
-    it("handles multiple ss entries and picks the matching PID", () => {
+    it("handles multiple ss entries and picks the matching PID", async () => {
       const output = [
         "State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process",
         `LISTEN 0      511    127.0.0.1:8080  0.0.0.0:*  users:(("node",pid=99999,fd=6))`,
         `LISTEN 0      511    127.0.0.1:4096  0.0.0.0:*  users:(("bun",pid=${process.pid},fd=7))`,
         "",
       ].join("\n");
-      const exec = mock(() => output);
-      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+      const exec = mock(async () => output);
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
     });
 
-    it("handles IPv6 listening addresses in ss output", () => {
+    it("handles IPv6 listening addresses in ss output", async () => {
       const output = [
         "State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process",
         `LISTEN 0      511    [::]:4096  [::]:*  users:(("bun",pid=${process.pid},fd=6))`,
         "",
       ].join("\n");
-      const exec = mock(() => output);
-      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+      const exec = mock(async () => output);
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(4096);
+    });
+
+    it("works with async exec that resolves after a delay", async () => {
+      const exec = mock(
+        () =>
+          new Promise<string>((resolve) =>
+            setTimeout(() => resolve(ssOutput(process.pid, 5555)), 10)
+          )
+      );
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBe(5555);
     });
   });
+
   describe("failure cases", () => {
-    it("returns null when ss is not available", () => {
-      expect(resolvePort(new URL("http://127.0.0.1"), noopExec)).toBeNull();
+    it("returns null when ss is not available", async () => {
+      expect(await resolvePort(new URL("http://127.0.0.1"), noopExec)).toBeNull();
     });
 
-    it("returns null when ss returns empty output", () => {
-      const exec = mock(() => "");
-      expect(resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
+    it("returns null when ss returns empty output", async () => {
+      const exec = mock(async () => "");
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
+    });
+
+    it("returns null when async exec rejects", async () => {
+      const exec = mock(async () => {
+        throw new Error("command failed");
+      });
+      expect(await resolvePort(new URL("http://127.0.0.1"), exec as never)).toBeNull();
     });
   });
 
   describe("edge cases", () => {
-    it("URL.port is empty string for default HTTP port 80", () => {
+    it("URL.port is empty string for default HTTP port 80", async () => {
       // http://127.0.0.1:80 → URL.port is "" (80 is default for http)
       const url = new URL("http://127.0.0.1:80");
       expect(url.port).toBe("");
-      const exec = mock(() => ssOutput(process.pid, 4096));
-      expect(resolvePort(url, exec as never)).toBe(4096);
+      const exec = mock(async () => ssOutput(process.pid, 4096));
+      expect(await resolvePort(url, exec as never)).toBe(4096);
     });
 
-    it("URL.port is empty string for default HTTPS port 443", () => {
+    it("URL.port is empty string for default HTTPS port 443", async () => {
       const url = new URL("https://127.0.0.1:443");
       expect(url.port).toBe("");
-      const exec = mock(() => ssOutput(process.pid, 4096));
-      expect(resolvePort(url, exec as never)).toBe(4096);
-    });
-
-    it("does not use ss fallback when URL port is valid", () => {
-      const exec = mock(() => ssOutput(process.pid, 9999));
-      expect(resolvePort(new URL("http://127.0.0.1:4096"), exec as never)).toBe(4096);
-      expect(exec).not.toHaveBeenCalled();
+      const exec = mock(async () => ssOutput(process.pid, 4096));
+      expect(await resolvePort(url, exec as never)).toBe(4096);
     });
   });
 });

package/src/index.ts

@@ -4,8 +4,14 @@ import { resolvePort } from "./port";
 
 const root = process.env.ENVOY_URL ?? "http://127.0.0.1:9020";
 
+/** HTTP timeout for Envoy calls — prevent hanging when NATS/Envoy is unavailable. */
+const CALL_TIMEOUT_MS = 5_000;
+
 async function call(path: string, init?: RequestInit) {
-  const res = await fetch(`${root}${path}`, init);
+  const res = await fetch(`${root}${path}`, {
+    ...init,
+    signal: init?.signal ?? AbortSignal.timeout(CALL_TIMEOUT_MS),
+  });
   const text = await res.text();
   if (!res.ok) throw new Error(text || `${res.status}`);
   return text;
@@ -15,6 +21,8 @@ export default async (input: { serverUrl: URL }) => {
   const registryDir = process.env.OC_REGISTRY;
   let activeSessionID: string | null = null;
   let _activeFile: string | null = null;
+  /** Cached port — resolved asynchronously, null until first successful resolution. */
+  let resolvedPort: number | null = null;
 
   const registryFile = (sessionID: string) =>
     registryDir ? `${registryDir}/${sessionID}.json` : null;
@@ -36,20 +44,26 @@ export default async (input: { serverUrl: URL }) => {
   };
 
   let portWarningLogged = false;
-  const currentPort = () => {
-    const port = resolvePort(input.serverUrl);
+  const refreshPort = async (): Promise<number | null> => {
+    const port = await resolvePort(input.serverUrl);
     if (!port && !portWarningLogged) {
       portWarningLogged = true;
       console.error(
         `[envoy-plugin] Could not resolve serve port: serverUrl=${input.serverUrl.href}, pid=${process.pid}`
       );
     }
-    if (port) portWarningLogged = false;
+    if (port) {
+      portWarningLogged = false;
+      resolvedPort = port;
+    }
     return port;
   };
 
-  const syncPort = (sessionID?: string) => {
-    const value = currentPort();
+  /** Return cached port synchronously — tools need a port value inline. */
+  const currentPort = () => resolvedPort;
+
+  const syncPort = async (sessionID?: string): Promise<boolean> => {
+    const value = await refreshPort();
     if (!value) return false;
     if (sessionID) update(sessionID, { port: value });
     return true;
@@ -57,7 +71,9 @@ export default async (input: { serverUrl: URL }) => {
 
   const fetchSession = async (sessionID: string) => {
     try {
-      const res = await fetch(`${input.serverUrl}/session/${sessionID}`);
+      const res = await fetch(`${input.serverUrl}/session/${sessionID}`, {
+        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+      });
       if (!res.ok) return null;
       const session = await res.json();
       return { id: session.id, title: session.title || "" };
@@ -70,10 +86,16 @@ export default async (input: { serverUrl: URL }) => {
   const registryFiles = new Set<string>();
 
   if (registryDir) {
-    syncPort();
+    // Defer port resolution to background — never block plugin init.
+    // The port sync loop retries every second until resolved.
     const timer = setInterval(() => {
-      if (syncPort(activeSessionID ?? undefined)) clearInterval(timer);
+      syncPort(activeSessionID ?? undefined).then((resolved) => {
+        if (resolved) clearInterval(timer);
+      });
     }, 1000);
+    timer.unref(); // Don't prevent graceful shutdown if port never resolves
+    // Fire an immediate async attempt (non-blocking)
+    syncPort().catch(() => {});
 
     // Heartbeat: re-subscribe every 2 minutes to refresh envoy_sessions TTL (5-min)
     const heartbeatInterval = setInterval(
@@ -96,6 +118,7 @@ export default async (input: { serverUrl: URL }) => {
     );
 
     process.on("exit", () => {
+      clearInterval(timer);
       clearInterval(heartbeatInterval);
       for (const f of registryFiles) {
         try {
@@ -108,7 +131,7 @@ export default async (input: { serverUrl: URL }) => {
   return {
     event: registryDir
       ? async ({ event }: { event: { type?: string; properties?: Record<string, unknown> } }) => {
-          if (activeSessionID) syncPort(activeSessionID);
+          if (activeSessionID) syncPort(activeSessionID).catch(() => {});
 
           if (
             event.type === "session.status" &&
@@ -120,7 +143,7 @@ export default async (input: { serverUrl: URL }) => {
               _activeFile = registryFile(sessionID);
               const session = await fetchSession(sessionID);
               if (session) update(sessionID, { session });
-              syncPort(sessionID);
+              await syncPort(sessionID);
               const port = currentPort();
               if (port) {
                 call("/v1/interests/subscribe", {
@@ -155,12 +178,12 @@ export default async (input: { serverUrl: URL }) => {
     tool: {
       envoy_subscribe: tool({
         description:
-          "Subscribe this session to Envoy notification topics. Use exact NATS-style topic strings such as notifications.agent.<session_id>, notifications.github.<owner>.<repo>.pr, notifications.github.<owner>.<repo>.issue, notifications.github.<owner>.<repo>.comment, notifications.github.<owner>.<repo>.ci, notifications.slack.<team_id>.<channel_id>.message, or notifications.slack.<team_id>.<channel_id>.mention. Use this when a session should RECEIVE future events.",
+          "Subscribe this session to Envoy notification topics. GitHub topics are resource-scoped: notifications.github.<owner>.<repo>.pr.<number>, notifications.github.<owner>.<repo>.issue.<number>.comment, etc. Use NATS wildcards for broad subscriptions: notifications.github.<owner>.<repo>.pr.> (all PR events). Other topics: notifications.agent.<session_id>, notifications.slack.<team_id>.<channel_id>.message, notifications.slack.<team_id>.<channel_id>.mention. Use this when a session should RECEIVE future events.",
         args: {
           topics: tool.schema
             .array(tool.schema.string())
             .describe(
-              "NATS-style topic patterns to subscribe to. Examples: notifications.agent.ses_123, notifications.github.trajectory-labs-pbc.agent-c.pr, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
+              "NATS-style topic patterns to subscribe to. GitHub topics include resource number: notifications.github.owner.repo.pr.123 (PR state), notifications.github.owner.repo.pr.123.comment (PR comments), notifications.github.owner.repo.issue.456.> (all events on issue). Use > wildcard for broad matching. Other examples: notifications.agent.ses_123, notifications.slack.T09FRELLTS8.C0A0DHVU8HE.mention"
             ),
         },
         async execute(args, ctx) {

package/src/port.ts

@@ -1,4 +1,18 @@
-import { execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
+
+type ExecFn = (
+  command: string,
+  args: string[],
+  options: { encoding: string }
+) => string | Promise<string>;
+
+const defaultExec: ExecFn = (command, args, options) =>
+  new Promise<string>((resolve, reject) => {
+    execFile(command, args, { encoding: options.encoding as BufferEncoding }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(stdout as string);
+    });
+  });
 
 /**
  * Resolve the serve port from the server URL, with ss(8) fallback.
@@ -8,17 +22,17 @@ import { execFileSync } from "node:child_process";
  * 2. ss -tlnp PID match (finds listening port by process ID)
  * 3. null (caller decides how to handle)
  */
-export function resolvePort(
+export async function resolvePort(
   serverUrl: URL,
-  exec: typeof execFileSync = execFileSync
-): number | null {
+  exec: ExecFn = defaultExec
+): Promise<number | null> {
   // Try URL.port first (standard path for non-default ports like 4096, 13381)
   const urlPort = Number.parseInt(serverUrl.port, 10);
   if (Number.isFinite(urlPort) && urlPort > 0) return urlPort;
 
   // Fallback: find listening port via ss(8) by PID
   try {
-    const output = exec("ss", ["-tlnp"], { encoding: "utf-8" }) as string;
+    const output = await exec("ss", ["-tlnp"], { encoding: "utf-8" });
     for (const line of output.split("\n")) {
       if (!line.includes(`pid=${process.pid}`)) continue;
       const parts = line.trim().split(/\s+/);
@@ -32,3 +46,4 @@ export function resolvePort(
 
   return null;
 }
+// trigger publish