@vumotions/vm-tunnel 1.0.0

package/README.md

@@ -0,0 +1,185 @@
+<div align="center">
+
+# @vumotions/vm-tunnel
+
+[![npm version](https://img.shields.io/npm/v/@vumotions/vm-tunnel)](https://www.npmjs.com/package/@vumotions/vm-tunnel)
+[![license](https://img.shields.io/npm/l/@vumotions/vm-tunnel)](./LICENSE)
+[![node](https://img.shields.io/node/v/@vumotions/vm-tunnel)](https://nodejs.org)
+
+Cloudflare Tunnel CLI for local development.<br/>
+Exposes your local server to the internet with a **fixed URL** (Named Tunnel) or a **random URL** (Quick Tunnel) — zero config, reads from `.env`.
+
+</div>
+
+---
+
+## Features
+
+- **Named Tunnel** — fixed, persistent URL via your own domain (`dev-john-api.example.com`)
+- **Quick Tunnel** — zero-config random URL, no Cloudflare account needed
+- **Auto-fallback** — if `TUNNEL_HOST` is not set, falls back to Quick Tunnel automatically
+- **Process manager** — spawn your app alongside the tunnel with `--exec`
+- **Programmatic API** — use as a library in your own scripts
+
+---
+
+## Installation
+
+```bash
+npm install @vumotions/vm-tunnel
+# or globally
+npm install -g @vumotions/vm-tunnel
+```
+
+---
+
+## Quick Start
+
+Add to your project's `.env`:
+
+```env
+PORT=3000
+```
+
+Run:
+
+```bash
+vm-tunnel
+# => Quick Tunnel started at https://random-words.trycloudflare.com
+```
+
+---
+
+## Named Tunnel (fixed URL)
+
+Requires a Cloudflare account with a domain.
+
+### Prerequisites
+
+1. **Cloudflare account** with a domain added
+2. **API Token** with permissions: `Cloudflare Tunnel:Edit`, `DNS:Edit`
+3. **Account ID** from your Cloudflare dashboard
+4. **cloudflared** authenticated locally:
+   ```bash
+   cloudflared login
+   # Opens browser → select your domain → cert.pem saved to ~/.cloudflared/cert.pem
+   ```
+
+### Setup
+
+Add to `.env`:
+
+```env
+PORT=3000
+TUNNEL_HOST=dev-john-api.example.com
+CF_API_TOKEN=your_api_token
+CF_ACCOUNT_ID=your_account_id
+```
+
+Run:
+
+```bash
+vm-tunnel
+# => Named Tunnel running at https://dev-john-api.example.com
+```
+
+The tunnel name is derived from the first segment of your hostname (`dev-john-api`). DNS CNAME is created automatically on first run and reused on subsequent runs.
+
+---
+
+## CLI Reference
+
+```
+Usage: vm-tunnel [options]
+
+Options:
+  --host <host>       Tunnel hostname (overrides TUNNEL_HOST env)
+  --port <port>       Local app port (overrides PORT env)
+  --exec <command>    App command to run alongside the tunnel
+  -h, --help          Display help
+```
+
+### Examples
+
+```bash
+# Quick Tunnel on port 3000
+vm-tunnel --port 3000
+
+# Named Tunnel with inline options
+vm-tunnel --host dev-john-api.example.com --port 3000
+
+# Start app + tunnel in one command
+vm-tunnel --exec "nest start --watch"
+
+# Inline everything
+vm-tunnel --host dev-john-api.example.com --port 3000 --exec "nest start --watch"
+```
+
+### Typical `package.json` integration
+
+```json
+{
+  "scripts": {
+    "dev": "vm-tunnel --exec \"nest start --watch\""
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable         | Required | Description                                          |
+| ---------------- | -------- | ---------------------------------------------------- |
+| `PORT`           | Yes      | Local port your app runs on                          |
+| `TUNNEL_HOST`    | No       | Fixed hostname for Named Tunnel (e.g. `dev-john-api.example.com`). If omitted, uses Quick Tunnel |
+| `CF_API_TOKEN`   | Named    | Cloudflare API token (required when `TUNNEL_HOST` is set) |
+| `CF_ACCOUNT_ID`  | Named    | Cloudflare account ID (required when `TUNNEL_HOST` is set) |
+
+> Variables are loaded from `.env` in the current working directory. CLI flags take precedence over env vars.
+
+---
+
+## Programmatic API
+
+```ts
+import { startNamedTunnel, startQuickTunnel, loadEnv } from '@vumotions/vm-tunnel'
+
+// Quick Tunnel
+const url = await startQuickTunnel('3000')
+console.log(url) // https://random-words.trycloudflare.com
+
+// Named Tunnel
+const url = await startNamedTunnel(
+  'dev-john-api.example.com',
+  '3000',
+  process.env.CF_API_TOKEN!,
+  process.env.CF_ACCOUNT_ID!
+)
+console.log(url) // https://dev-john-api.example.com
+```
+
+---
+
+## How It Works
+
+```
+Your app (localhost:PORT)
+       │
+       ▼
+  cloudflared  ──── outbound HTTPS ────▶  Cloudflare Edge
+                                               │
+                                    TUNNEL_HOST DNS CNAME
+                                               │
+                                    ◀── internet traffic
+```
+
+- **Named Tunnel**: creates a tunnel via Cloudflare API, sets a DNS CNAME pointing to the tunnel ID, and starts `cloudflared` with a token. The URL is always the same.
+- **Quick Tunnel**: starts `cloudflared` with no credentials, gets a temporary random URL from Cloudflare. No account required.
+- All connections are **outbound** from your machine — no inbound ports need to be opened.
+
+---
+
+## License
+
+MIT

package/bin/vm-tunnel.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js'

package/dist/chunk-YXAF7B6G.js

@@ -0,0 +1,100 @@
+// src/utils/env.ts
+import dotenv from "dotenv";
+import path from "path";
+dotenv.config({ path: path.resolve(process.cwd(), ".env") });
+function loadEnv(overrides = {}) {
+  const port = overrides.port ?? process.env.PORT;
+  if (!port) throw new Error("PORT is required. Please set PORT in your .env file.");
+  return {
+    port,
+    tunnelHost: overrides.tunnelHost ?? process.env.TUNNEL_HOST,
+    cfApiToken: overrides.cfApiToken ?? process.env.CF_API_TOKEN,
+    cfAccountId: overrides.cfAccountId ?? process.env.CF_ACCOUNT_ID
+  };
+}
+
+// src/tunnel/named.ts
+import Cloudflare from "cloudflare";
+import { Tunnel } from "cloudflared";
+import fs from "fs";
+import os from "os";
+import path2 from "path";
+var CERT_PATH = path2.join(os.homedir(), ".cloudflared", "cert.pem");
+function getTunnelName(host) {
+  return host.split(".")[0];
+}
+async function getOrCreateTunnel(cf, accountId, name) {
+  for await (const t of cf.zeroTrust.tunnels.cloudflared.list({ account_id: accountId, name })) {
+    if (t.name === name && !t.deleted_at && t.id) {
+      console.log(`[vm-tunnel] Reusing existing tunnel: ${name} (${t.id})`);
+      const token2 = await cf.zeroTrust.tunnels.cloudflared.token.get(t.id, { account_id: accountId });
+      return { id: t.id, token: token2 };
+    }
+  }
+  console.log(`[vm-tunnel] Creating tunnel: ${name}`);
+  const created = await cf.zeroTrust.tunnels.cloudflared.create({ account_id: accountId, name });
+  if (!created.id) throw new Error(`[vm-tunnel] Failed to create tunnel: no ID returned`);
+  const token = await cf.zeroTrust.tunnels.cloudflared.token.get(created.id, { account_id: accountId });
+  return { id: created.id, token };
+}
+async function getZoneId(cf, host) {
+  const domain = host.split(".").slice(-2).join(".");
+  for await (const zone of cf.zones.list({ name: domain })) {
+    return zone.id;
+  }
+  throw new Error(`[vm-tunnel] Zone not found for domain: ${domain}`);
+}
+async function ensureDnsRecord(cf, zoneId, host, tunnelId) {
+  const cname = `${tunnelId}.cfargotunnel.com`;
+  for await (const record of cf.dns.records.list({ zone_id: zoneId, name: { exact: host }, type: "CNAME" })) {
+    if (record.name === host) {
+      console.log(`[vm-tunnel] DNS CNAME already exists: ${host} \u2192 ${cname}`);
+      return;
+    }
+  }
+  console.log(`[vm-tunnel] Creating DNS CNAME: ${host} \u2192 ${cname}`);
+  await cf.dns.records.create({ zone_id: zoneId, type: "CNAME", name: host, content: cname, proxied: true, ttl: 1 });
+}
+async function startNamedTunnel(host, port, apiToken, accountId) {
+  if (!fs.existsSync(CERT_PATH)) {
+    throw new Error(`[vm-tunnel] cert.pem not found at ${CERT_PATH}. Run: cloudflared login`);
+  }
+  const cf = new Cloudflare({ apiToken });
+  const name = getTunnelName(host);
+  const { id: tunnelId, token } = await getOrCreateTunnel(cf, accountId, name);
+  const zoneId = await getZoneId(cf, host);
+  await ensureDnsRecord(cf, zoneId, host, tunnelId);
+  console.log(`[vm-tunnel] Starting Named Tunnel: https://${host} \u2192 http://localhost:${port}`);
+  const t = Tunnel.withToken(token);
+  await new Promise((resolve, reject) => {
+    t.once("connected", () => resolve());
+    t.once("error", reject);
+    t.once("exit", (code) => reject(new Error(`cloudflared exited with code ${code}`)));
+  });
+  console.log(`[vm-tunnel] Tunnel running at https://${host}`);
+  process.on("SIGINT", () => t.stop());
+  process.on("SIGTERM", () => t.stop());
+  return `https://${host}`;
+}
+
+// src/tunnel/quick.ts
+import { Tunnel as Tunnel2 } from "cloudflared";
+async function startQuickTunnel(port) {
+  console.log(`[vm-tunnel] TUNNEL_HOST not set \u2014 starting Quick Tunnel on port ${port}...`);
+  const t = Tunnel2.quick(`http://localhost:${port}`);
+  const url = await new Promise((resolve, reject) => {
+    t.once("url", resolve);
+    t.once("error", reject);
+    t.once("exit", (code) => reject(new Error(`cloudflared exited with code ${code}`)));
+  });
+  console.log(`[vm-tunnel] Quick Tunnel running at ${url}`);
+  process.on("SIGINT", () => t.stop());
+  process.on("SIGTERM", () => t.stop());
+  return url;
+}
+
+export {
+  loadEnv,
+  startNamedTunnel,
+  startQuickTunnel
+};

package/dist/cli.js

@@ -0,0 +1,36 @@
+import {
+  loadEnv,
+  startNamedTunnel,
+  startQuickTunnel
+} from "./chunk-YXAF7B6G.js";
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/utils/process.ts
+import { spawn } from "child_process";
+function spawnApp(exec) {
+  const [cmd, ...args] = exec.split(" ");
+  const child = spawn(cmd, args, { shell: true, stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(`[vm-tunnel] Failed to start app: ${err.message}`);
+    process.exit(1);
+  });
+  process.on("SIGINT", () => child.kill("SIGINT"));
+  process.on("SIGTERM", () => child.kill("SIGTERM"));
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("vm-tunnel").description("Cloudflare tunnel CLI for local development").option("--host <host>", "Tunnel hostname (overrides TUNNEL_HOST)").option("--port <port>", "Local app port (overrides PORT)").option("--exec <command>", "App command to run alongside tunnel").action(async (options) => {
+  const env = loadEnv({ tunnelHost: options.host, port: options.port });
+  if (options.exec) spawnApp(options.exec);
+  if (env.tunnelHost) {
+    if (!env.cfApiToken) throw new Error("[vm-tunnel] CF_API_TOKEN is required for Named Tunnel.");
+    if (!env.cfAccountId) throw new Error("[vm-tunnel] CF_ACCOUNT_ID is required for Named Tunnel.");
+    await startNamedTunnel(env.tunnelHost, env.port, env.cfApiToken, env.cfAccountId);
+  } else {
+    await startQuickTunnel(env.port);
+  }
+});
+program.parse();

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  loadEnv,
+  startNamedTunnel,
+  startQuickTunnel
+} from "./chunk-YXAF7B6G.js";
+export {
+  loadEnv,
+  startNamedTunnel,
+  startQuickTunnel
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@vumotions/vm-tunnel",
+  "version": "1.0.0",
+  "description": "Cloudflare Named Tunnel and Quick Tunnel CLI for local development",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "vm-tunnel": "./bin/vm-tunnel.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "keywords": ["cloudflare", "tunnel", "dev", "shopify"],
+  "author": "vumotions",
+  "license": "MIT",
+  "dependencies": {
+    "cloudflare": "^5.2.0",
+    "cloudflared": "^0.7.1",
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2"
+  }
+}