enpilink 1.0.2

package/dist/cli/tunnel-handler.test.js

@@ -0,0 +1,107 @@
+import { EventEmitter } from "node:events";
+import http from "node:http";
+import { Readable } from "node:stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TunnelManager } from "./tunnel.js";
+import { createTunnelHandler } from "./tunnel-handler.js";
+let openServer;
+afterEach(() => openServer?.close());
+function makeFakeChild() {
+    const child = new EventEmitter();
+    child.stdout = new Readable({ read() { } });
+    child.stderr = new Readable({ read() { } });
+    child.kill = vi.fn(() => true);
+    return child;
+}
+async function listen(handler) {
+    const server = http.createServer(handler);
+    await new Promise((resolve) => server.listen(0, resolve));
+    const port = server.address().port;
+    return { port, server };
+}
+async function listenWithHandler() {
+    const child = makeFakeChild();
+    const manager = new TunnelManager({
+        getPort: () => 3000,
+        spawn: () => child,
+    });
+    const { port, server } = await listen(createTunnelHandler(manager));
+    openServer = server;
+    return { port, child, manager };
+}
+describe("createTunnelHandler", () => {
+    it("POST /__enpilink/tunnel starts the tunnel and returns the current state", async () => {
+        const { port, child } = await listenWithHandler();
+        const res = await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "POST",
+        });
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({
+            status: "starting",
+            message: "Starting tunnel…",
+        });
+        expect(child.kill).not.toHaveBeenCalled();
+    });
+    it("POST /__enpilink/tunnel is idempotent — second call does not respawn", async () => {
+        const { port, manager } = await listenWithHandler();
+        const startSpy = vi.spyOn(manager, "start");
+        await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "POST",
+        });
+        await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "POST",
+        });
+        expect(startSpy).toHaveBeenCalledTimes(2);
+        // Manager.start() is internally idempotent (verified in tunnel.test.ts).
+    });
+    it("DELETE /__enpilink/tunnel stops the tunnel", async () => {
+        const { port, child } = await listenWithHandler();
+        await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "POST",
+        });
+        const res = await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "DELETE",
+        });
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({ status: "idle" });
+        expect(child.kill).toHaveBeenCalled();
+    });
+    it("GET /__enpilink/tunnel/events streams the current state on connect", async () => {
+        const { port, child } = await listenWithHandler();
+        await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "POST",
+        });
+        child.stdout.emit("data", Buffer.from("https://abc123.srv.us/\n"));
+        const res = await fetch(`http://localhost:${port}/__enpilink/tunnel/events`);
+        expect(res.headers.get("content-type")).toMatch(/text\/event-stream/);
+        expect(res.body).toBeTruthy();
+        const reader = res.body.getReader();
+        const { value } = await reader.read();
+        const chunk = new TextDecoder().decode(value);
+        expect(chunk).toContain("event: state");
+        expect(chunk).toContain('"status":"connected"');
+        expect(chunk).toContain('"url":"https://abc123.srv.us"');
+        await reader.cancel();
+    });
+    it("GET /__enpilink/tunnel/events surfaces a drop as reconnecting state with the stderr detail", async () => {
+        const { port, child } = await listenWithHandler();
+        await fetch(`http://localhost:${port}/__enpilink/tunnel`, {
+            method: "POST",
+        });
+        child.stderr.emit("data", Buffer.from("boom: tunnel auth failed\n"));
+        // While the tunnel should be up, an unexpected close triggers auto-reconnect
+        // (it does NOT terminate as a hard error).
+        child.emit("close", 1);
+        const res = await fetch(`http://localhost:${port}/__enpilink/tunnel/events`);
+        expect(res.headers.get("content-type")).toMatch(/text\/event-stream/);
+        expect(res.body).toBeTruthy();
+        const reader = res.body.getReader();
+        const { value } = await reader.read();
+        const chunk = new TextDecoder().decode(value);
+        expect(chunk).toContain("event: state");
+        expect(chunk).toContain('"status":"reconnecting"');
+        expect(chunk).toContain("boom: tunnel auth failed");
+        await reader.cancel();
+    });
+});
+//# sourceMappingURL=tunnel-handler.test.js.map

package/dist/cli/tunnel-handler.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-handler.test.js","sourceRoot":"","sources":["../../src/cli/tunnel-handler.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { EventEmitter } from \"node:events\";\nimport http from \"node:http\";\nimport { Readable } from \"node:stream\";\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { TunnelManager } from \"./tunnel.js\";\nimport { createTunnelHandler } from \"./tunnel-handler.js\";\n\nlet openServer: http.Server | undefined;\nafterEach(() => openServer?.close());\n\ntype FakeChild = EventEmitter & {\n  stdout: Readable;\n  stderr: Readable;\n  kill: ReturnType<typeof vi.fn<() => boolean>>;\n};\n\nfunction makeFakeChild(): FakeChild {\n  const child = new EventEmitter() as FakeChild;\n  child.stdout = new Readable({ read() {} });\n  child.stderr = new Readable({ read() {} });\n  child.kill = vi.fn<() => boolean>(() => true);\n  return child;\n}\n\nasync function listen(handler: http.RequestListener) {\n  const server = http.createServer(handler);\n  await new Promise<void>((resolve) => server.listen(0, resolve));\n  const port = (server.address() as { port: number }).port;\n  return { port, server };\n}\n\nasync function listenWithHandler() {\n  const child = makeFakeChild();\n  const manager = new TunnelManager({\n    getPort: () => 3000,\n    spawn: () => child,\n  });\n  const { port, server } = await listen(createTunnelHandler(manager));\n  openServer = server;\n  return { port, child, manager };\n}\n\ndescribe(\"createTunnelHandler\", () => {\n  it(\"POST /__enpilink/tunnel starts the tunnel and returns the current state\", async () => {\n    const { port, child } = await listenWithHandler();\n\n    const res = await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"POST\",\n    });\n    expect(res.status).toBe(200);\n    expect(await res.json()).toEqual({\n      status: \"starting\",\n      message: \"Starting tunnel…\",\n    });\n    expect(child.kill).not.toHaveBeenCalled();\n  });\n\n  it(\"POST /__enpilink/tunnel is idempotent — second call does not respawn\", async () => {\n    const { port, manager } = await listenWithHandler();\n    const startSpy = vi.spyOn(manager, \"start\");\n\n    await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"POST\",\n    });\n    await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"POST\",\n    });\n\n    expect(startSpy).toHaveBeenCalledTimes(2);\n    // Manager.start() is internally idempotent (verified in tunnel.test.ts).\n  });\n\n  it(\"DELETE /__enpilink/tunnel stops the tunnel\", async () => {\n    const { port, child } = await listenWithHandler();\n    await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"POST\",\n    });\n\n    const res = await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"DELETE\",\n    });\n    expect(res.status).toBe(200);\n    expect(await res.json()).toEqual({ status: \"idle\" });\n    expect(child.kill).toHaveBeenCalled();\n  });\n\n  it(\"GET /__enpilink/tunnel/events streams the current state on connect\", async () => {\n    const { port, child } = await listenWithHandler();\n    await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"POST\",\n    });\n    child.stdout.emit(\"data\", Buffer.from(\"https://abc123.srv.us/\\n\"));\n\n    const res = await fetch(\n      `http://localhost:${port}/__enpilink/tunnel/events`,\n    );\n    expect(res.headers.get(\"content-type\")).toMatch(/text\\/event-stream/);\n    expect(res.body).toBeTruthy();\n\n    const reader = (res.body as ReadableStream<Uint8Array>).getReader();\n    const { value } = await reader.read();\n    const chunk = new TextDecoder().decode(value);\n\n    expect(chunk).toContain(\"event: state\");\n    expect(chunk).toContain('\"status\":\"connected\"');\n    expect(chunk).toContain('\"url\":\"https://abc123.srv.us\"');\n\n    await reader.cancel();\n  });\n\n  it(\"GET /__enpilink/tunnel/events surfaces a drop as reconnecting state with the stderr detail\", async () => {\n    const { port, child } = await listenWithHandler();\n    await fetch(`http://localhost:${port}/__enpilink/tunnel`, {\n      method: \"POST\",\n    });\n    child.stderr.emit(\"data\", Buffer.from(\"boom: tunnel auth failed\\n\"));\n    // While the tunnel should be up, an unexpected close triggers auto-reconnect\n    // (it does NOT terminate as a hard error).\n    child.emit(\"close\", 1);\n\n    const res = await fetch(\n      `http://localhost:${port}/__enpilink/tunnel/events`,\n    );\n    expect(res.headers.get(\"content-type\")).toMatch(/text\\/event-stream/);\n    expect(res.body).toBeTruthy();\n\n    const reader = (res.body as ReadableStream<Uint8Array>).getReader();\n    const { value } = await reader.read();\n    const chunk = new TextDecoder().decode(value);\n\n    expect(chunk).toContain(\"event: state\");\n    expect(chunk).toContain('\"status\":\"reconnecting\"');\n    expect(chunk).toContain(\"boom: tunnel auth failed\");\n\n    await reader.cancel();\n  });\n});\n"]}

package/dist/cli/tunnel-providers/index.d.ts

@@ -0,0 +1,5 @@
+import type { TunnelProvider } from "./types.js";
+export { parseSrvUsLine, srvUsProvider, srvUsSshArgs } from "./srv-us.js";
+export type { ParsedStdoutEvent, TunnelChildProcess, TunnelProvider, } from "./types.js";
+/** The default tunnel provider. Account-free, only needs `ssh`. */
+export declare const defaultProvider: TunnelProvider;

package/dist/cli/tunnel-providers/index.js

@@ -0,0 +1,5 @@
+import { srvUsProvider } from "./srv-us.js";
+export { parseSrvUsLine, srvUsProvider, srvUsSshArgs } from "./srv-us.js";
+/** The default tunnel provider. Account-free, only needs `ssh`. */
+export const defaultProvider = srvUsProvider;
+//# sourceMappingURL=index.js.map

package/dist/cli/tunnel-providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/tunnel-providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO1E,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAmB,aAAa,CAAC","sourcesContent":["import { srvUsProvider } from \"./srv-us.js\";\nimport type { TunnelProvider } from \"./types.js\";\n\nexport { parseSrvUsLine, srvUsProvider, srvUsSshArgs } from \"./srv-us.js\";\nexport type {\n  ParsedStdoutEvent,\n  TunnelChildProcess,\n  TunnelProvider,\n} from \"./types.js\";\n\n/** The default tunnel provider. Account-free, only needs `ssh`. */\nexport const defaultProvider: TunnelProvider = srvUsProvider;\n"]}

package/dist/cli/tunnel-providers/srv-us.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedStdoutEvent, TunnelProvider } from "./types.js";
+export declare function parseSrvUsLine(line: string): ParsedStdoutEvent | null;
+/**
+ * Build the ssh argv for a srv.us reverse tunnel.
+ *  - `-i <keyPath>`: use enpilink's dedicated key (stable URL).
+ *  - `StrictHostKeyChecking=accept-new`: trust srv.us on first connect, no prompt.
+ *  - `ServerAliveInterval=30` / `ServerAliveCountMax=3`: detect dead links fast
+ *    so auto-reconnect kicks in.
+ *  - `ExitOnForwardFailure=yes`: fail (and let us reconnect) instead of hanging
+ *    if the remote forward can't be set up.
+ *  - `-R 1:localhost:<port>`: reverse-forward srv.us tunnel #1 to the dev server.
+ */
+export declare function srvUsSshArgs(port: number, keyPath: string): string[];
+/**
+ * The default, account-free provider. Spawns `ssh … srv.us -R 1:localhost:<port>`
+ * after lazily ensuring the ed25519 key exists.
+ */
+export declare const srvUsProvider: TunnelProvider;

package/dist/cli/tunnel-providers/srv-us.js

@@ -0,0 +1,66 @@
+import spawn from "cross-spawn";
+import { ensureSshKey } from "../ensure-ssh-key.js";
+/**
+ * Matches a srv.us public URL anywhere in a stdout line. srv.us announces each
+ * forwarded port as `<n>: https://<hash>.srv.us/` (live-confirmed 2026-06-14),
+ * with NO `Forwarding:` prefix — so we scan for the URL itself anywhere in the
+ * line. Tolerant of GitHub/GitLab-style friendly subdomains (any host ending in
+ * `.srv.us`) and an optional trailing slash.
+ */
+const SRV_US_URL_RE = /(https?:\/\/[a-z0-9.-]+\.srv\.us)\/?/i;
+export function parseSrvUsLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const match = trimmed.match(SRV_US_URL_RE);
+    if (match?.[1]) {
+        return { kind: "connected", url: match[1].replace(/\/$/, "") };
+    }
+    return { kind: "starting", message: trimmed };
+}
+/**
+ * Build the ssh argv for a srv.us reverse tunnel.
+ *  - `-i <keyPath>`: use enpilink's dedicated key (stable URL).
+ *  - `StrictHostKeyChecking=accept-new`: trust srv.us on first connect, no prompt.
+ *  - `ServerAliveInterval=30` / `ServerAliveCountMax=3`: detect dead links fast
+ *    so auto-reconnect kicks in.
+ *  - `ExitOnForwardFailure=yes`: fail (and let us reconnect) instead of hanging
+ *    if the remote forward can't be set up.
+ *  - `-R 1:localhost:<port>`: reverse-forward srv.us tunnel #1 to the dev server.
+ */
+export function srvUsSshArgs(port, keyPath) {
+    return [
+        "-i",
+        keyPath,
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-o",
+        "ServerAliveInterval=30",
+        "-o",
+        "ServerAliveCountMax=3",
+        "-o",
+        "ExitOnForwardFailure=yes",
+        "srv.us",
+        "-R",
+        `1:localhost:${port}`,
+    ];
+}
+/**
+ * The default, account-free provider. Spawns `ssh … srv.us -R 1:localhost:<port>`
+ * after lazily ensuring the ed25519 key exists.
+ */
+export const srvUsProvider = {
+    name: "srv.us",
+    ensure() {
+        ensureSshKey();
+    },
+    spawn(port) {
+        const keyPath = ensureSshKey();
+        return spawn("ssh", srvUsSshArgs(port, keyPath), {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    },
+    parseLine: parseSrvUsLine,
+};
+//# sourceMappingURL=srv-us.js.map

package/dist/cli/tunnel-providers/srv-us.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"srv-us.js","sourceRoot":"","sources":["../../../src/cli/tunnel-providers/srv-us.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,aAAa,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOpD;;;;;;GAMG;AACH,MAAM,aAAa,GAAG,uCAAuC,CAAC;AAE9D,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC3C,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAe;IACxD,OAAO;QACL,IAAI;QACJ,OAAO;QACP,IAAI;QACJ,kCAAkC;QAClC,IAAI;QACJ,wBAAwB;QACxB,IAAI;QACJ,uBAAuB;QACvB,IAAI;QACJ,0BAA0B;QAC1B,QAAQ;QACR,IAAI;QACJ,eAAe,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,QAAQ;IACd,MAAM;QACJ,YAAY,EAAE,CAAC;IACjB,CAAC;IACD,KAAK,CAAC,IAAY;QAChB,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE;YAC/C,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IACD,SAAS,EAAE,cAAc;CAC1B,CAAC","sourcesContent":["import spawn from \"cross-spawn\";\nimport { ensureSshKey } from \"../ensure-ssh-key.js\";\nimport type {\n  ParsedStdoutEvent,\n  TunnelChildProcess,\n  TunnelProvider,\n} from \"./types.js\";\n\n/**\n * Matches a srv.us public URL anywhere in a stdout line. srv.us announces each\n * forwarded port as `<n>: https://<hash>.srv.us/` (live-confirmed 2026-06-14),\n * with NO `Forwarding:` prefix — so we scan for the URL itself anywhere in the\n * line. Tolerant of GitHub/GitLab-style friendly subdomains (any host ending in\n * `.srv.us`) and an optional trailing slash.\n */\nconst SRV_US_URL_RE = /(https?:\\/\\/[a-z0-9.-]+\\.srv\\.us)\\/?/i;\n\nexport function parseSrvUsLine(line: string): ParsedStdoutEvent | null {\n  const trimmed = line.trim();\n  if (!trimmed) {\n    return null;\n  }\n\n  const match = trimmed.match(SRV_US_URL_RE);\n  if (match?.[1]) {\n    return { kind: \"connected\", url: match[1].replace(/\\/$/, \"\") };\n  }\n  return { kind: \"starting\", message: trimmed };\n}\n\n/**\n * Build the ssh argv for a srv.us reverse tunnel.\n *  - `-i <keyPath>`: use enpilink's dedicated key (stable URL).\n *  - `StrictHostKeyChecking=accept-new`: trust srv.us on first connect, no prompt.\n *  - `ServerAliveInterval=30` / `ServerAliveCountMax=3`: detect dead links fast\n *    so auto-reconnect kicks in.\n *  - `ExitOnForwardFailure=yes`: fail (and let us reconnect) instead of hanging\n *    if the remote forward can't be set up.\n *  - `-R 1:localhost:<port>`: reverse-forward srv.us tunnel #1 to the dev server.\n */\nexport function srvUsSshArgs(port: number, keyPath: string): string[] {\n  return [\n    \"-i\",\n    keyPath,\n    \"-o\",\n    \"StrictHostKeyChecking=accept-new\",\n    \"-o\",\n    \"ServerAliveInterval=30\",\n    \"-o\",\n    \"ServerAliveCountMax=3\",\n    \"-o\",\n    \"ExitOnForwardFailure=yes\",\n    \"srv.us\",\n    \"-R\",\n    `1:localhost:${port}`,\n  ];\n}\n\n/**\n * The default, account-free provider. Spawns `ssh … srv.us -R 1:localhost:<port>`\n * after lazily ensuring the ed25519 key exists.\n */\nexport const srvUsProvider: TunnelProvider = {\n  name: \"srv.us\",\n  ensure() {\n    ensureSshKey();\n  },\n  spawn(port: number): TunnelChildProcess {\n    const keyPath = ensureSshKey();\n    return spawn(\"ssh\", srvUsSshArgs(port, keyPath), {\n      stdio: [\"ignore\", \"pipe\", \"pipe\"],\n    });\n  },\n  parseLine: parseSrvUsLine,\n};\n"]}

package/dist/cli/tunnel-providers/srv-us.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/tunnel-providers/srv-us.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { parseSrvUsLine, srvUsProvider, srvUsSshArgs } from "./srv-us.js";
+describe("parseSrvUsLine", () => {
+    it("extracts the URL from srv.us's real on-connect line (live-confirmed format)", () => {
+        // Confirmed against a live srv.us tunnel on 2026-06-14: each forwarded port
+        // is announced as `<n>: https://<hash>.srv.us/`.
+        expect(parseSrvUsLine("1: https://65xgxz2werq5kx7rj6fjndeol4.srv.us/")).toEqual({
+            kind: "connected",
+            url: "https://65xgxz2werq5kx7rj6fjndeol4.srv.us",
+        });
+    });
+    it("extracts a hash subdomain srv.us URL printed bare", () => {
+        expect(parseSrvUsLine("https://qp556ma755ktlag5b2xyt334ae.srv.us/")).toEqual({
+            kind: "connected",
+            url: "https://qp556ma755ktlag5b2xyt334ae.srv.us",
+        });
+    });
+    it("extracts the URL even when embedded in surrounding text", () => {
+        expect(parseSrvUsLine("Your service is available at https://abc.srv.us")).toEqual({
+            kind: "connected",
+            url: "https://abc.srv.us",
+        });
+    });
+    it("accepts friendly github/gitlab-style subdomains", () => {
+        expect(parseSrvUsLine("https://my-user.srv.us/")).toEqual({
+            kind: "connected",
+            url: "https://my-user.srv.us",
+        });
+    });
+    it("strips a trailing slash", () => {
+        expect(parseSrvUsLine("https://abc.srv.us/")).toEqual({
+            kind: "connected",
+            url: "https://abc.srv.us",
+        });
+    });
+    it("treats non-URL output as a starting/progress message", () => {
+        expect(parseSrvUsLine("Warning: Permanently added 'srv.us' to known hosts.")).toEqual({
+            kind: "starting",
+            message: "Warning: Permanently added 'srv.us' to known hosts.",
+        });
+    });
+    it("returns null for blank lines", () => {
+        expect(parseSrvUsLine("")).toBeNull();
+        expect(parseSrvUsLine("   ")).toBeNull();
+    });
+});
+describe("srvUsSshArgs", () => {
+    it("builds the reverse-tunnel ssh argv with hardening options", () => {
+        expect(srvUsSshArgs(63189, "/home/u/.enpilink/id_ed25519")).toEqual([
+            "-i",
+            "/home/u/.enpilink/id_ed25519",
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            "-o",
+            "ServerAliveInterval=30",
+            "-o",
+            "ServerAliveCountMax=3",
+            "-o",
+            "ExitOnForwardFailure=yes",
+            "srv.us",
+            "-R",
+            "1:localhost:63189",
+        ]);
+    });
+});
+describe("srvUsProvider", () => {
+    it("is named srv.us and exposes ensure + spawn + parseLine", () => {
+        expect(srvUsProvider.name).toBe("srv.us");
+        expect(typeof srvUsProvider.ensure).toBe("function");
+        expect(typeof srvUsProvider.spawn).toBe("function");
+        expect(srvUsProvider.parseLine).toBe(parseSrvUsLine);
+    });
+});
+//# sourceMappingURL=srv-us.test.js.map

package/dist/cli/tunnel-providers/srv-us.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"srv-us.test.js","sourceRoot":"","sources":["../../../src/cli/tunnel-providers/srv-us.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport { parseSrvUsLine, srvUsProvider, srvUsSshArgs } from \"./srv-us.js\";\n\ndescribe(\"parseSrvUsLine\", () => {\n  it(\"extracts the URL from srv.us's real on-connect line (live-confirmed format)\", () => {\n    // Confirmed against a live srv.us tunnel on 2026-06-14: each forwarded port\n    // is announced as `<n>: https://<hash>.srv.us/`.\n    expect(\n      parseSrvUsLine(\"1: https://65xgxz2werq5kx7rj6fjndeol4.srv.us/\"),\n    ).toEqual({\n      kind: \"connected\",\n      url: \"https://65xgxz2werq5kx7rj6fjndeol4.srv.us\",\n    });\n  });\n\n  it(\"extracts a hash subdomain srv.us URL printed bare\", () => {\n    expect(\n      parseSrvUsLine(\"https://qp556ma755ktlag5b2xyt334ae.srv.us/\"),\n    ).toEqual({\n      kind: \"connected\",\n      url: \"https://qp556ma755ktlag5b2xyt334ae.srv.us\",\n    });\n  });\n\n  it(\"extracts the URL even when embedded in surrounding text\", () => {\n    expect(\n      parseSrvUsLine(\"Your service is available at https://abc.srv.us\"),\n    ).toEqual({\n      kind: \"connected\",\n      url: \"https://abc.srv.us\",\n    });\n  });\n\n  it(\"accepts friendly github/gitlab-style subdomains\", () => {\n    expect(parseSrvUsLine(\"https://my-user.srv.us/\")).toEqual({\n      kind: \"connected\",\n      url: \"https://my-user.srv.us\",\n    });\n  });\n\n  it(\"strips a trailing slash\", () => {\n    expect(parseSrvUsLine(\"https://abc.srv.us/\")).toEqual({\n      kind: \"connected\",\n      url: \"https://abc.srv.us\",\n    });\n  });\n\n  it(\"treats non-URL output as a starting/progress message\", () => {\n    expect(\n      parseSrvUsLine(\"Warning: Permanently added 'srv.us' to known hosts.\"),\n    ).toEqual({\n      kind: \"starting\",\n      message: \"Warning: Permanently added 'srv.us' to known hosts.\",\n    });\n  });\n\n  it(\"returns null for blank lines\", () => {\n    expect(parseSrvUsLine(\"\")).toBeNull();\n    expect(parseSrvUsLine(\"   \")).toBeNull();\n  });\n});\n\ndescribe(\"srvUsSshArgs\", () => {\n  it(\"builds the reverse-tunnel ssh argv with hardening options\", () => {\n    expect(srvUsSshArgs(63189, \"/home/u/.enpilink/id_ed25519\")).toEqual([\n      \"-i\",\n      \"/home/u/.enpilink/id_ed25519\",\n      \"-o\",\n      \"StrictHostKeyChecking=accept-new\",\n      \"-o\",\n      \"ServerAliveInterval=30\",\n      \"-o\",\n      \"ServerAliveCountMax=3\",\n      \"-o\",\n      \"ExitOnForwardFailure=yes\",\n      \"srv.us\",\n      \"-R\",\n      \"1:localhost:63189\",\n    ]);\n  });\n});\n\ndescribe(\"srvUsProvider\", () => {\n  it(\"is named srv.us and exposes ensure + spawn + parseLine\", () => {\n    expect(srvUsProvider.name).toBe(\"srv.us\");\n    expect(typeof srvUsProvider.ensure).toBe(\"function\");\n    expect(typeof srvUsProvider.spawn).toBe(\"function\");\n    expect(srvUsProvider.parseLine).toBe(parseSrvUsLine);\n  });\n});\n"]}

package/dist/cli/tunnel-providers/types.d.ts

@@ -0,0 +1,49 @@
+import type { Readable } from "node:stream";
+/**
+ * A spawned tunnel child process. Intentionally a structural subset of
+ * `ChildProcess` so it can be faked in tests without a real subprocess.
+ */
+export type TunnelChildProcess = {
+    stdout: Pick<Readable, "on"> | null;
+    stderr: Pick<Readable, "on"> | null;
+    kill: (signal?: NodeJS.Signals | number) => boolean;
+    on(event: "error", listener: (err: Error) => void): unknown;
+    on(event: "close", listener: (code: number | null) => void): unknown;
+};
+/**
+ * The result of parsing a single line of a provider's stdout.
+ *  - `connected`: the public URL is now known and the tunnel is live.
+ *  - `starting`: progress text emitted before the URL is known.
+ */
+export type ParsedStdoutEvent = {
+    kind: "connected";
+    url: string;
+} | {
+    kind: "starting";
+    message: string;
+};
+/**
+ * A pluggable tunnel backend. Encapsulates BOTH how the tunnel process is
+ * spawned AND how its stdout is parsed for the public URL, since each provider
+ * (srv.us, localhost.run, bore, cloudflared…) prints a different format.
+ *
+ * `TunnelManager` is provider-agnostic: it owns lifecycle/state/reconnect and
+ * delegates spawning + line parsing to the provider. Adding a provider therefore
+ * never touches the manager or any caller.
+ */
+export interface TunnelProvider {
+    /** Stable identifier, e.g. "srv.us". */
+    readonly name: string;
+    /**
+     * Ensure any prerequisites exist (e.g. an SSH key). Best-effort and lazy;
+     * called once before the first spawn. Optional — providers with no setup omit it.
+     */
+    ensure?(): void | Promise<void>;
+    /** Spawn the tunnel for a local port and return the child process. */
+    spawn(port: number): TunnelChildProcess;
+    /**
+     * Parse one stdout line. Return `null` for lines that carry no signal so they
+     * can be ignored (or surfaced only under `--verbose`).
+     */
+    parseLine(line: string): ParsedStdoutEvent | null;
+}

package/dist/cli/tunnel-providers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/tunnel-providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cli/tunnel-providers/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Readable } from \"node:stream\";\n\n/**\n * A spawned tunnel child process. Intentionally a structural subset of\n * `ChildProcess` so it can be faked in tests without a real subprocess.\n */\nexport type TunnelChildProcess = {\n  stdout: Pick<Readable, \"on\"> | null;\n  stderr: Pick<Readable, \"on\"> | null;\n  kill: (signal?: NodeJS.Signals | number) => boolean;\n  on(event: \"error\", listener: (err: Error) => void): unknown;\n  on(event: \"close\", listener: (code: number | null) => void): unknown;\n};\n\n/**\n * The result of parsing a single line of a provider's stdout.\n *  - `connected`: the public URL is now known and the tunnel is live.\n *  - `starting`: progress text emitted before the URL is known.\n */\nexport type ParsedStdoutEvent =\n  | { kind: \"connected\"; url: string }\n  | { kind: \"starting\"; message: string };\n\n/**\n * A pluggable tunnel backend. Encapsulates BOTH how the tunnel process is\n * spawned AND how its stdout is parsed for the public URL, since each provider\n * (srv.us, localhost.run, bore, cloudflared…) prints a different format.\n *\n * `TunnelManager` is provider-agnostic: it owns lifecycle/state/reconnect and\n * delegates spawning + line parsing to the provider. Adding a provider therefore\n * never touches the manager or any caller.\n */\nexport interface TunnelProvider {\n  /** Stable identifier, e.g. \"srv.us\". */\n  readonly name: string;\n  /**\n   * Ensure any prerequisites exist (e.g. an SSH key). Best-effort and lazy;\n   * called once before the first spawn. Optional — providers with no setup omit it.\n   */\n  ensure?(): void | Promise<void>;\n  /** Spawn the tunnel for a local port and return the child process. */\n  spawn(port: number): TunnelChildProcess;\n  /**\n   * Parse one stdout line. Return `null` for lines that carry no signal so they\n   * can be ignored (or surfaced only under `--verbose`).\n   */\n  parseLine(line: string): ParsedStdoutEvent | null;\n}\n"]}

package/dist/cli/tunnel.d.ts

@@ -0,0 +1,75 @@
+import { EventEmitter } from "node:events";
+import { type ParsedStdoutEvent, type TunnelChildProcess, type TunnelProvider } from "./tunnel-providers/index.js";
+export type { ParsedStdoutEvent, TunnelChildProcess, TunnelProvider, } from "./tunnel-providers/index.js";
+export type TunnelState = {
+    status: "idle";
+} | {
+    status: "starting";
+    message: string;
+} | {
+    status: "connected";
+    url: string;
+} | {
+    status: "reconnecting";
+    message: string;
+} | {
+    status: "error";
+    message: string;
+};
+/**
+ * Parse a single stdout line using the default (srv.us) provider. Kept as a
+ * standalone export for tests and callers that want the default parser.
+ */
+export declare function parseStdoutLine(line: string): ParsedStdoutEvent | null;
+export type TunnelActivity = {
+    time: string;
+    text: string;
+    level: "log" | "error";
+};
+/**
+ * Legacy spawn injection. A bare `(port) => child` function; when provided it is
+ * adapted into a provider that uses the default (srv.us) line parser. New code
+ * should pass a full `provider` instead.
+ */
+export type SpawnFn = (port: number) => TunnelChildProcess;
+export declare class TunnelManager extends EventEmitter {
+    private state;
+    private child;
+    private timeout;
+    private reconnectTimer;
+    private stderrBuffer;
+    private connected;
+    /** True between start() and stop(): governs whether drops trigger reconnect. */
+    private wantUp;
+    private reconnectAttempts;
+    private ensured;
+    private readonly getPort;
+    private readonly provider;
+    constructor(opts: {
+        getPort: () => number;
+        provider?: TunnelProvider;
+        /** @deprecated pass `provider` instead. */
+        spawn?: SpawnFn;
+    });
+    getState(): TunnelState;
+    subscribe(listener: (state: TunnelState) => void): () => void;
+    start(): void;
+    /**
+     * Spawn (or respawn) the tunnel child. `initialState` is what we broadcast
+     * while waiting for the URL — "starting" on first launch, "reconnecting" after
+     * a drop. Ensures provider prerequisites (e.g. SSH key) once, lazily.
+     */
+    private spawnChild;
+    /**
+     * After an unexpected drop, broadcast "reconnecting" and respawn after an
+     * exponential backoff (capped). Reset attempts once a connection succeeds.
+     */
+    private scheduleReconnect;
+    stop(): void;
+    private handleStdout;
+    private handleStderr;
+    private setState;
+    private emitActivity;
+    private clearConnectTimeout;
+    private clearReconnectTimer;
+}