mekong-cli 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# mekong-cli
+
+Run your dev server and a [Mekong](https://mekongtunnel.dev) tunnel together in a single command — no separate terminal needed.
+
+Think of it as the glue between `next dev` / `vite` / `nuxt dev` and `mekong <port>`.
+
+---
+
+## Install
+
+```bash
+npm install -g mekong-cli
+```
+
+Or use it without installing:
+
+```bash
+npx mekong-cli 3000
+```
+
+---
+
+## Requirements
+
+- **Node.js 14+**
+- **mekong binary** installed separately (see below)
+
+---
+
+## Install the mekong binary
+
+Download from the [GitHub releases page](https://github.com/MuyleangIng/MekongTunnel/releases/tag/v1.4.9).
+
+**Linux / macOS (amd64) — quick one-liner:**
+
+```bash
+curl -sL https://github.com/MuyleangIng/MekongTunnel/releases/download/v1.4.9/mekong-linux-amd64 \
+  -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong
+```
+
+**macOS (Apple Silicon):**
+
+```bash
+curl -sL https://github.com/MuyleangIng/MekongTunnel/releases/download/v1.4.9/mekong-darwin-arm64 \
+  -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong
+```
+
+**Windows:** Download `mekong-windows-amd64.exe`, rename it to `mekong.exe`, and place it somewhere on your `PATH` (e.g. `C:\Windows\System32\` or `%USERPROFILE%\AppData\Local\`).
+
+---
+
+## Usage
+
+### Tunnel an already-running server
+
+```bash
+mekong-cli 3000
+```
+
+### Start server + tunnel together
+
+```bash
+mekong-cli --with "next dev" --port 3000
+mekong-cli --with "vite" --port 5173
+mekong-cli --with "nuxt dev" --port 3000
+mekong-cli --with "ng serve" --port 4200
+mekong-cli --with "astro dev" --port 4321
+```
+
+### Extra options
+
+```bash
+# Set tunnel expiry
+mekong-cli --with "next dev" --port 3000 --expire 2h
+
+# Run mekong in background (daemon mode)
+mekong-cli --with "next dev" --port 3000 --daemon
+
+# Suppress QR code
+mekong-cli --with "next dev" --port 3000 --no-qr
+
+# Use a custom mekong binary path
+mekong-cli --with "next dev" --port 3000 --mekong ~/bin/mekong
+```
+
+### All options
+
+```
+--with <cmd>     Shell command to start the dev server
+--port <n>       Local port (auto-detected from package.json if omitted)
+--expire <val>   Expiry duration passed to mekong (e.g. 2h, 30m)
+--daemon         Run mekong in the background (-d flag)
+--no-qr          Suppress QR code output
+--mekong <path>  Custom path to the mekong binary
+--help           Show help
+```
+
+---
+
+## Add to package.json scripts
+
+You can wire `mekong-cli` directly into your project's `package.json` so the whole team uses it consistently:
+
+```json
+{
+  "scripts": {
+    "dev": "next dev",
+    "tunnel": "mekong-cli --with \"next dev\" --port 3000",
+    "tunnel:share": "mekong-cli --with \"next dev\" --port 3000 --expire 2h"
+  }
+}
+```
+
+Then just run:
+
+```bash
+npm run tunnel
+```
+
+### Framework-specific examples
+
+**Vite / SvelteKit:**
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "tunnel": "mekong-cli --with \"vite\" --port 5173"
+  }
+}
+```
+
+**Nuxt:**
+
+```json
+{
+  "scripts": {
+    "dev": "nuxt dev",
+    "tunnel": "mekong-cli --with \"nuxt dev\" --port 3000"
+  }
+}
+```
+
+**Angular:**
+
+```json
+{
+  "scripts": {
+    "start": "ng serve",
+    "tunnel": "mekong-cli --with \"ng serve\" --port 4200"
+  }
+}
+```
+
+**Astro:**
+
+```json
+{
+  "scripts": {
+    "dev": "astro dev",
+    "tunnel": "mekong-cli --with \"astro dev\" --port 4321"
+  }
+}
+```
+
+---
+
+## How it works
+
+1. Spawns your dev server (`--with`) with its stdout/stderr streamed to your terminal, prefixed with `[server]`.
+2. Polls the local port every 500 ms until the server is accepting connections (up to 30 s).
+3. Starts `mekong <port>` and streams its output prefixed with `[tunnel]`.
+4. When the public URL appears in mekong's output, prints a banner:
+
+```
+╔══════════════════════════════════════════╗
+║  Public URL: https://happy-tiger-a1b2c3d4.mekongtunnel.dev  ║
+╚══════════════════════════════════════════╝
+```
+
+5. On `Ctrl+C` (or `SIGTERM`), kills the tunnel first, then the server, and exits cleanly.
+
+---
+
+## License
+
+MIT — Author: Ing Muyleang

package/bin/mekong-cli.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+const { findMekong }  = require('../lib/find-mekong');
+const { detectPort }  = require('../lib/detect-port');
+const { runWithServer } = require('../lib/runner');
+
+const BOLD   = '\x1b[1m';
+const DIM    = '\x1b[2m';
+const CYAN   = '\x1b[36m';
+const GREEN  = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED    = '\x1b[31m';
+const RESET  = '\x1b[0m';
+
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+const HELP = `
+${BOLD}mekong-cli${RESET} — Run your dev server + Mekong tunnel in one command
+
+${BOLD}USAGE${RESET}
+  mekong-cli <port>                        Tunnel an already-running server
+  mekong-cli --port <n>                    Tunnel only (auto-detect port)
+  mekong-cli --with "<cmd>" --port <n>     Start server + tunnel together
+
+${BOLD}OPTIONS${RESET}
+  --with <cmd>     Shell command to start the dev server
+  --port <n>       Local port (auto-detected from package.json if omitted)
+  --expire <val>   Expiry duration passed to mekong (e.g. 2h, 30m)
+  --daemon         Run mekong in the background (-d flag)
+  --no-qr          Suppress QR code output
+  --mekong <path>  Custom path to the mekong binary
+  --help           Show this help message
+
+${BOLD}EXAMPLES${RESET}
+  mekong-cli 3000
+  mekong-cli --with "next dev" --port 3000
+  mekong-cli --with "vite" --port 5173
+  mekong-cli --with "nuxt dev" --port 3000
+  mekong-cli --with "ng serve" --port 4200
+  mekong-cli --with "astro dev" --port 4321
+  mekong-cli --with "next dev" --port 3000 --expire 2h
+  mekong-cli --with "next dev" --port 3000 --daemon
+
+${BOLD}INSTALL MEKONG BINARY${RESET}
+  Download from: https://github.com/MuyleangIng/MekongTunnel/releases/tag/v1.4.9
+
+  Linux/macOS (quick install):
+    curl -sL https://github.com/MuyleangIng/MekongTunnel/releases/download/v1.4.9/mekong-linux-amd64 \\
+      -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong
+
+  Windows: download mekong-windows-amd64.exe and place in PATH
+`;
+
+// ---------------------------------------------------------------------------
+// Argument parser
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const args = argv.slice(2); // strip node + script
+  const opts = {
+    port: null,
+    with: null,
+    expire: null,
+    daemon: false,
+    noQr: false,
+    mekongPath: null,
+    help: false,
+    positional: [],
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    switch (a) {
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      case '--port':
+      case '-p':
+        opts.port = parseInt(args[++i], 10);
+        break;
+      case '--with':
+        opts.with = args[++i];
+        break;
+      case '--expire':
+        opts.expire = args[++i];
+        break;
+      case '--daemon':
+      case '-d':
+        opts.daemon = true;
+        break;
+      case '--no-qr':
+        opts.noQr = true;
+        break;
+      case '--mekong':
+        opts.mekongPath = args[++i];
+        break;
+      default:
+        if (!a.startsWith('-')) {
+          opts.positional.push(a);
+        } else {
+          // unknown flag — warn but continue
+          process.stderr.write(`${YELLOW}mekong-cli: unknown option: ${a}${RESET}\n`);
+        }
+    }
+    i++;
+  }
+
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+
+  // Resolve mekong binary
+  const mekongBin = opts.mekongPath || findMekong();
+  if (!mekongBin) {
+    process.stderr.write(
+      `${RED}${BOLD}mekong-cli: mekong binary not found.${RESET}\n\n` +
+      `Install it from:\n` +
+      `  https://github.com/MuyleangIng/MekongTunnel/releases/tag/v1.4.9\n\n` +
+      `Quick install (Linux/macOS):\n` +
+      `  curl -sL https://github.com/MuyleangIng/MekongTunnel/releases/download/v1.4.9/mekong-linux-amd64 \\\n` +
+      `    -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong\n\n` +
+      `Or specify a custom path with: ${CYAN}--mekong /path/to/mekong${RESET}\n`
+    );
+    process.exit(1);
+  }
+
+  // Resolve port
+  let port = opts.port;
+  if (!port && opts.positional.length > 0) {
+    port = parseInt(opts.positional[0], 10);
+  }
+  if (!port) {
+    port = detectPort();
+  }
+  if (!port || isNaN(port)) {
+    process.stderr.write(
+      `${RED}mekong-cli: could not determine port.${RESET}\n` +
+      `Specify it with ${CYAN}--port <n>${RESET} or pass it as the first argument.\n`
+    );
+    process.exit(1);
+  }
+
+  const runnerOpts = {
+    mekongBin,
+    expire: opts.expire,
+    daemon: opts.daemon,
+    noQr:   opts.noQr,
+  };
+
+  // --with: start server + tunnel
+  if (opts.with) {
+    await runWithServer(opts.with, port, runnerOpts);
+    return;
+  }
+
+  // Tunnel-only mode: just proxy straight to mekong
+  const mekongArgs = [String(port)];
+  if (opts.expire) mekongArgs.push('--expire', opts.expire);
+  if (opts.daemon) mekongArgs.push('-d');
+  if (opts.noQr)   mekongArgs.push('--no-qr');
+
+  process.stdout.write(
+    `${CYAN}${BOLD}mekong-cli${RESET} Tunneling ${CYAN}localhost:${port}${RESET} via mekong...\n`
+  );
+
+  const tunnel = spawn(mekongBin, mekongArgs, { stdio: 'inherit' });
+
+  tunnel.on('exit', (code) => {
+    process.exit(code == null ? 0 : code);
+  });
+
+  process.on('SIGINT',  () => { tunnel.kill('SIGTERM'); });
+  process.on('SIGTERM', () => { tunnel.kill('SIGTERM'); });
+}
+
+main().catch((err) => {
+  process.stderr.write(`${RED}mekong-cli: ${err.message}${RESET}\n`);
+  process.exit(1);
+});

package/lib/detect-port.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Auto-detect the local dev server port from package.json in cwd.
+ * Returns a number or null if not detected.
+ */
+function detectPort() {
+  const pkgPath = path.join(process.cwd(), 'package.json');
+
+  let pkg;
+  try {
+    const raw = fs.readFileSync(pkgPath, 'utf8');
+    pkg = JSON.parse(raw);
+  } catch (_) {
+    return null;
+  }
+
+  // Check scripts for explicit --port N
+  const scripts = pkg.scripts || {};
+  for (const key of ['dev', 'start']) {
+    const script = scripts[key];
+    if (typeof script === 'string') {
+      const m = script.match(/--port[=\s]+(\d+)/);
+      if (m) return parseInt(m[1], 10);
+      // also handle -p N
+      const m2 = script.match(/-p[=\s]+(\d+)/);
+      if (m2) return parseInt(m2[1], 10);
+    }
+  }
+
+  // Check dependencies / devDependencies for known frameworks
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+
+  const frameworkPort = [
+    [['next', 'next.js'], 3000],
+    [['nuxt', 'nuxt3', 'nuxt-edge'], 3000],
+    [['vite'], 5173],
+    [['react-scripts'], 3000],
+    [['@angular/core'], 4200],
+    [['svelte', '@sveltejs/kit', '@sveltejs/vite-plugin-svelte'], 5173],
+    [['gatsby'], 8000],
+    [['remix', '@remix-run/node', '@remix-run/react', '@remix-run/serve'], 3000],
+    [['astro'], 4321],
+    [['express', 'fastify', 'koa', '@hapi/hapi', 'hapi'], 3000],
+  ];
+
+  for (const [keys, port] of frameworkPort) {
+    for (const key of keys) {
+      if (key in deps) return port;
+    }
+  }
+
+  return null;
+}
+
+module.exports = { detectPort };

package/lib/find-mekong.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Locate the mekong binary.
+ * Returns an absolute path string or null if not found.
+ */
+function findMekong() {
+  const isWindows = process.platform === 'win32';
+
+  // 1. Try `which mekong` (or `where mekong` on Windows)
+  try {
+    const cmd = isWindows ? 'where mekong' : 'which mekong';
+    const result = execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim()
+      .split('\n')[0]
+      .trim();
+    if (result && fs.existsSync(result)) return result;
+  } catch (_) {
+    // not on PATH
+  }
+
+  // 2. Common Unix paths
+  if (!isWindows) {
+    const unixPaths = [
+      path.join(os.homedir(), '.local', 'bin', 'mekong'),
+      '/usr/local/bin/mekong',
+      '/usr/bin/mekong',
+    ];
+    for (const p of unixPaths) {
+      if (fs.existsSync(p)) return p;
+    }
+  }
+
+  // 3. Windows paths
+  if (isWindows) {
+    const winPaths = [
+      path.join(os.homedir(), '.local', 'bin', 'mekong.exe'),
+      'C:\\Program Files\\mekong\\mekong.exe',
+      path.join(process.env.USERPROFILE || os.homedir(), 'AppData', 'Local', 'mekong.exe'),
+    ];
+    for (const p of winPaths) {
+      if (fs.existsSync(p)) return p;
+    }
+
+    // Also try without .exe in same locations
+    const winPathsNoExt = [
+      path.join(os.homedir(), '.local', 'bin', 'mekong'),
+      path.join(process.env.USERPROFILE || os.homedir(), 'AppData', 'Local', 'mekong'),
+    ];
+    for (const p of winPathsNoExt) {
+      if (fs.existsSync(p)) return p;
+    }
+  }
+
+  return null;
+}
+
+module.exports = { findMekong };

package/lib/runner.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const { waitForPort } = require('./wait-for-port');
+
+const BOLD   = '\x1b[1m';
+const DIM    = '\x1b[2m';
+const CYAN   = '\x1b[36m';
+const GREEN  = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED    = '\x1b[31m';
+const RESET  = '\x1b[0m';
+
+/**
+ * Prefix and stream lines from a readable stream.
+ * @param {import('stream').Readable} readable
+ * @param {string} prefix
+ * @param {(line: string) => void} [onLine]
+ */
+function streamLines(readable, prefix, onLine) {
+  let buf = '';
+  readable.on('data', (chunk) => {
+    buf += chunk.toString();
+    let idx;
+    while ((idx = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, idx);
+      buf = buf.slice(idx + 1);
+      process.stdout.write(`${DIM}${prefix}${RESET} ${line}\n`);
+      if (onLine) onLine(line);
+    }
+  });
+  readable.on('end', () => {
+    if (buf.length > 0) {
+      process.stdout.write(`${DIM}${prefix}${RESET} ${buf}\n`);
+      if (onLine) onLine(buf);
+      buf = '';
+    }
+  });
+}
+
+/**
+ * Print a banner with the public tunnel URL.
+ * @param {string} url
+ */
+function printBanner(url) {
+  const label = '  Public URL: ';
+  const inner = label + url + '  ';
+  const width = Math.max(inner.length + 2, 42);
+  const top    = '╔' + '═'.repeat(width) + '╗';
+  const bottom = '╚' + '═'.repeat(width) + '╝';
+  const pad    = width - inner.length;
+  const middle = '║' + inner + ' '.repeat(pad) + '║';
+
+  process.stdout.write('\n');
+  process.stdout.write(`${GREEN}${BOLD}${top}${RESET}\n`);
+  process.stdout.write(`${GREEN}${BOLD}${middle}${RESET}\n`);
+  process.stdout.write(`${GREEN}${BOLD}${bottom}${RESET}\n`);
+  process.stdout.write('\n');
+}
+
+/**
+ * Run a dev server command alongside a mekong tunnel.
+ *
+ * @param {string} serverCmd  - shell command to start the dev server
+ * @param {number} port       - local port the server will listen on
+ * @param {object} opts
+ * @param {string}  opts.mekongBin  - path to mekong binary
+ * @param {string}  [opts.expire]   - --expire value passed to mekong
+ * @param {boolean} [opts.daemon]   - pass -d to mekong
+ * @param {boolean} [opts.noQr]     - pass --no-qr to mekong
+ */
+async function runWithServer(serverCmd, port, opts) {
+  const { mekongBin, expire, daemon, noQr } = opts;
+
+  process.stdout.write(
+    `${CYAN}${BOLD}mekong-cli${RESET} Starting dev server: ${YELLOW}${serverCmd}${RESET}\n`
+  );
+
+  // 1. Spawn the dev server
+  const server = spawn(serverCmd, [], {
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  streamLines(server.stdout, '[server]');
+  streamLines(server.stderr, '[server]');
+
+  let tunnelProc = null;
+
+  function cleanup(exitCode) {
+    if (tunnelProc && !tunnelProc.killed) {
+      tunnelProc.kill('SIGTERM');
+    }
+    if (server && !server.killed) {
+      server.kill('SIGTERM');
+    }
+    process.exit(exitCode == null ? 0 : exitCode);
+  }
+
+  process.on('SIGINT', () => cleanup(0));
+  process.on('SIGTERM', () => cleanup(0));
+
+  server.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      process.stderr.write(
+        `${RED}[server] exited with code ${code}${RESET}\n`
+      );
+      cleanup(code);
+    }
+  });
+
+  // 2. Wait for the port to be ready
+  process.stdout.write(
+    `${DIM}mekong-cli${RESET} Waiting for port ${CYAN}${port}${RESET} to be ready...\n`
+  );
+
+  try {
+    await waitForPort(port);
+  } catch (err) {
+    process.stderr.write(`${RED}mekong-cli: ${err.message}${RESET}\n`);
+    cleanup(1);
+    return;
+  }
+
+  process.stdout.write(
+    `${GREEN}mekong-cli${RESET} Port ${CYAN}${port}${RESET} is ready. Starting tunnel...\n`
+  );
+
+  // 3. Build mekong args
+  const mekongArgs = [String(port)];
+  if (expire) mekongArgs.push('--expire', expire);
+  if (daemon) mekongArgs.push('-d');
+  if (noQr)   mekongArgs.push('--no-qr');
+
+  // 4. Spawn mekong
+  tunnelProc = spawn(mekongBin, mekongArgs, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  const urlRegex = /https?:\/\/[^\s]+/;
+  let bannerShown = false;
+
+  function handleTunnelLine(line) {
+    if (!bannerShown) {
+      const m = line.match(urlRegex);
+      if (m) {
+        bannerShown = true;
+        printBanner(m[0]);
+      }
+    }
+  }
+
+  streamLines(tunnelProc.stdout, '[tunnel]', handleTunnelLine);
+  streamLines(tunnelProc.stderr, '[tunnel]', handleTunnelLine);
+
+  tunnelProc.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      process.stderr.write(
+        `${YELLOW}[tunnel] exited with code ${code}${RESET}\n`
+      );
+    }
+  });
+}
+
+module.exports = { runWithServer };

package/lib/wait-for-port.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const net = require('net');
+
+/**
+ * Poll a TCP port every 500ms until it accepts a connection.
+ * Rejects after 30 seconds.
+ *
+ * @param {number} port
+ * @returns {Promise<void>}
+ */
+function waitForPort(port) {
+  const INTERVAL_MS = 500;
+  const TIMEOUT_MS = 30_000;
+
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+
+    function attempt() {
+      const elapsed = Date.now() - started;
+      if (elapsed >= TIMEOUT_MS) {
+        return reject(
+          new Error(`Timed out waiting for port ${port} after ${TIMEOUT_MS / 1000}s`)
+        );
+      }
+
+      const sock = new net.Socket();
+      let settled = false;
+
+      function cleanup(err) {
+        if (settled) return;
+        settled = true;
+        sock.destroy();
+        if (err) {
+          setTimeout(attempt, INTERVAL_MS);
+        } else {
+          resolve();
+        }
+      }
+
+      sock.setTimeout(INTERVAL_MS);
+      sock.once('connect', () => cleanup(null));
+      sock.once('error', (err) => cleanup(err));
+      sock.once('timeout', () => cleanup(new Error('timeout')));
+      sock.connect(port, '127.0.0.1');
+    }
+
+    attempt();
+  });
+}
+
+module.exports = { waitForPort };

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "mekong-cli",
+  "version": "1.0.0",
+  "description": "Run your dev server + Mekong tunnel in one command",
+  "bin": {
+    "mekong-cli": "bin/mekong-cli.js"
+  },
+  "license": "MIT",
+  "author": "Ing Muyleang",
+  "keywords": [
+    "tunnel",
+    "mekong",
+    "ngrok",
+    "devserver",
+    "nextjs",
+    "vite",
+    "nuxt"
+  ],
+  "dependencies": {}
+}