@o-town/local.dev 1.0.0

package/.vscode/settings.json

@@ -0,0 +1 @@
+{}

package/README.md

@@ -0,0 +1,144 @@
+# local.dev
+
+> Expose your local website to the internet — instantly. No signup, no config.
+
+```
+npx local.dev 3000
+```
+
+---
+
+## Install
+
+```bash
+npm install -g local.dev
+```
+
+Or use without installing:
+
+```bash
+npx local.dev 3000
+```
+
+---
+
+## CLI Usage
+
+```
+local.dev [port] [options]
+```
+
+### Arguments
+
+| Argument | Description              | Default |
+|----------|--------------------------|---------|
+| `port`   | Local port to expose     | `3000`  |
+
+### Options
+
+| Flag                  | Alias | Description                              |
+|-----------------------|-------|------------------------------------------|
+| `--subdomain`         | `-s`  | Request a custom subdomain               |
+| `--host`              | `-H`  | Local host to tunnel (default: localhost)|
+| `--qr`                | `-q`  | Show QR code for the public URL          |
+| `--open`              | `-o`  | Open tunnel URL in your browser          |
+| `--print-requests`    | `-r`  | Log incoming HTTP requests               |
+| `--help`              | `-h`  | Show help                                |
+| `--version`           | `-v`  | Show version number                      |
+
+### Examples
+
+```bash
+# Expose port 3000
+local.dev 3000
+
+# Expose port 8080 with a custom subdomain
+local.dev 8080 --subdomain myapp
+
+# Show QR code (great for mobile testing)
+local.dev 3000 --qr
+
+# Open tunnel URL in browser + log requests
+local.dev 3000 --open --print-requests
+
+# Expose a non-localhost server
+local.dev 3000 --host 192.168.1.10
+```
+
+---
+
+## Programmatic API
+
+You can also use `local.dev` as a Node.js library:
+
+```js
+const { tunnel } = require('local.dev');
+
+async function main() {
+  // Simple: just pass a port
+  const t = await tunnel(3000);
+  console.log('Public URL:', t.url);
+
+  // Stop the tunnel when done
+  t.close();
+}
+
+main();
+```
+
+### With options
+
+```js
+const t = await tunnel({
+  port: 8080,
+  subdomain: 'myapp',
+  host: 'localhost',
+  printRequests: true,
+});
+
+console.log(t.url); // https://myapp.loca.lt
+
+t.on('request', (info) => {
+  console.log(info.method, info.path, info.statusCode);
+});
+
+t.on('close', () => {
+  console.log('Tunnel closed');
+});
+```
+
+### API Reference
+
+#### `tunnel(port, [options])` → `Promise<TunnelHandle>`
+#### `tunnel(options)` → `Promise<TunnelHandle>`
+
+**Options:**
+
+| Property        | Type    | Description                          |
+|-----------------|---------|--------------------------------------|
+| `port`          | number  | **Required.** Local port to expose   |
+| `host`          | string  | Local host (default: `'localhost'`)  |
+| `subdomain`     | string  | Requested subdomain                  |
+| `printRequests` | boolean | Log requests (default: `false`)      |
+
+#### `TunnelHandle`
+
+| Property/Method | Description                  |
+|-----------------|------------------------------|
+| `.url`          | The public HTTPS URL         |
+| `.close()`      | Close the tunnel             |
+| `.on('request', cb)` | Fired on each HTTP request |
+| `.on('close', cb)` | Fired when tunnel closes   |
+| `.on('error', cb)` | Fired on tunnel errors     |
+
+---
+
+## How it works
+
+`local.dev` creates a secure tunnel from a public URL to your local machine using the [localtunnel](https://github.com/localtunnel/localtunnel) protocol. Incoming requests hit the public URL and are proxied through to your local server — no port forwarding or firewall changes needed.
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const yargs = require('yargs/yargs');
+const { hideBin } = require('yargs/helpers');
+const chalk = require('chalk');
+const ora = require('ora');
+const qrcode = require('qrcode-terminal');
+const { createTunnel } = require('../lib/tunnel');
+const { printBanner, printSuccess, printInfo, printError } = require('../lib/ui');
+const updateNotifier = require('update-notifier');
+const pkg = require('../package.json');
+
+// Check for updates silently
+updateNotifier({ pkg }).notify();
+
+const argv = yargs(hideBin(process.argv))
+  .usage(`\n${chalk.cyan('local.dev')} — expose your local server to the internet\n\nUsage: $0 [port] [options]`)
+  .command('$0 [port]', 'Start a tunnel to your local server', (yargs) => {
+    yargs.positional('port', {
+      describe: 'Local port to expose',
+      type: 'number',
+      default: 3000,
+    });
+  })
+  .option('subdomain', {
+    alias: 's',
+    type: 'string',
+    describe: 'Request a specific subdomain (e.g. myapp)',
+  })
+  .option('host', {
+    alias: 'H',
+    type: 'string',
+    describe: 'Local host to tunnel (default: localhost)',
+    default: 'localhost',
+  })
+  .option('qr', {
+    alias: 'q',
+    type: 'boolean',
+    describe: 'Show QR code for the tunnel URL',
+    default: false,
+  })
+  .option('open', {
+    alias: 'o',
+    type: 'boolean',
+    describe: 'Open the tunnel URL in browser',
+    default: false,
+  })
+  .option('print-requests', {
+    alias: 'r',
+    type: 'boolean',
+    describe: 'Print incoming requests to stdout',
+    default: false,
+  })
+  .example('$0 3000', 'Expose localhost:3000')
+  .example('$0 8080 --subdomain myapp', 'Expose localhost:8080 as myapp.loca.lt')
+  .example('$0 5000 --qr', 'Show QR code for mobile testing')
+  .epilog(chalk.gray('Docs: https://localdev.sh  •  Issues: https://github.com/yourusername/local.dev'))
+  .argv;
+
+async function main() {
+  printBanner();
+
+  const port = argv.port || 3000;
+  const host = argv.host || 'localhost';
+
+  printInfo(`Tunneling ${chalk.yellow(`${host}:${port}`)} to the internet...`);
+
+  const spinner = ora({
+    text: 'Establishing secure tunnel...',
+    color: 'cyan',
+  }).start();
+
+  try {
+    const tunnel = await createTunnel({
+      port,
+      host,
+      subdomain: argv.subdomain,
+      printRequests: argv['print-requests'],
+    });
+
+    spinner.stop();
+
+    printSuccess(tunnel.url);
+
+    if (argv.qr) {
+      console.log('\n' + chalk.gray('  Scan to open on mobile:'));
+      qrcode.generate(tunnel.url, { small: true }, (qr) => {
+        qr.split('\n').forEach(line => console.log('  ' + line));
+      });
+    }
+
+    if (argv.open) {
+      const { exec } = require('child_process');
+      const openCmd = process.platform === 'darwin' ? 'open' :
+        process.platform === 'win32' ? 'start' : 'xdg-open';
+      exec(`${openCmd} ${tunnel.url}`);
+    }
+
+    console.log('');
+    console.log(chalk.gray('  Press Ctrl+C to stop the tunnel'));
+    console.log('');
+
+    // Handle incoming request logging
+    if (argv['print-requests']) {
+      tunnel.on('request', (info) => {
+        const time = new Date().toLocaleTimeString();
+        const method = chalk.cyan(info.method.padEnd(6));
+        const status = info.statusCode >= 400
+          ? chalk.red(info.statusCode)
+          : chalk.green(info.statusCode);
+        console.log(`  ${chalk.gray(time)}  ${method} ${status}  ${chalk.white(info.path)}`);
+      });
+    }
+
+    // Graceful shutdown
+    process.on('SIGINT', async () => {
+      console.log('\n' + chalk.gray('  Closing tunnel...'));
+      tunnel.close();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', async () => {
+      tunnel.close();
+      process.exit(0);
+    });
+
+  } catch (err) {
+    spinner.fail('Failed to create tunnel');
+    printError(err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/example.js

@@ -0,0 +1,37 @@
+/**
+ * local.dev — programmatic usage example
+ *
+ * Run:  node example.js
+ * (Make sure you have a server running on port 3000 first)
+ */
+
+const { tunnel } = require('./lib/index');
+
+async function main() {
+  console.log('Opening tunnel to localhost:3000...');
+
+  const t = await tunnel(3000);
+
+  console.log('');
+  console.log('✔  Public URL:', t.url);
+  console.log('');
+  console.log('Listening for requests... (Ctrl+C to stop)');
+
+  t.on('request', (info) => {
+    console.log(`  ${info.method} ${info.path} → ${info.statusCode}`);
+  });
+
+  t.on('close', () => {
+    console.log('Tunnel closed.');
+  });
+
+  process.on('SIGINT', () => {
+    t.close();
+    process.exit(0);
+  });
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * local.dev — Expose your local server to the internet.
+ *
+ * Programmatic API:
+ *
+ *   const { tunnel } = require('local.dev');
+ *
+ *   const t = await tunnel(3000);
+ *   console.log('Public URL:', t.url);
+ *
+ *   // Later:
+ *   t.close();
+ */
+
+const { createTunnel, TunnelHandle } = require('./tunnel');
+
+/**
+ * Open a tunnel to a local port.
+ *
+ * @param {number|object} portOrOptions - Port number, or options object
+ * @param {object} [options]            - Options (if first arg is a port)
+ * @returns {Promise<TunnelHandle>}
+ *
+ * @example
+ * // Simple usage
+ * const t = await tunnel(3000);
+ * console.log(t.url); // https://xyz.loca.lt
+ * t.close();
+ *
+ * @example
+ * // With options
+ * const t = await tunnel({ port: 8080, subdomain: 'myapp' });
+ */
+async function tunnel(portOrOptions, options = {}) {
+  let opts;
+
+  if (typeof portOrOptions === 'number') {
+    opts = { port: portOrOptions, ...options };
+  } else if (typeof portOrOptions === 'object' && portOrOptions !== null) {
+    opts = portOrOptions;
+  } else {
+    throw new TypeError('First argument must be a port number or options object');
+  }
+
+  return createTunnel(opts);
+}
+
+module.exports = {
+  tunnel,
+  createTunnel,
+  TunnelHandle,
+};

package/lib/tunnel.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const localtunnel = require('localtunnel');
+const EventEmitter = require('events');
+
+/**
+ * Creates a tunnel to expose a local port to the internet.
+ *
+ * @param {object} options
+ * @param {number} options.port       - Local port to expose
+ * @param {string} [options.host]     - Local host (default: localhost)
+ * @param {string} [options.subdomain] - Requested subdomain
+ * @param {boolean} [options.printRequests] - Log incoming requests
+ * @returns {Promise<TunnelHandle>}
+ */
+async function createTunnel(options = {}) {
+  const {
+    port,
+    host = 'localhost',
+    subdomain,
+    printRequests = false,
+  } = options;
+
+  if (!port || typeof port !== 'number' || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${port}. Must be a number between 1 and 65535.`);
+  }
+
+  const tunnelOptions = {
+    port,
+    local_host: host,
+    allow_invalid_cert: false,
+  };
+
+  if (subdomain) {
+    tunnelOptions.subdomain = subdomain;
+  }
+
+  const tunnel = await localtunnel(tunnelOptions);
+
+  const handle = new TunnelHandle(tunnel, { printRequests });
+  return handle;
+}
+
+class TunnelHandle extends EventEmitter {
+  constructor(tunnel, options = {}) {
+    super();
+    this._tunnel = tunnel;
+    this.url = tunnel.url;
+
+    // Proxy tunnel events
+    tunnel.on('close', () => {
+      this.emit('close');
+    });
+
+    tunnel.on('error', (err) => {
+      this.emit('error', err);
+    });
+
+    tunnel.on('request', (info) => {
+      this.emit('request', info);
+    });
+  }
+
+  /**
+   * Close the tunnel and free resources.
+   */
+  close() {
+    this._tunnel.close();
+  }
+}
+
+module.exports = { createTunnel, TunnelHandle };

package/lib/ui.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const chalk = require('chalk');
+
+const BRAND = chalk.bold.cyan('local') + chalk.bold.white('.dev');
+
+function printBanner() {
+  console.log('');
+  console.log(`  ${BRAND}  ${chalk.gray('v' + require('../package.json').version)}`);
+  console.log(`  ${chalk.gray('Expose your local server to the internet')}`);
+  console.log('');
+}
+
+function printSuccess(url) {
+  const line = chalk.gray('─'.repeat(50));
+  console.log(`  ${line}`);
+  console.log('');
+  console.log(`  ${chalk.green('✔')}  Tunnel is ${chalk.green('live')}`);
+  console.log('');
+  console.log(`     ${chalk.gray('URL')}  ${chalk.bold.white(url)}`);
+  console.log('');
+  console.log(`  ${line}`);
+}
+
+function printInfo(msg) {
+  console.log(`  ${chalk.cyan('→')}  ${chalk.gray(msg)}`);
+}
+
+function printError(msg) {
+  console.log('');
+  console.log(`  ${chalk.red('✖')}  ${chalk.red('Error:')} ${msg}`);
+  console.log('');
+  console.log(`  ${chalk.gray('Troubleshooting:')}`);
+  console.log(`  ${chalk.gray('  • Is your local server running?')}`);
+  console.log(`  ${chalk.gray('  • Check the port number is correct')}`);
+  console.log(`  ${chalk.gray('  • Try: local.dev --help')}`);
+  console.log('');
+}
+
+module.exports = { printBanner, printSuccess, printInfo, printError };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@o-town/local.dev",
+  "version": "1.0.0",
+  "description": "Expose your local website to the internet instantly — no config, no signup.",
+  "main": "lib/index.js",
+  "bin": {
+    "local.dev": "./bin/cli.js",
+    "localdev": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "tunnel",
+    "localhost",
+    "expose",
+    "ngrok",
+    "local",
+    "dev",
+    "proxy",
+    "public-url"
+  ],
+  "author": "local.dev contributors",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "chalk": "^4.1.2",
+    "http-proxy": "^1.18.1",
+    "localtunnel": "^1.8.3",
+    "ora": "^5.4.1",
+    "qrcode-terminal": "^0.12.0",
+    "update-notifier": "^7.3.1",
+    "ws": "^8.16.0",
+    "yargs": "^17.7.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/local.dev.git"
+  },
+  "homepage": "https://localdev.sh",
+  "bugs": {
+    "url": "https://github.com/yourusername/local.dev/issues"
+  }
+}