traforo 0.2.3 → 0.2.5

package/dist/lockfile.d.ts

@@ -4,7 +4,10 @@
  * 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;

package/dist/lockfile.js

@@ -4,17 +4,22 @@
  * 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';
-const LOCKFILE_DIR = path.join(os.homedir(), '.traforo');
+export function getLockfileDir() {
+    return process.env.TRAFORO_HOME ?? path.join(os.homedir(), '.traforo');
+}
 function lockfilePath(port) {
-    return path.join(LOCKFILE_DIR, `${port}.json`);
+    return path.join(getLockfileDir(), `${port}.json`);
 }
 export function writeLockfile(port, data) {
     try {
-        fs.mkdirSync(LOCKFILE_DIR, { recursive: true });
+        const dir = getLockfileDir();
+        fs.mkdirSync(dir, { recursive: true });
         fs.writeFileSync(lockfilePath(port), JSON.stringify(data, null, 2) + '\n');
     }
     catch {
@@ -60,7 +65,9 @@ export function isLockfileStale(lock) {
         process.kill(lock.tunnelPid, 0);
         return false;
     }
-    catch {
-        return true;
+    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

@@ -6,6 +6,23 @@ 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}`;
@@ -168,13 +185,13 @@ export async function runTunnel(options) {
     // Kill existing process on port if requested
     if (options.kill) {
         await killProcessOnPort(port);
-        removeLockfile(port); // no ownership check — --kill is intentional
-        // Verify the port actually freed up
+        // 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) {
@@ -184,6 +201,7 @@ export async function runTunnel(options) {
             if (lock && !isLockfileStale(lock)) {
                 const currentCwd = process.cwd();
                 const currentCmd = options.command;
+                const restartCommand = `${CLI_NAME} -p ${port} -t ${lock.tunnelId} --kill -- ${shellQuote(currentCmd)}`;
                 const sameCwd = lock.cwd === currentCwd;
                 const sameCmd = lock.command &&
                     lock.command.length === currentCmd.length &&
@@ -193,12 +211,14 @@ export async function runTunnel(options) {
                     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?.join(' ') ?? 'unknown'}`);
+                    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.`);
+                    console.error(`If you want to restart it without changing the tunnel URL for existing consumers, run:`);
+                    console.error(`  ${restartCommand}`);
                     process.exit(1);
                 }
                 else {
@@ -206,13 +226,13 @@ export async function runTunnel(options) {
                     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?.join(' ') ?? 'unknown'}`);
+                    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(`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(`  traforo -p ${port} --kill -- ${options.command.join(' ')}`);
+                    console.error(`  ${restartCommand}`);
                     process.exit(1);
                 }
             }
@@ -222,7 +242,7 @@ export async function runTunnel(options) {
                     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 -- ${options.command.join(' ')}`);
+                console.error(`  traforo -p ${port} --kill -- ${shellQuote(options.command)}`);
                 process.exit(1);
             }
         }
@@ -232,7 +252,7 @@ export async function runTunnel(options) {
     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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traforo",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "HTTP tunnel via Cloudflare Durable Objects and WebSockets. Edge caching and password protection.",
   "type": "module",
   "license": "MIT",