mekong-cli 1.1.0 → 1.2.0

package/README.md

@@ -1,8 +1,10 @@
 # mekong-cli
 
-Run your dev server and a [Mekong](https://mekongtunnel.dev) tunnel together in a single command — no separate terminal needed.
+> Expose your Node.js dev server to the internet in one command.
+> Works with Next.js, Vite, Nuxt, Angular, Astro, Svelte, Express, and more.
 
-Think of it as the glue between `next dev` / `vite` / `nuxt dev` and `mekong <port>`.
+[![npm version](https://img.shields.io/npm/v/mekong-cli)](https://www.npmjs.com/package/mekong-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 ---
 
@@ -12,7 +14,7 @@ Think of it as the glue between `next dev` / `vite` / `nuxt dev` and `mekong <po
 npm install -g mekong-cli
 ```
 
-Or use it without installing:
+Or use without installing:
 
 ```bash
 npx mekong-cli 3000
@@ -23,90 +25,133 @@ npx mekong-cli 3000
 ## Requirements
 
 - **Node.js 14+**
-- **mekong binary** installed separately (see below)
+- **mekong binary** — install separately (see below)
 
----
+### Install the mekong binary
 
-## Install the mekong binary
+```bash
+# macOS / Linux (auto-detect arch)
+curl -fsSL https://github.com/MuyleangIng/MekongTunnel/releases/latest/download/mekong-$(uname -s | tr A-Z a-z)-$(uname -m) \
+  -o ~/.local/bin/mekong && chmod +x ~/.local/bin/mekong
 
-Download from the [GitHub releases page](https://github.com/MuyleangIng/MekongTunnel/releases/tag/v1.4.9).
+# macOS Intel
+curl -fsSL https://github.com/MuyleangIng/MekongTunnel/releases/latest/download/mekong-darwin-amd64 \
+  -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong
 
-**Linux / macOS (amd64) — quick one-liner:**
+# macOS Apple Silicon
+curl -fsSL https://github.com/MuyleangIng/MekongTunnel/releases/latest/download/mekong-darwin-arm64 \
+  -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong
 
-```bash
-curl -sL https://github.com/MuyleangIng/MekongTunnel/releases/download/v1.4.9/mekong-linux-amd64 \
+# Linux amd64
+curl -fsSL https://github.com/MuyleangIng/MekongTunnel/releases/latest/download/mekong-linux-amd64 \
   -o /usr/local/bin/mekong && chmod +x /usr/local/bin/mekong
+
+# Windows — download from:
+# https://github.com/MuyleangIng/MekongTunnel/releases/latest
 ```
 
-**macOS (Apple Silicon):**
+---
+
+## Commands
+
+### 1. `mekong-cli <port>` — Tunnel an already-running server
+
+Your server is already running. Just pass the port:
 
 ```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
+mekong-cli 3000
+mekong-cli 5173
+mekong-cli 8080
 ```
 
-**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\`).
+> If nothing is listening on that port, mekong-cli will tell you clearly and exit — it will **not** start the tunnel.
 
 ---
 
-## Usage
+### 2. `mekong-cli` — Auto-detect port from package.json
 
-### Tunnel an already-running server
+No port needed if your `package.json` uses a known framework:
 
 ```bash
-mekong-cli 3000
+mekong-cli
 ```
 
-### Start server + tunnel together
+mekong-cli reads your `package.json` and detects the port automatically:
+
+| Framework | Detected port |
+|---|---|
+| Next.js | 3000 |
+| Nuxt | 3000 |
+| React (CRA) | 3000 |
+| Remix | 3000 |
+| Express / Fastify / Koa | 3000 |
+| Vite | 5173 |
+| SvelteKit | 5173 |
+| Angular | 4200 |
+| Astro | 4321 |
+| Gatsby | 8000 |
+
+---
+
+### 3. `mekong-cli --with "<cmd>" --port <n>` — Start server + tunnel together
+
+Start your dev server AND the tunnel at the same time — no separate terminals:
 
 ```bash
+# Next.js
 mekong-cli --with "next dev" --port 3000
+
+# Vite (React, Vue, Svelte, etc.)
 mekong-cli --with "vite" --port 5173
+
+# Nuxt
 mekong-cli --with "nuxt dev" --port 3000
+
+# Angular
 mekong-cli --with "ng serve" --port 4200
+
+# Astro
 mekong-cli --with "astro dev" --port 4321
-```
 
-### Extra options
+# SvelteKit
+mekong-cli --with "vite dev" --port 5173
 
-```bash
-# Set tunnel expiry
-mekong-cli --with "next dev" --port 3000 --expire 2h
+# Express / Node server
+mekong-cli --with "node server.js" --port 3000
 
-# Run mekong in background (daemon mode)
-mekong-cli --with "next dev" --port 3000 --daemon
+# Any custom command
+mekong-cli --with "npm run dev" --port 3000
+```
 
-# Suppress QR code
-mekong-cli --with "next dev" --port 3000 --no-qr
+mekong-cli will:
+1. Start your dev server
+2. Wait for port to accept connections (up to 30s)
+3. Start the mekong tunnel
+4. Print the public URL banner
+5. On Ctrl+C — stop both cleanly
 
-# Use a custom mekong binary path
-mekong-cli --with "next dev" --port 3000 --mekong ~/bin/mekong
-```
+---
 
-### All options
+### 4. `mekong-cli init` — Auto-setup in your project
 
-```
---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
-```
+Run this once in your project root:
 
----
+```bash
+mekong-cli init
+```
 
-## Add to package.json scripts
+mekong-cli init will:
+- Detect your framework (Next.js, Vite, Nuxt, etc.)
+- Ask which port your server runs on
+- Inject a `dev:tunnel` script into your `package.json`
 
-You can wire `mekong-cli` directly into your project's `package.json` so the whole team uses it consistently:
+After running init, your `package.json` will have:
 
 ```json
 {
   "scripts": {
     "dev": "next dev",
-    "tunnel": "mekong-cli --with \"next dev\" --port 3000",
-    "tunnel:share": "mekong-cli --with \"next dev\" --port 3000 --expire 2h"
+    "dev:tunnel": "mekong-cli --with \"next dev\" --port 3000"
   }
 }
 ```
@@ -114,74 +159,99 @@ You can wire `mekong-cli` directly into your project's `package.json` so the who
 Then just run:
 
 ```bash
-npm run tunnel
+npm run dev:tunnel
 ```
 
-### Framework-specific examples
+---
 
-**Vite / SvelteKit:**
+## All options
 
-```json
-{
-  "scripts": {
-    "dev": "vite",
-    "tunnel": "mekong-cli --with \"vite\" --port 5173"
-  }
-}
+```
+mekong-cli [options] [port]
+
+  <port>           Port of an already-running server to tunnel
+  --with <cmd>     Start this dev server command first, then tunnel
+  --port <n>       Explicit port (used with --with, or overrides auto-detect)
+  --expire <val>   Tunnel expiry: 30m, 2h, 1d, 1w
+  --daemon         Run mekong tunnel in background
+  --no-qr          Suppress QR code in terminal
+  --mekong <path>  Custom path to mekong binary
+  --help, -h       Show help
+
+  init             Auto-setup dev:tunnel script in your project
 ```
 
-**Nuxt:**
+---
 
-```json
-{
-  "scripts": {
-    "dev": "nuxt dev",
-    "tunnel": "mekong-cli --with \"nuxt dev\" --port 3000"
-  }
-}
-```
+## Framework quick reference
+
+| Framework | Command |
+|---|---|
+| **Next.js** | `mekong-cli --with "next dev" --port 3000` |
+| **Vite** | `mekong-cli --with "vite" --port 5173` |
+| **Nuxt** | `mekong-cli --with "nuxt dev" --port 3000` |
+| **Angular** | `mekong-cli --with "ng serve" --port 4200` |
+| **Astro** | `mekong-cli --with "astro dev" --port 4321` |
+| **SvelteKit** | `mekong-cli --with "vite dev" --port 5173` |
+| **Remix** | `mekong-cli --with "remix dev" --port 3000` |
+| **Gatsby** | `mekong-cli --with "gatsby develop" --port 8000` |
+| **Express** | `mekong-cli --with "node server.js" --port 3000` |
+| **Fastify** | `mekong-cli --with "node server.js" --port 3000` |
 
-**Angular:**
+---
 
-```json
-{
-  "scripts": {
-    "start": "ng serve",
-    "tunnel": "mekong-cli --with \"ng serve\" --port 4200"
-  }
-}
+## With expiry and options
+
+```bash
+# Expire tunnel after 2 hours
+mekong-cli --with "next dev" --port 3000 --expire 2h
+
+# Run tunnel in background (daemon mode)
+mekong-cli --with "next dev" --port 3000 --daemon
+
+# No QR code
+mekong-cli --with "vite" --port 5173 --no-qr
+
+# Custom mekong binary path
+mekong-cli --with "next dev" --port 3000 --mekong ~/bin/mekong
 ```
 
-**Astro:**
+---
+
+## Add scripts to package.json manually
 
 ```json
 {
   "scripts": {
-    "dev": "astro dev",
-    "tunnel": "mekong-cli --with \"astro dev\" --port 4321"
+    "dev": "next dev",
+    "dev:tunnel": "mekong-cli --with \"next dev\" --port 3000",
+    "dev:tunnel:share": "mekong-cli --with \"next dev\" --port 3000 --expire 2h"
   }
 }
 ```
 
+Or just run `mekong-cli init` and it does this for you automatically.
+
 ---
 
 ## 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:
-
 ```
-╔══════════════════════════════════════════╗
+mekong-cli --with "next dev" --port 3000
+
+[server] ready - started server on 0.0.0.0:3000
+[server] ...
+✔  Port 3000 is ready. Starting tunnel...
+[tunnel] ✔  Tunnel is live!
+[tunnel]    URL  https://happy-tiger-a1b2c3d4.mekongtunnel.dev
+
+╔══════════════════════════════════════════════════╗
 ║  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
+MIT © [Ing Muyleang](https://github.com/MuyleangIng) — KhmerStack

package/bin/mekong-cli.js

@@ -4,9 +4,10 @@
 const { spawn } = require('child_process');
 const path = require('path');
 
-const { findMekong }  = require('../lib/find-mekong');
-const { detectPort }  = require('../lib/detect-port');
+const { findMekong }    = require('../lib/find-mekong');
+const { detectPort }    = require('../lib/detect-port');
 const { runWithServer } = require('../lib/runner');
+const { checkPortOpen } = require('../lib/wait-for-port');
 
 const BOLD   = '\x1b[1m';
 const DIM    = '\x1b[2m';
@@ -23,37 +24,51 @@ 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 <port>                        Tunnel an already-running server on <port>
+  mekong-cli                               Auto-detect port from package.json + tunnel
   mekong-cli --with "<cmd>" --port <n>     Start server + tunnel together
+  mekong-cli init                          Auto-setup dev:tunnel script in your project
 
 ${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)
+  --expire <val>   Expiry duration passed to mekong (e.g. 2h, 30m, 1d, 1w)
   --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
+  --help, -h       Show this help message
+
+${BOLD}SUBCOMMANDS${RESET}
+  init             Auto-detect your framework, inject dev:tunnel into package.json
 
 ${BOLD}EXAMPLES${RESET}
+  ${DIM}# Tunnel a server already running on port 3000${RESET}
   mekong-cli 3000
+
+  ${DIM}# Auto-detect port from package.json and tunnel${RESET}
+  mekong-cli
+
+  ${DIM}# Start your dev server AND open a tunnel together${RESET}
   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
+
+  ${DIM}# With options${RESET}
   mekong-cli --with "next dev" --port 3000 --expire 2h
-  mekong-cli --with "next dev" --port 3000 --daemon
+  mekong-cli --with "vite" --port 5173 --daemon
+  mekong-cli --with "next dev" --port 3000 --no-qr
 
-${BOLD}INSTALL MEKONG BINARY${RESET}
-  Download from: https://github.com/MuyleangIng/MekongTunnel/releases/tag/v1.4.9
+  ${DIM}# Auto-setup script (run once in your project root)${RESET}
+  mekong-cli init
 
-  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
+${BOLD}INSTALL MEKONG BINARY${RESET}
+  Linux/macOS (auto-detect arch):
+    curl -fsSL https://github.com/MuyleangIng/MekongTunnel/releases/latest/download/mekong-\\$(uname -s | tr A-Z a-z)-\\$(uname -m) \\
+      -o ~/.local/bin/mekong && chmod +x ~/.local/bin/mekong
 
-  Windows: download mekong-windows-amd64.exe and place in PATH
+  Windows: download from https://github.com/MuyleangIng/MekongTunnel/releases/latest
 `;
 
 // ---------------------------------------------------------------------------
@@ -179,7 +194,20 @@ async function main() {
     return;
   }
 
-  // Tunnel-only mode: just proxy straight to mekong
+  // Tunnel-only mode: verify the port is actually listening before calling mekong
+  const isOpen = await checkPortOpen(port);
+  if (!isOpen) {
+    process.stderr.write(
+      `${RED}${BOLD}mekong-cli: nothing is listening on port ${port}.${RESET}\n\n` +
+      `  Start your server first, then run:\n` +
+      `    ${CYAN}mekong-cli ${port}${RESET}\n\n` +
+      `  Or let mekong-cli start it for you:\n` +
+      `    ${CYAN}mekong-cli --with "your-start-cmd" --port ${port}${RESET}\n\n` +
+      `  Or run ${CYAN}mekong-cli init${RESET} to set it up automatically.\n`
+    );
+    process.exit(1);
+  }
+
   const mekongArgs = [String(port)];
   if (opts.expire) mekongArgs.push('--expire', opts.expire);
   if (opts.daemon) mekongArgs.push('-d');

package/lib/wait-for-port.js

@@ -49,4 +49,27 @@ function waitForPort(port) {
   });
 }
 
-module.exports = { waitForPort };
+/**
+ * Single immediate check — resolves true if port is open right now, false otherwise.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function checkPortOpen(port) {
+  return new Promise((resolve) => {
+    const sock = new net.Socket();
+    let done = false;
+    function finish(open) {
+      if (done) return;
+      done = true;
+      sock.destroy();
+      resolve(open);
+    }
+    sock.setTimeout(1000);
+    sock.once('connect', () => finish(true));
+    sock.once('error',   () => finish(false));
+    sock.once('timeout', () => finish(false));
+    sock.connect(port, '127.0.0.1');
+  });
+}
+
+module.exports = { waitForPort, checkPortOpen };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mekong-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Run your dev server + Mekong tunnel in one command",
   "bin": {
     "mekong-cli": "bin/mekong-cli.js"