traforo 0.2.5 → 0.4.0

package/README

@@ -14,15 +14,21 @@ Expose a local server:
 
     traforo -p 3000
 
+Or let traforo auto-detect the port from a dev server command:
+
+    traforo -- pnpm dev
+    traforo -- next start
+
 With a custom tunnel ID (only for services safe to expose publicly):
 
     traforo -p 3000 -t my-app
 
 Run a command and tunnel it:
 
-    traforo -p 3000 -- next start
-    traforo -p 3000 -- pnpm dev
+    traforo -- next start
+    traforo -- pnpm dev
     traforo -p 5173 -- vite
+    traforo -p 3000 -- next start    # explicit port overrides auto-detection
 
 The tunnel URL will be:
 
@@ -30,7 +36,7 @@ The tunnel URL will be:
 
 ## OPTIONS
 
-    -p, --port <port>          Local port to expose (required)
+    -p, --port <port>          Local port to expose (optional with -- command)
     -t, --tunnel-id [id]       Custom tunnel ID (prefer random default)
     -c, --cache [key]          Enable edge caching (optional partition key)
     --password <password>      Protect the tunnel with a password
@@ -39,6 +45,20 @@ The tunnel URL will be:
     --help                     Show help
     --version                  Show version
 
+## AUTO PORT DETECTION
+
+When you pass a command after `--`, traforo can detect the local port from the
+process output. It watches stdout and stderr for addresses like these:
+
+    http://localhost:3000
+    localhost:5173
+    127.0.0.1:8080
+    0.0.0.0:4321
+
+This works well with common dev servers that print their local URL when they start.
+
+If you also pass `-p`, traforo uses that explicit port instead of auto-detecting.
+
 ## EDGE CACHING
 
 Cache responses at Cloudflare's edge so repeat requests never hit your
@@ -91,6 +111,29 @@ instructions to pass the password as a cookie:
 WebSocket upgrade requests without the correct cookie are rejected with
 close code 4013.
 
+## TRAFORO_URL ENVIRONMENT VARIABLE
+
+When you run a command after `--`, traforo injects `TRAFORO_URL` into the
+child process environment with the full public tunnel URL:
+
+    TRAFORO_URL=https://{tunnel-id}-tunnel.traforo.dev
+
+Your app can read it directly:
+
+    const baseUrl = process.env.TRAFORO_URL
+
+To remap it to a custom env var your app already uses, prefix the command:
+
+    traforo -p 3000 -- sh -c 'APP_URL=$TRAFORO_URL exec node server.js'
+    traforo -p 3000 -- sh -c 'NEXT_PUBLIC_URL=$TRAFORO_URL exec next dev'
+    traforo -p 3000 -- sh -c 'VITE_BASE_URL=$TRAFORO_URL exec vite'
+
+Or set it in your .env / startup script and let traforo override only
+`TRAFORO_URL`, reading it where needed:
+
+    // next.config.js
+    const baseUrl = process.env.APP_URL || process.env.TRAFORO_URL || 'http://localhost:3000'
+
 ## HOW IT WORKS
 
 1. Local client connects to Cloudflare Durable Object via WebSocket

package/dist/cli.js

@@ -5,7 +5,7 @@ const { command, argv } = parseCommandFromArgv(process.argv);
 const cli = goke(CLI_NAME);
 cli
     .command('', 'Expose a local port via tunnel')
-    .option('-p, --port <port>', 'Local port to expose (required)')
+    .option('-p, --port <port>', 'Local port to expose (optional when using -- command)')
     .option('-t, --tunnel-id [id]', 'Custom tunnel ID (only for services safe to expose publicly; prefer random default)')
     .option('-h, --host [host]', 'Local host (default: localhost)')
     .option('-s, --server [url]', 'Tunnel server URL')
@@ -13,33 +13,37 @@ cli
     .option('--password <password>', 'Protect the tunnel with a password (visitors must enter it to access)')
     .option('-k, --kill', 'Kill any existing process on the port before starting')
     .example(`${CLI_NAME} -p 3000`)
+    .example(`${CLI_NAME} -- next start`)
+    .example(`${CLI_NAME} -- pnpm dev`)
     .example(`${CLI_NAME} -p 3000 -- next start`)
-    .example(`${CLI_NAME} -p 3000 -- pnpm dev`)
     .example(`${CLI_NAME} -p 5173 -t my-app -- vite`)
     .example(`${CLI_NAME} -p 3000 --cache`)
     .example(`${CLI_NAME} -p 3000 --cache v2`)
     .action(async (options) => {
-    if (!options.port) {
-        console.error('Error: --port is required');
-        console.error(`\nUsage: ${CLI_NAME} -p <port> [-- command]`);
+    if (!options.port && command.length === 0) {
+        console.error('Error: --port is required unless a command is provided after --');
+        console.error(`\nUsage: ${CLI_NAME} [-p <port>] [-- command]`);
         process.exit(1);
     }
-    const port = parseInt(options.port, 10);
-    if (isNaN(port) || port < 1 || port > 65535) {
-        console.error(`Error: Invalid port number: ${options.port}`);
+    if (options.kill && !options.port) {
+        console.error('Error: --kill requires --port');
         process.exit(1);
     }
-    // --cache with no value comes as boolean true, --cache v2 comes as string "v2"
-    const cacheKey = options.cache
-        ? typeof options.cache === 'string'
-            ? options.cache
-            : 'default'
-        : undefined;
+    let port;
+    if (options.port) {
+        port = parseInt(options.port, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error(`Error: Invalid port number: ${options.port}`);
+            process.exit(1);
+        }
+    }
+    // --cache bare (`''`) → 'default', --cache v2 → 'v2', omitted → undefined
+    const cacheKey = options.cache === '' ? 'default' : options.cache || undefined;
     await runTunnel({
         port,
-        tunnelId: options.tunnelId,
-        localHost: options.host,
-        serverUrl: options.server,
+        tunnelId: options.tunnelId || undefined,
+        localHost: options.host || undefined,
+        serverUrl: options.server || undefined,
         command: command.length > 0 ? command : undefined,
         cacheKey,
         password: options.password,

package/dist/client.d.ts

@@ -6,7 +6,7 @@ type TunnelClientOptions = {
     localPort: number;
     /** Local host (default: localhost) */
     localHost?: string;
-    /** Base domain for tunnel URLs (default: kimaki.xyz) */
+    /** Base domain for tunnel URLs (default: kimaki.dev) */
     baseDomain?: string;
     /** Tunnel server URL (default: wss://{tunnelId}-tunnel.{baseDomain}) */
     serverUrl?: string;

package/dist/run-tunnel.d.ts

@@ -1,9 +1,9 @@
 export declare const CLI_NAME = "traforo";
-export declare function createRandomTunnelId({ port }: {
-    port: number;
+export declare function createRandomTunnelId({ port }?: {
+    port?: number;
 }): string;
 export type RunTunnelOptions = {
-    port: number;
+    port?: number;
     tunnelId?: string;
     localHost?: string;
     baseDomain?: string;
@@ -16,6 +16,7 @@ export type RunTunnelOptions = {
     /** Kill any existing process on the port before starting */
     kill?: boolean;
 };
+export declare function detectPortFromText(text: string): number | null;
 /**
  * Parse argv to extract command after `--` separator.
  * Returns the command array and remaining argv without the command.

package/dist/run-tunnel.js

@@ -24,8 +24,27 @@ function shellQuote(args) {
         .join(' ');
 }
 const DEFAULT_TUNNEL_ID_BYTES = 10;
-export function createRandomTunnelId({ port }) {
-    return `${crypto.randomBytes(DEFAULT_TUNNEL_ID_BYTES).toString('hex')}-${port}`;
+export function createRandomTunnelId({ port } = {}) {
+    const randomId = crypto.randomBytes(DEFAULT_TUNNEL_ID_BYTES).toString('hex');
+    if (!port) {
+        return randomId;
+    }
+    return `${randomId}-${port}`;
+}
+const LOCAL_PORT_PATTERNS = [
+    /(?:https?:\/\/)?(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::\]):(\d{1,5})/i,
+    /\blistening(?:\s+at|\s+on)?\s+(?:https?:\/\/)?(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::\]):(\d{1,5})/i,
+    /\bport\s+(\d{1,5})\b/i,
+];
+export function detectPortFromText(text) {
+    for (const pattern of LOCAL_PORT_PATTERNS) {
+        const match = text.match(pattern);
+        const port = Number(match?.[1]);
+        if (port >= 1 && port <= 65535) {
+            return port;
+        }
+    }
+    return null;
 }
 /**
  * Wait for a port to be available (accepting connections).
@@ -54,6 +73,62 @@ async function waitForPort(port, host = 'localhost', timeoutMs = 60_000) {
         check();
     });
 }
+async function detectPortFromProcessOutput(child, timeoutMs = 60_000) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let outputBuffer = '';
+        const cleanup = () => {
+            clearTimeout(timeout);
+            child.off('exit', handleExit);
+            child.off('error', handleError);
+            child.stdout?.off('data', onStdout);
+            child.stderr?.off('data', onStderr);
+        };
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const scanChunk = (chunk) => {
+            outputBuffer += chunk.toString();
+            if (outputBuffer.length > 8_000) {
+                outputBuffer = outputBuffer.slice(-8_000);
+            }
+            const detectedPort = detectPortFromText(outputBuffer);
+            if (detectedPort) {
+                finish(detectedPort);
+            }
+        };
+        const handleExit = (code) => {
+            fail(new Error(`Command exited with code ${code} before a local port was detected`));
+        };
+        const handleError = (error) => {
+            fail(error);
+        };
+        const onStdout = (chunk) => {
+            scanChunk(chunk);
+        };
+        const onStderr = (chunk) => {
+            scanChunk(chunk);
+        };
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        const timeout = setTimeout(() => {
+            fail(new Error('Timeout waiting for command output to reveal a local port'));
+        }, timeoutMs);
+        child.on('exit', handleExit);
+        child.on('error', handleError);
+    });
+}
 /**
  * Check if a port is currently in use (something is listening).
  */
@@ -180,10 +255,18 @@ export function parseCommandFromArgv(argv) {
  */
 export async function runTunnel(options) {
     const localHost = options.localHost || 'localhost';
-    const port = options.port;
+    if (!options.port && !options.command?.length) {
+        console.error('Error: --port is required unless a command is provided after --');
+        process.exit(1);
+    }
+    if (options.kill && !options.port) {
+        console.error('Error: --kill requires --port');
+        process.exit(1);
+    }
+    let port = options.port;
     const tunnelId = options.tunnelId || createRandomTunnelId({ port });
     // Kill existing process on port if requested
-    if (options.kill) {
+    if (options.kill && port) {
         await killProcessOnPort(port);
         // Verify the port actually freed up before removing the lockfile
         if (await isPortInUse(port, localHost)) {
@@ -194,7 +277,7 @@ export async function runTunnel(options) {
         removeLockfile(port); // no ownership check — --kill is intentional
     }
     // Pre-flight: detect port conflict before spawning the child process
-    if (options.command && options.command.length > 0 && !options.kill) {
+    if (port && options.command && options.command.length > 0 && !options.kill) {
         const portBusy = await isPortInUse(port, localHost);
         if (portBusy) {
             const lock = readLockfile(port);
@@ -230,8 +313,7 @@ export async function runTunnel(options) {
                     console.error(`  Dir:     ${lock.cwd}`);
                     console.error(`  PID:     ${lock.tunnelPid}`);
                     console.error(`  Started: ${lock.startedAt}\n`);
-                    console.error(`Use --kill to terminate the existing process and start fresh while keeping the same tunnel URL,`);
-                    console.error(`or just reuse the tunnel URL above instead:\n`);
+                    console.error(`Use --kill to terminate the existing process and reuse the tunnel URL:`);
                     console.error(`  ${restartCommand}`);
                     process.exit(1);
                 }
@@ -248,17 +330,27 @@ export async function runTunnel(options) {
         }
     }
     let child = null;
+    // Compute tunnel URL early so it can be injected into the child env
+    const baseDomain = options.baseDomain || 'traforo.dev';
+    const tunnelUrl = `https://${tunnelId}-tunnel.${baseDomain}`;
     // If command provided, spawn child process with PORT env
     if (options.command && options.command.length > 0) {
         const cmd = options.command[0];
         const args = options.command.slice(1);
         console.log(`Starting: ${shellQuote(options.command)}`);
-        console.log(`PORT=${port}\n`);
+        if (port) {
+            console.log(`PORT=${port}`);
+        }
+        else {
+            console.log('Waiting for command output to reveal the local port...');
+        }
+        console.log('');
         const spawnedChild = spawn(cmd, args, {
-            stdio: 'inherit',
+            stdio: ['inherit', 'pipe', 'pipe'],
             env: {
                 ...process.env,
-                PORT: String(port),
+                ...(port ? { PORT: String(port) } : {}),
+                TRAFORO_URL: tunnelUrl,
                 // Disable clear/animations for common tools without lying about CI
                 FORCE_COLOR: '1',
                 VITE_CLS: 'false',
@@ -266,18 +358,28 @@ export async function runTunnel(options) {
             },
         });
         child = spawnedChild;
+        spawnedChild.stdout?.pipe(process.stdout);
+        spawnedChild.stderr?.pipe(process.stderr);
         spawnedChild.on('error', (err) => {
             console.error(`Failed to start command: ${err.message}`);
             process.exit(1);
         });
         spawnedChild.on('exit', (code) => {
             console.log(`\nCommand exited with code ${code}`);
-            removeLockfile(port, process.pid);
+            if (port) {
+                removeLockfile(port, process.pid);
+            }
             process.exit(code || 0);
         });
-        // Wait for port to be available before connecting tunnel
-        console.log(`Waiting for port ${port}...`);
         try {
+            if (!port) {
+                port = await detectPortFromProcessOutput(spawnedChild);
+                console.log(`\nDetected local port ${port}`);
+            }
+            if (!port) {
+                throw new Error('Failed to determine local port');
+            }
+            console.log(`Waiting for port ${port}...`);
             await waitForPort(port, localHost);
             console.log(`Port ${port} is ready!\n`);
         }
@@ -287,6 +389,10 @@ export async function runTunnel(options) {
             process.exit(1);
         }
     }
+    if (!port) {
+        console.error('Error: Failed to determine local port');
+        process.exit(1);
+    }
     const client = new TunnelClient({
         localPort: port,
         tunnelId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traforo",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "wrangler": "^4.24.3"
   },
   "dependencies": {
-    "goke": "^6.3.0",
+    "goke": "^6.8.0",
     "http-cache-semantics": "^4.2.0",
     "string-dedent": "^3.0.2",
     "ws": "^8.19.0"
@@ -49,8 +49,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.client.json && chmod +x dist/cli.js",
     "dev": "wrangler dev",
-    "deploy": "wrangler deploy",
-    "deploy:preview": "wrangler deploy --env preview",
+    "deploy": "wrangler deploy --env preview",
+    "deploy:prod": "wrangler deploy # only run if user asks specifically!",
     "typecheck": "tsc --noEmit",
     "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",