@hienlh/ppm 0.8.85 → 0.8.86

package/src/server/index.ts

@@ -13,8 +13,7 @@ import { postgresRoutes } from "./routes/postgres.ts";
 import { databaseRoutes } from "./routes/database.ts";
 import { fsBrowseRoutes } from "./routes/fs-browse.ts";
 import { accountsRoutes } from "./routes/accounts.ts";
-import { proxyRoutes } from "./routes/proxy.ts";
-import { browserPreviewRoutes } from "./routes/browser-preview.ts";
+import { proxyRoutes, handleProxyRequest } from "./routes/proxy.ts";
 import { initAdapters } from "../services/database/init-adapters.ts";
 import { terminalWebSocket } from "./ws/terminal.ts";
 import { chatWebSocket } from "./ws/chat.ts";
@@ -22,10 +21,6 @@ import { ok, err } from "../types/api.ts";
 
 /** Tee console.log/error to ~/.ppm/ppm.log while preserving terminal output */
 async function setupLogFile() {
-  // Guard: prevent re-wrapping console on hot-reload (bun --hot re-executes the module)
-  if ((globalThis as any).__PPM_LOG_SETUP__) return;
-  (globalThis as any).__PPM_LOG_SETUP__ = true;
-
   const { resolve } = await import("node:path");
   const { homedir } = await import("node:os");
   const { appendFileSync, mkdirSync, existsSync } = await import("node:fs");
@@ -131,9 +126,6 @@ app.route("/proxy", proxyRoutes);
 app.use("/api/*", authMiddleware);
 app.get("/api/auth/check", (c) => c.json(ok(true)));
 
-// Browser preview reverse proxy — proxies to localhost:<port> for iframe embedding
-app.route("/api/preview", browserPreviewRoutes);
-
 // Filesystem operations (browse, list, read, write) — consolidated in fs-browse route
 app.route("/api/fs", fsBrowseRoutes);
 
@@ -160,39 +152,47 @@ app.route("/", staticRoutes);
 
 export async function startServer(options: {
   port?: string;
+  foreground?: boolean;
+  daemon?: boolean; // compat, ignored (daemon is now default)
   share?: boolean;
   config?: string;
   profile?: string;
 }) {
-  // Tunnel always enabled — cloudflared shares the server publicly
-  options.share = true;
-
   // Load config
   configService.load(options.config);
   const port = parseInt(options.port ?? String(configService.get("port")), 10);
   const host = configService.get("host");
 
+  // Setup log file (both foreground and daemon modes)
   await setupLogFile();
 
-  // Check if port is already in use before spawning supervisor
-  const portInUse = await new Promise<boolean>((resolve) => {
-    const net = require("node:net") as typeof import("node:net");
-    const tester = net.createServer()
-      .once("error", (err: NodeJS.ErrnoException) => {
-        resolve(err.code === "EADDRINUSE");
-      })
-      .once("listening", () => {
-        tester.close(() => resolve(false));
-      })
-      .listen(port, host);
-  });
-  if (portInUse) {
-    console.error(`\n  ✗  Port ${port} is already in use.`);
-    console.error(`     Run 'ppm stop' first or use a different port with --port.\n`);
-    process.exit(1);
+  // Check if port is already in use before starting.
+  // Skip in hot-reload mode — Bun.serve() replaces the previous server on the same port,
+  // but a net.createServer() probe would see it as "in use" and exit prematurely.
+  // globalThis persists across bun --hot reloads, so we use a flag set after first start.
+  const isHotReload = !!(globalThis as any).__PPM_SERVER_STARTED__;
+  if (!isHotReload) {
+    const portInUse = await new Promise<boolean>((resolve) => {
+      const net = require("node:net") as typeof import("node:net");
+      const tester = net.createServer()
+        .once("error", (err: NodeJS.ErrnoException) => {
+          resolve(err.code === "EADDRINUSE");
+        })
+        .once("listening", () => {
+          tester.close(() => resolve(false));
+        })
+        .listen(port, host);
+    });
+    if (portInUse) {
+      console.error(`\n  ✗  Port ${port} is already in use.`);
+      console.error(`     Run 'ppm stop' first or use a different port with --port.\n`);
+      process.exit(1);
+    }
   }
 
-  {
+  const isDaemon = !options.foreground;
+
+  if (isDaemon) {
     const { resolve } = await import("node:path");
     const { homedir } = await import("node:os");
     const { writeFileSync, readFileSync, mkdirSync, existsSync, openSync } = await import("node:fs");
@@ -258,6 +258,7 @@ export async function startServer(options: {
       if (isNaN(supervisorPid)) {
         console.error("  ✗  Failed to start supervisor on Windows.");
         console.error(`     ${result.stderr.toString().trim()}`);
+        console.error("     Try: ppm start -f (foreground mode)");
         process.exit(1);
       }
     } else {
@@ -282,6 +283,7 @@ export async function startServer(options: {
       try { process.kill(supervisorPid, 0); } catch {
         console.error("  ✗  Supervisor exited immediately after start.");
         console.error("     Check logs: ppm logs");
+        console.error("     Or try: ppm start -f (foreground mode)");
         process.exit(1);
       }
       // Check if server PID appeared in status.json
@@ -337,6 +339,133 @@ export async function startServer(options: {
 
     process.exit(0);
   }
+
+  // Foreground mode — with WebSocket support
+  const server = Bun.serve({
+    port,
+    hostname: host,
+    async fetch(req, server) {
+      const url = new URL(req.url);
+
+      // Proxy: handle before Hono to avoid SPA catch-all conflict
+      if (url.pathname.startsWith("/proxy")) {
+        const proxyRes = await handleProxyRequest(req);
+        if (proxyRes) return proxyRes;
+      }
+
+      // WebSocket upgrade: /ws/project/:projectName/terminal/:id
+      if (url.pathname.startsWith("/ws/project/")) {
+        const parts = url.pathname.split("/");
+        const projectName = parts[3] ?? "";
+        const wsType = parts[4] ?? "";
+        const id = parts[5] ?? "";
+
+        if (wsType === "terminal") {
+          const upgraded = server.upgrade(req, {
+            data: { type: "terminal", id, projectName },
+          });
+          if (upgraded) return undefined;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
+
+        if (wsType === "chat") {
+          const sessionId = id;
+          const upgraded = server.upgrade(req, {
+            data: { type: "chat", sessionId, projectName },
+          });
+          if (upgraded) return undefined;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
+      }
+
+      return app.fetch(req, server);
+    },
+    websocket: {
+      idleTimeout: 960,
+      sendPong: true,
+      perMessageDeflate: false, // Disable compression — Cloudflare tunnels can mangle compressed frames
+      open(ws: any) {
+        if (ws.data?.type === "health") {
+          ws.send(JSON.stringify({ type: "health", status: "ok" }));
+        } else if (ws.data?.type === "chat") chatWebSocket.open(ws);
+        else terminalWebSocket.open(ws);
+      },
+      message(ws: any, msg: any) {
+        if (ws.data?.type === "health") {
+          // Respond to ping with pong
+          ws.send(JSON.stringify({ type: "health", status: "ok" }));
+        } else if (ws.data?.type === "chat") chatWebSocket.message(ws, msg);
+        else terminalWebSocket.message(ws, msg);
+      },
+      close(ws: any) {
+        if (ws.data?.type === "health") return;
+        if (ws.data?.type === "chat") chatWebSocket.close(ws);
+        else terminalWebSocket.close(ws);
+      },
+    } as Parameters<typeof Bun.serve>[0] extends { websocket?: infer W } ? W : never,
+  });
+
+  // Mark server as started — survives bun --hot reloads (globalThis persists)
+  (globalThis as any).__PPM_SERVER_STARTED__ = true;
+
+  // Start background usage polling
+  import("../services/claude-usage.service.ts").then(({ startUsagePolling }) => startUsagePolling()).catch(() => {});
+
+  // Start background account token refresh
+  import("../services/account.service.ts").then(({ accountService }) => accountService.startAutoRefresh()).catch(() => {});
+
+  console.log(`\n  PPM ready\n`);
+  console.log(`  ➜  Local:   http://localhost:${server.port}/`);
+
+  const { networkInterfaces } = await import("node:os");
+  const nets = networkInterfaces();
+  for (const name of Object.keys(nets)) {
+    for (const net of nets[name] ?? []) {
+      if (net.family === "IPv4" && !net.internal) {
+        console.log(`  ➜  Network: http://${net.address}:${server.port}/`);
+      }
+    }
+  }
+
+  // Share tunnel in foreground mode
+  if (options.share) {
+    try {
+      const { tunnelService } = await import("../services/tunnel.service.ts");
+      console.log("\n  Starting share tunnel...");
+      const shareUrl = await tunnelService.startTunnel(server.port!);
+      console.log(`  ➜  Share:   ${shareUrl}`);
+      if (!configService.get("auth").enabled) {
+        console.log(`\n  ⚠  Warning: auth is disabled — your IDE is publicly accessible!`);
+        console.log(`     Enable auth: run 'ppm config set auth.enabled true' or restart without --share.`);
+      }
+      const qr = await import("qrcode-terminal");
+      console.log();
+      qr.generate(shareUrl, { small: true });
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`  ✗  Share failed: ${msg}`);
+    }
+  }
+
+  console.log(`\n  Auth: ${configService.get("auth").enabled ? "enabled" : "disabled"}`);
+  if (configService.get("auth").enabled) {
+    console.log(`  Token: ${configService.get("auth").token}`);
+  }
+  console.log();
+
+  // Graceful shutdown — stop server + tunnel + DB on exit
+  const shutdown = () => {
+    try { server.stop(true); } catch {}
+    try {
+      import("../services/tunnel.service.ts").then(({ tunnelService }) => tunnelService.stopTunnel()).catch(() => {});
+    } catch {}
+    try {
+      import("../services/db.service.ts").then(({ closeDb }) => closeDb()).catch(() => {});
+    } catch {}
+  };
+  process.on("SIGINT", () => { shutdown(); process.exit(0); });
+  process.on("SIGTERM", () => { shutdown(); process.exit(0); });
+  process.on("exit", shutdown);
 }
 
 // Internal entry point for daemon child process
@@ -360,16 +489,12 @@ if (process.argv.includes("__serve__")) {
 
   // Sync externally-started tunnel URL + PID into tunnelService
   // so GET /api/tunnel reflects the correct state and Share button doesn't start a duplicate.
-  // Also write server version to status.json so supervisor heartbeat reports the actual running version.
   try {
     const { resolve: r } = await import("node:path");
     const { homedir: h } = await import("node:os");
-    const { readFileSync: rf, writeFileSync: wf } = await import("node:fs");
+    const { readFileSync: rf } = await import("node:fs");
     const statusFile = r(h(), ".ppm", "status.json");
     const status = JSON.parse(rf(statusFile, "utf-8"));
-    // Write running server version — source of truth for heartbeat
-    status.serverVersion = VERSION;
-    wf(statusFile, JSON.stringify(status));
     if (status.shareUrl) {
       const { tunnelService } = await import("../services/tunnel.service.ts");
       tunnelService.setExternalUrl(status.shareUrl);
@@ -380,9 +505,15 @@ if (process.argv.includes("__serve__")) {
   Bun.serve({
     port,
     hostname: host,
-    fetch(req, server) {
+    async fetch(req, server) {
       const url = new URL(req.url);
 
+      // Proxy: handle before Hono to avoid SPA catch-all conflict
+      if (url.pathname.startsWith("/proxy")) {
+        const proxyRes = await handleProxyRequest(req);
+        if (proxyRes) return proxyRes;
+      }
+
       if (url.pathname === "/ws/health") {
         const upgraded = server.upgrade(req, { data: { type: "health" } });
         if (upgraded) return undefined;
@@ -437,8 +568,5 @@ if (process.argv.includes("__serve__")) {
   // Start background account token refresh in daemon child
   import("../services/account.service.ts").then(({ accountService }) => accountService.startAutoRefresh()).catch(() => {});
 
-  // Start background usage limit polling (every 5 min)
-  import("../services/claude-usage.service.ts").then(({ startUsagePolling }) => startUsagePolling()).catch(() => {});
-
   console.log(`Server child ready on port ${port}`);
 }

package/src/server/routes/chat.ts

@@ -8,7 +8,7 @@ import { renameSession as sdkRenameSession } from "@anthropic-ai/claude-agent-sd
 import { listSlashItems } from "../../services/slash-items.service.ts";
 import { getCachedUsage, refreshUsageNow } from "../../services/claude-usage.service.ts";
 import { getSessionLog } from "../../services/session-log.service.ts";
-import { getSessionMapping, setSessionTitle, getPinnedSessionIds, pinSession, unpinSession } from "../../services/db.service.ts";
+import { getSessionMapping } from "../../services/db.service.ts";
 import { ok, err } from "../../types/api.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
@@ -63,16 +63,7 @@ chatRoutes.get("/sessions", async (c) => {
     const projectPath = c.get("projectPath");
     const providerId = c.req.query("providerId");
     const sessions = await chatService.listSessions(providerId, projectPath);
-    // Enrich with pin status
-    const pinnedIds = getPinnedSessionIds();
-    const enriched = sessions.map((s) => ({ ...s, pinned: pinnedIds.has(s.id) }));
-    // Sort: pinned first (by pinned_at implicit via Set order), then unpinned by createdAt
-    enriched.sort((a, b) => {
-      if (a.pinned && !b.pinned) return -1;
-      if (!a.pinned && b.pinned) return 1;
-      return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
-    });
-    return c.json(ok(enriched));
+    return c.json(ok(sessions));
   } catch (e) {
     return c.json(err((e as Error).message), 500);
   }
@@ -129,9 +120,7 @@ chatRoutes.patch("/sessions/:id", async (c) => {
     // Resolve PPM UUID → SDK session ID if mapped
     const sdkId = getSessionMapping(id) ?? id;
     const projectPath = c.get("projectPath");
-    // Persist to PPM DB (authoritative source for user-set titles)
-    setSessionTitle(sdkId, title);
-    // Also persist to SDK so Claude Code CLI sees the custom title
+    // Persist to SDK so Claude Code CLI also sees the custom title
     await sdkRenameSession(sdkId, title, { dir: projectPath });
     // Also update in-memory session
     const session = chatService.getSession(id);
@@ -142,28 +131,6 @@ chatRoutes.patch("/sessions/:id", async (c) => {
   }
 });
 
-/** PUT /chat/sessions/:id/pin — pin a session */
-chatRoutes.put("/sessions/:id/pin", (c) => {
-  try {
-    const id = c.req.param("id");
-    pinSession(id);
-    return c.json(ok({ id, pinned: true }));
-  } catch (e) {
-    return c.json(err((e as Error).message), 500);
-  }
-});
-
-/** DELETE /chat/sessions/:id/pin — unpin a session */
-chatRoutes.delete("/sessions/:id/pin", (c) => {
-  try {
-    const id = c.req.param("id");
-    unpinSession(id);
-    return c.json(ok({ id, pinned: false }));
-  } catch (e) {
-    return c.json(err((e as Error).message), 500);
-  }
-});
-
 /** POST /chat/sessions/:id/fork — fork session into a new one (for rewind/branch) */
 chatRoutes.post("/sessions/:id/fork", async (c) => {
   try {
@@ -200,22 +167,6 @@ chatRoutes.get("/sessions/:id/logs", (c) => {
   }
 });
 
-/** GET /chat/sessions/:id/debug — session debug info (IDs, JSONL path) */
-chatRoutes.get("/sessions/:id/debug", (c) => {
-  const ppmId = c.req.param("id");
-  const sdkId = getSessionMapping(ppmId) ?? ppmId;
-  const projectName = c.req.query("project") ?? "";
-  // Resolve JSONL path: ~/.claude/projects/<encoded-cwd>/<sdkId>.jsonl
-  const homedir = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  const provider = providerRegistry.get("claude") as any;
-  const projectPath = provider?.activeSessions?.get(ppmId)?.projectPath ?? "";
-  const encodedCwd = projectPath ? projectPath.replace(/\//g, "-") : "";
-  const jsonlDir = encodedCwd ? resolve(homedir, ".claude", "projects", encodedCwd) : "";
-  const jsonlPath = jsonlDir ? resolve(jsonlDir, `${sdkId}.jsonl`) : "";
-  const jsonlExists = jsonlPath ? existsSync(jsonlPath) : false;
-  return c.json(ok({ ppmSessionId: ppmId, sdkSessionId: sdkId, jsonlPath: jsonlExists ? jsonlPath : null, jsonlDir, projectPath }));
-});
-
 /** POST /chat/upload — upload files for chat attachments, returns server-side paths */
 chatRoutes.post("/upload", async (c) => {
   try {

package/src/server/routes/project-scoped.ts

@@ -4,7 +4,6 @@ import { chatRoutes } from "./chat.ts";
 import { gitRoutes } from "./git.ts";
 import { fileRoutes } from "./files.ts";
 import { sqliteRoutes } from "./sqlite.ts";
-import { workspaceRoutes } from "./workspace.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
 
@@ -28,4 +27,3 @@ projectScopedRouter.route("/chat", chatRoutes);
 projectScopedRouter.route("/git", gitRoutes);
 projectScopedRouter.route("/files", fileRoutes);
 projectScopedRouter.route("/sqlite", sqliteRoutes);
-projectScopedRouter.route("/workspace", workspaceRoutes);

package/src/server/routes/proxy.ts

@@ -1,79 +1,86 @@
 import { Hono } from "hono";
 import { proxyService } from "../../services/proxy.service.ts";
-import { ok, err } from "../../types/api.ts";
 
 /**
  * Proxy routes — Anthropic-compatible API proxy.
- * External tools (opencode, cursor, etc.) send requests here
+ * External tools (Claude Code CLI, OpenCode, Cursor, etc.) send requests here
  * and PPM forwards them to Anthropic using account rotation.
  *
- * Mounted at /proxy — so /proxy/v1/messages maps to Anthropic's POST /v1/messages.
+ * Mounted at /proxy — all paths are forwarded to api.anthropic.com.
  * Uses its own auth (proxy auth key), NOT PPM's auth middleware.
+ *
+ * Usage with Claude Code CLI:
+ *   ANTHROPIC_BASE_URL=http://host:port/proxy
+ *   ANTHROPIC_API_KEY=<proxy-auth-key>
  */
-export const proxyRoutes = new Hono();
 
-/** Validate proxy auth key from Authorization header */
+/** Validate proxy auth key from Authorization or x-api-key header */
 function validateProxyAuth(authHeader: string | undefined): boolean {
   if (!authHeader) return false;
   const key = proxyService.getAuthKey();
   if (!key) return false;
-  // Accept both "Bearer <key>" and raw "<key>" (x-api-key style)
   const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
   return token === key;
 }
 
-/** CORS preflight for external tools */
-proxyRoutes.options("/*", (c) => {
-  return new Response(null, {
-    status: 204,
-    headers: {
-      "Access-Control-Allow-Origin": "*",
-      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
-      "Access-Control-Allow-Headers": "Content-Type, Authorization, x-api-key, anthropic-version, anthropic-beta",
-      "Access-Control-Max-Age": "86400",
-    },
-  });
-});
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, GET, PUT, DELETE, PATCH, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, x-api-key, anthropic-version, anthropic-beta",
+  "Access-Control-Max-Age": "86400",
+};
 
-/** POST /proxy/v1/messages — Anthropic Messages API proxy */
-proxyRoutes.post("/v1/messages", async (c) => {
-  if (!proxyService.isEnabled()) {
-    return c.json({ type: "error", error: { type: "api_error", message: "Proxy is disabled" } }, 503);
-  }
+/**
+ * Standalone proxy request handler — called directly from Bun.serve fetch,
+ * bypassing Hono routing to avoid SPA catch-all conflicts.
+ * Returns a Response for /proxy/* requests, or null if path doesn't match.
+ */
+export async function handleProxyRequest(req: Request): Promise<Response | null> {
+  const url = new URL(req.url);
+  if (!url.pathname.startsWith("/proxy/") && url.pathname !== "/proxy") return null;
 
-  // Auth check — accept both Authorization and x-api-key headers
-  const authHeader = c.req.header("authorization") || c.req.header("x-api-key");
-  if (!validateProxyAuth(authHeader)) {
-    return c.json({ type: "error", error: { type: "authentication_error", message: "Invalid proxy auth key" } }, 401);
+  // CORS preflight
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: CORS_HEADERS });
   }
 
-  const body = await c.req.text();
-  const headers: Record<string, string> = {};
-  for (const key of ["anthropic-version", "anthropic-beta", "content-type"]) {
-    const val = c.req.header(key);
-    if (val) headers[key] = val;
-  }
-
-  return proxyService.forward("/v1/messages", "POST", headers, body);
-});
-
-/** POST /proxy/v1/messages/count_tokens — token counting proxy */
-proxyRoutes.post("/v1/messages/count_tokens", async (c) => {
   if (!proxyService.isEnabled()) {
-    return c.json({ type: "error", error: { type: "api_error", message: "Proxy is disabled" } }, 503);
+    return Response.json(
+      { type: "error", error: { type: "api_error", message: "Proxy is disabled" } },
+      { status: 503, headers: { "Access-Control-Allow-Origin": "*" } },
+    );
   }
 
-  const authHeader = c.req.header("authorization") || c.req.header("x-api-key");
+  // Auth check
+  const authHeader = req.headers.get("authorization") || req.headers.get("x-api-key") || undefined;
   if (!validateProxyAuth(authHeader)) {
-    return c.json({ type: "error", error: { type: "authentication_error", message: "Invalid proxy auth key" } }, 401);
+    return Response.json(
+      { type: "error", error: { type: "authentication_error", message: "Invalid proxy auth key" } },
+      { status: 401, headers: { "Access-Control-Allow-Origin": "*" } },
+    );
   }
 
-  const body = await c.req.text();
+  // Strip /proxy prefix to get the Anthropic API path
+  const path = url.pathname.replace(/^\/proxy/, "") || "/";
+  const method = req.method;
+
+  // Collect relevant headers to forward
   const headers: Record<string, string> = {};
-  for (const key of ["anthropic-version", "anthropic-beta", "content-type"]) {
-    const val = c.req.header(key);
+  for (const key of ["anthropic-version", "anthropic-beta", "content-type", "accept"]) {
+    const val = req.headers.get(key);
     if (val) headers[key] = val;
   }
 
-  return proxyService.forward("/v1/messages/count_tokens", "POST", headers, body);
+  // Read body for methods that have one
+  const body = ["POST", "PUT", "PATCH"].includes(method) ? await req.text() : null;
+
+  return proxyService.forward(path, method, headers, body);
+}
+
+// Keep Hono sub-router for backward compat with app.route() + tests
+export const proxyRoutes = new Hono();
+proxyRoutes.all("/*", async (c) => {
+  const res = await handleProxyRequest(c.req.raw);
+  if (res) return res;
+  return c.notFound();
 });

package/src/server/routes/tunnel.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { tunnelService } from "../../services/tunnel.service.ts";
+import { portTunnelService } from "../../services/port-tunnel.service.ts";
 import { configService } from "../../services/config.service.ts";
 import { getLocalIp } from "../../lib/network-utils.ts";
 import { ok, err } from "../../types/api.ts";
@@ -36,3 +37,34 @@ tunnelRoutes.post("/stop", (c) => {
   tunnelService.stopTunnel();
   return c.json(ok({ stopped: true }));
 });
+
+// --- Port-specific tunnels (for browser tab preview) ---
+
+/** GET /api/tunnel/ports — list all active port tunnels */
+tunnelRoutes.get("/ports", (c) => {
+  return c.json(ok(portTunnelService.list()));
+});
+
+/** POST /api/tunnel/port/start — start tunnel for a specific port */
+tunnelRoutes.post("/port/start", async (c) => {
+  const body = await c.req.json<{ port: number }>();
+  const port = Number(body.port);
+  if (!port || port < 1 || port > 65535) {
+    return c.json(err("Invalid port number"), 400);
+  }
+  try {
+    const url = await portTunnelService.start(port);
+    return c.json(ok({ port, url }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /api/tunnel/port/stop — stop tunnel for a specific port */
+tunnelRoutes.post("/port/stop", async (c) => {
+  const body = await c.req.json<{ port: number }>();
+  const port = Number(body.port);
+  if (!port) return c.json(err("Invalid port number"), 400);
+  const stopped = portTunnelService.stop(port);
+  return c.json(ok({ stopped }));
+});