traforo 0.2.2 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kimaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/lockfile.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Port lockfile management for traforo tunnels.
+ *
+ * Stores one JSON file per active tunnel port in ~/.traforo/{port}.json.
+ * Used to detect port conflicts, show tunnel info in error messages,
+ * and let agents reuse existing tunnels instead of killing them.
+ *
+ * Override the lockfile directory with TRAFORO_HOME env var (useful for tests).
+ */
+export declare function getLockfileDir(): string;
+export type LockfileData = {
+    tunnelId: string;
+    tunnelUrl: string;
+    port: number;
+    /** PID of the traforo tunnel process (used for liveness checks) */
+    tunnelPid: number;
+    /** PID of the child server process, if any */
+    serverPid?: number;
+    command: string[] | undefined;
+    cwd: string;
+    startedAt: string;
+};
+export declare function writeLockfile(port: number, data: LockfileData): void;
+export declare function readLockfile(port: number): LockfileData | null;
+/**
+ * Remove lockfile only if it belongs to this traforo instance.
+ * Prevents a late-exiting old process from deleting a newer instance's lockfile.
+ */
+export declare function removeLockfile(port: number, expectedTunnelPid?: number): void;
+/**
+ * Check if the tunnel process in a lockfile is still alive.
+ * Uses tunnelPid (the traforo process) not serverPid, because
+ * the tunnel URL is only valid while the traforo process is running.
+ * Returns true (stale) if the tunnel process no longer exists.
+ */
+export declare function isLockfileStale(lock: LockfileData): boolean;

package/dist/lockfile.js

@@ -0,0 +1,73 @@
+/**
+ * Port lockfile management for traforo tunnels.
+ *
+ * Stores one JSON file per active tunnel port in ~/.traforo/{port}.json.
+ * Used to detect port conflicts, show tunnel info in error messages,
+ * and let agents reuse existing tunnels instead of killing them.
+ *
+ * Override the lockfile directory with TRAFORO_HOME env var (useful for tests).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export function getLockfileDir() {
+    return process.env.TRAFORO_HOME ?? path.join(os.homedir(), '.traforo');
+}
+function lockfilePath(port) {
+    return path.join(getLockfileDir(), `${port}.json`);
+}
+export function writeLockfile(port, data) {
+    try {
+        const dir = getLockfileDir();
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(lockfilePath(port), JSON.stringify(data, null, 2) + '\n');
+    }
+    catch {
+        // Non-critical — don't crash if we can't write the lockfile
+    }
+}
+export function readLockfile(port) {
+    try {
+        const raw = fs.readFileSync(lockfilePath(port), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove lockfile only if it belongs to this traforo instance.
+ * Prevents a late-exiting old process from deleting a newer instance's lockfile.
+ */
+export function removeLockfile(port, expectedTunnelPid) {
+    try {
+        if (expectedTunnelPid != null) {
+            const lock = readLockfile(port);
+            if (lock && lock.tunnelPid !== expectedTunnelPid) {
+                return; // not ours — leave it alone
+            }
+        }
+        fs.unlinkSync(lockfilePath(port));
+    }
+    catch {
+        // Already gone or never existed
+    }
+}
+/**
+ * Check if the tunnel process in a lockfile is still alive.
+ * Uses tunnelPid (the traforo process) not serverPid, because
+ * the tunnel URL is only valid while the traforo process is running.
+ * Returns true (stale) if the tunnel process no longer exists.
+ */
+export function isLockfileStale(lock) {
+    try {
+        // signal 0 doesn't kill — just checks if process exists
+        process.kill(lock.tunnelPid, 0);
+        return false;
+    }
+    catch (error) {
+        // ESRCH = no such process (dead). EPERM = process exists but we
+        // can't signal it (e.g. PID 1) — treat as alive, not stale.
+        return error.code === 'ESRCH';
+    }
+}

package/dist/run-tunnel.js

@@ -3,8 +3,26 @@ import { exec, spawn } from 'node:child_process';
 import net from 'node:net';
 import { promisify } from 'node:util';
 import { TunnelClient } from './client.js';
+import { writeLockfile, readLockfile, removeLockfile, isLockfileStale, } from './lockfile.js';
 const execPromise = promisify(exec);
 export const CLI_NAME = 'traforo';
+/**
+ * Shell-quote an argument array so the suggested command is copy-pasteable.
+ * Wraps args in single quotes if they contain shell-special characters.
+ */
+function shellQuote(args) {
+    return args
+        .map((arg) => {
+        if (arg === '')
+            return "''";
+        // Safe chars that don't need quoting
+        if (/^[a-zA-Z0-9._\-/:=@]+$/.test(arg))
+            return arg;
+        // Wrap in single quotes, escaping any inner single quotes
+        return "'" + arg.replace(/'/g, "'\\''") + "'";
+    })
+        .join(' ');
+}
 const DEFAULT_TUNNEL_ID_BYTES = 10;
 export function createRandomTunnelId({ port }) {
     return `${crypto.randomBytes(DEFAULT_TUNNEL_ID_BYTES).toString('hex')}-${port}`;
@@ -167,13 +185,71 @@ export async function runTunnel(options) {
     // Kill existing process on port if requested
     if (options.kill) {
         await killProcessOnPort(port);
+        // Verify the port actually freed up before removing the lockfile
+        if (await isPortInUse(port, localHost)) {
+            console.error(`Error: Port ${port} is still in use after --kill.`);
+            console.error(`The process may require elevated permissions to terminate.`);
+            process.exit(1);
+        }
+        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) {
+        const portBusy = await isPortInUse(port, localHost);
+        if (portBusy) {
+            const lock = readLockfile(port);
+            if (lock && !isLockfileStale(lock)) {
+                const currentCwd = process.cwd();
+                const currentCmd = options.command;
+                const sameCwd = lock.cwd === currentCwd;
+                const sameCmd = lock.command &&
+                    lock.command.length === currentCmd.length &&
+                    lock.command.every((arg, i) => arg === currentCmd[i]);
+                if (sameCwd && sameCmd) {
+                    // Same command in same directory — tell agent to reuse the tunnel
+                    console.error(`Error: Port ${port} is already in use\n`);
+                    console.error(`  Tunnel:  ${lock.tunnelUrl}`);
+                    console.error(`  ID:      ${lock.tunnelId}`);
+                    console.error(`  Command: ${lock.command ? shellQuote(lock.command) : 'unknown'}`);
+                    console.error(`  Dir:     ${lock.cwd}`);
+                    console.error(`  PID:     ${lock.tunnelPid}`);
+                    console.error(`  Started: ${lock.startedAt}\n`);
+                    console.error(`The same command in the same directory is already tunneled.`);
+                    console.error(`Reuse the tunnel URL above instead of creating a new one.`);
+                    process.exit(1);
+                }
+                else {
+                    // Different command or directory — suggest --kill or reuse
+                    console.error(`Error: Port ${port} is already in use\n`);
+                    console.error(`  Tunnel:  ${lock.tunnelUrl}`);
+                    console.error(`  ID:      ${lock.tunnelId}`);
+                    console.error(`  Command: ${lock.command ? shellQuote(lock.command) : 'unknown'}`);
+                    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,`);
+                    console.error(`or just reuse the tunnel URL above instead:\n`);
+                    console.error(`  traforo -p ${port} --kill -- ${shellQuote(options.command)}`);
+                    process.exit(1);
+                }
+            }
+            else {
+                // Port busy but no lockfile or stale lockfile — unknown process
+                if (lock)
+                    removeLockfile(port);
+                console.error(`Error: Port ${port} is already in use by another process.\n`);
+                console.error(`Use --kill to terminate it before starting:`);
+                console.error(`  traforo -p ${port} --kill -- ${shellQuote(options.command)}`);
+                process.exit(1);
+            }
+        }
     }
     let child = null;
     // 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: ${options.command.join(' ')}`);
+        console.log(`Starting: ${shellQuote(options.command)}`);
         console.log(`PORT=${port}\n`);
         const spawnedChild = spawn(cmd, args, {
             stdio: 'inherit',
@@ -193,6 +269,7 @@ export async function runTunnel(options) {
         });
         spawnedChild.on('exit', (code) => {
             console.log(`\nCommand exited with code ${code}`);
+            removeLockfile(port, process.pid);
             process.exit(code || 0);
         });
         // Wait for port to be available before connecting tunnel
@@ -225,6 +302,7 @@ export async function runTunnel(options) {
     // Handle shutdown
     const cleanup = () => {
         console.log('\nShutting down...');
+        removeLockfile(port, process.pid);
         client.close();
         if (child) {
             child.kill();
@@ -235,6 +313,17 @@ export async function runTunnel(options) {
     process.on('SIGTERM', cleanup);
     try {
         await client.connect();
+        // Write lockfile so other traforo instances can detect this tunnel
+        writeLockfile(port, {
+            tunnelId,
+            tunnelUrl: client.url,
+            port,
+            tunnelPid: process.pid,
+            serverPid: child?.pid,
+            command: options.command,
+            cwd: process.cwd(),
+            startedAt: new Date().toISOString(),
+        });
     }
     catch (err) {
         console.error('Failed to connect:', err instanceof Error ? err.message : String(err));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traforo",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",
@@ -28,18 +28,6 @@
       "import": "./dist/run-tunnel.js"
     }
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.client.json && chmod +x dist/cli.js",
-    "prepublishOnly": "pnpm build",
-    "dev": "wrangler dev",
-    "deploy": "wrangler deploy",
-    "deploy:preview": "wrangler deploy --env preview",
-    "typecheck": "tsc --noEmit",
-    "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
-    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
-    "cli": "tsx src/cli.ts",
-    "test": "vitest --run"
-  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250712.0",
     "@types/http-cache-semantics": "^4.2.0",
@@ -57,5 +45,16 @@
     "http-cache-semantics": "^4.2.0",
     "string-dedent": "^3.0.2",
     "ws": "^8.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.client.json && chmod +x dist/cli.js",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:preview": "wrangler deploy --env preview",
+    "typecheck": "tsc --noEmit",
+    "typecheck:client": "tsc --noEmit -p tsconfig.client.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "cli": "tsx src/cli.ts",
+    "test": "vitest --run"
   }
-}
+}