localpeek 1.0.0

package/GUIDE.md

@@ -0,0 +1,128 @@
+# LocalPeek Guide
+
+Simple words. No jargon. Read this if something is confusing.
+
+## What LocalPeek do
+
+You build website on computer. Computer show website at `localhost`. Phone cannot see `localhost` — phone not the same computer.
+
+LocalPeek find real address of your computer on your Wi-Fi (like `192.168.1.5`). LocalPeek make QR code with that address. You scan QR with phone. Phone open website. Done.
+
+No cloud. No upload. No account. Just computer and phone talking on same Wi-Fi, direct.
+
+## Install
+
+Global install (use anywhere):
+
+```bash
+npm install -g localpeek
+```
+
+Or skip install, run once:
+
+```bash
+npx localpeek
+```
+
+## Basic use
+
+Go to your project folder. Run command:
+
+```bash
+localpeek
+```
+
+or short version:
+
+```bash
+lp
+```
+
+LocalPeek do rest:
+
+1. Look at folder. Guess what kind of project (plain HTML? Vite? Next.js? Astro? something else?).
+2. Start dev server, correct way, so phone can reach it.
+3. Find your computer's Wi-Fi address.
+4. Print QR code in terminal.
+5. Show URL too, in case QR scan hard.
+
+Scan QR with phone camera. Website open.
+
+Stop anytime: press `Ctrl+C`.
+
+## Supported project types
+
+- Plain HTML/CSS/JS (just an `index.html`)
+- Vite
+- Next.js
+- Astro
+- Vue, Nuxt, Svelte, SvelteKit, Angular, Remix — LocalPeek use your project's own `dev` script and try to point it at right address
+- Any other npm project with a `dev` script in `package.json`
+
+LocalPeek never change your project files. LocalPeek only read, never write.
+
+## LAN requirement (important!)
+
+Computer and phone must be on **same network**.
+
+Good:
+- Both on same Wi-Fi router.
+- Phone connect to computer's Mobile Hotspot, computer use that hotspot's network.
+
+Bad (will not work):
+- Computer on Wi-Fi, phone on mobile data (4G/5G). Different network, no connection possible.
+- Computer connected through VPN. VPN can hide or change your real address. Try disconnecting VPN if QR doesn't work.
+- Phone and computer on same Wi-Fi, but router use "client isolation" or "AP isolation" (common on public/office/guest Wi-Fi, and even some home routers). This blocks devices from seeing each other even on same network. Try a different network, or check router settings.
+
+## Phone hotspot behavior
+
+Using phone as hotspot for the computer? That's fine — same rule applies, both devices need to be on the same network. When phone is the hotspot, computer connects to phone's network, and things should just work the same way.
+
+## Firewall
+
+Your computer's firewall might block incoming connections on the dev server's port. LocalPeek does **not** touch your firewall automatically (that would be risky to do blindly).
+
+If your phone times out trying to connect:
+
+- **Windows**: Windows Defender Firewall may ask permission the first time Node.js tries to accept a network connection. Allow it for Private networks.
+- **macOS**: System Settings → Network → Firewall may block incoming connections to `node`. Allow it, or temporarily turn off firewall to test.
+- **Linux**: check `ufw` or your distro's firewall tool; you may need to allow the port.
+
+## Common errors, explained
+
+**"No project found in [folder]"**
+LocalPeek looked in that folder and found no `index.html` and no usable `package.json`. Make sure you're in the right folder.
+
+**"This project has a package.json but no installed dependencies"**
+Your project needs `npm install` (or `yarn`/`pnpm install`) run first. LocalPeek never installs things for you — that's your call.
+
+**"No usable LAN network address was found on this computer"**
+LocalPeek couldn't find a normal Wi-Fi/Ethernet address. Usually means you're not connected to any network, or you're only connected through virtual adapters (VPN, Docker, VM). Connect to real Wi-Fi/Ethernet and try again.
+
+**"Port already in use" / "Port X was busy — using Y instead"**
+Something else is already using that port. LocalPeek just picks the next free one automatically. If LocalPeek instead says it's *reusing* a server on that port, that's because something already running there looks like your project — LocalPeek shows you the QR for it instead of starting a duplicate.
+
+**Phone scans QR but page never loads**
+Almost always one of: different networks, VPN in the way, router client isolation, or firewall blocking the port. See sections above.
+
+## How framework detection works
+
+LocalPeek looks (only reads, never edits) at:
+
+- `package.json` — dependencies, devDependencies, and the `scripts.dev` entry
+- Known config files — `vite.config.*`, `next.config.*`, `astro.config.*`, `nuxt.config.*`, `angular.json`, `svelte.config.js`, etc.
+- Whether `node_modules` exists
+
+It checks specific frameworks first (Next.js, Astro, SvelteKit, etc.), then falls back to Vite, then to any project with a `dev` script, then to plain HTML if there's an `index.html`.
+
+LocalPeek always prefers your existing `dev` script over inventing its own command — it just adds flags (like `--host`) so the server is reachable from your phone, and picks a port.
+
+## Publishing / updating this package (for maintainers)
+
+1. Make your changes.
+2. Bump the version in `package.json` (`npm version patch` / `minor` / `major`).
+3. Log in once: `npm login`.
+4. Publish: `npm publish`.
+5. Tag the release in git and push tags: `git push --follow-tags`.
+
+That's it. No build step — LocalPeek ships as plain CommonJS.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dipto Thakur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+<div align="center">
+
+# LocalPeek
+
+**See your local dev project on your phone in 5 seconds zero cloud, zero tunnels, zero setup.**
+One command turns any `localhost` project into a scannable QR code on your own Wi-Fi.
+
+[![npm version](https://img.shields.io/npm/v/localpeek.svg)](https://www.npmjs.com/package/localpeek)
+[![npm downloads](https://img.shields.io/npm/dm/localpeek.svg)](https://www.npmjs.com/package/localpeek)
+[![license](https://img.shields.io/npm/l/localpeek.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/localpeek.svg)](https://nodejs.org)
+
+```bash
+npx localpeek
+```
+
+**That's it.** Scan the QR code. Your project opens on your phone.
+
+</div>
+
+---
+
+## Why LocalPeek
+
+Testing responsive design usually means deploying, tunneling through ngrok, or typing your laptop's IP address into your phone by hand. LocalPeek skips all of that.
+
+- ⚡ **One command, zero config** `npx localpeek` and you're done, no flags required
+- 🔒 **100% local, always** traffic never leaves your Wi-Fi network. No cloud relay, no account, no telemetry, no data collection
+- 📷 **Real terminal QR code** scan and go, no typing IP addresses on a phone keyboard
+- 🧠 **Auto-detects your stack** Plain HTML, Vite, Next.js, Astro, Vue, Nuxt, Svelte, SvelteKit, Angular, Remix
+- 🛡️ **Never touches your project files** read-only detection, your `dev` script stays the source of truth
+- 🖥️ **Cross-platform** Windows, macOS, Linux, WSL, and phone hotspots all work
+- 🪶 **Tiny footprint** one dependency, no bloated framework underneath
+
+If that saved you a `ngrok` signup or a "what's my IP" search, a ⭐ on the repo goes a long way it's how other developers find this instead of a heavier alternative.
+
+---
+
+## Install
+
+The whole point is that you usually don't need to install anything:
+
+```bash
+npx localpeek
+```
+
+Prefer it always available as a command:
+
+```bash
+npm install -g localpeek
+```
+
+```bash
+localpeek        # full command
+lp               # short alias
+```
+
+---
+
+## Usage
+
+```bash
+cd your-project
+localpeek
+```
+
+```bash
+localpeek                 # detect and run the current project
+localpeek --port 5000     # ask for a specific port
+localpeek --iface eth0    # prefer a specific network interface
+localpeek --dir ../app    # point at a different project folder
+localpeek --help          # see all options
+```
+
+## What happens under the hood
+
+1. Reads the current folder and figures out what kind of project it is.
+2. Starts (or reuses) the dev server, bound so your **phone** can reach it not just `localhost`.
+3. Finds your computer's real LAN IP address (skipping VPNs, Docker, and virtual adapters).
+4. Renders a QR code directly in your terminal no image file, no upload, no third-party API.
+5. You scan it. Your phone opens the project. Live-reload, dev tools, everything works as normal.
+
+Nothing here talks to the internet. LocalPeek never sends your project, your code, your IP, or anything else off of your machine.
+
+---
+
+## Supported projects
+
+| Project type | Support |
+|---|---|
+| Plain HTML/CSS/JS | ✅ built-in static server |
+| Vite | ✅ native adapter |
+| Next.js | ✅ native adapter |
+| Astro | ✅ native adapter |
+| Vue, Nuxt, Svelte, SvelteKit, Angular, Remix | ✅ via generic adapter (reuses your `dev` script) |
+| Anything else with a `dev` script | ✅ generic fallback |
+
+## Specs
+
+| | |
+|---|---|
+| **Dependencies** | 1 (`qrcode-terminal`) |
+| **Requires** | Node.js ≥ 16 |
+| **Platforms** | Windows · macOS · Linux · WSL |
+| **Network** | Same-LAN only Wi-Fi, Ethernet, or phone hotspot |
+| **Cloud/telemetry** | None. Ever. |
+| **Project files** | Read-only never modified |
+
+Full setup requirements, firewall notes, and troubleshooting: see **[GUIDE.md](./GUIDE.md)**.
+
+---
+
+## Support the project
+
+If LocalPeek saved you time:
+
+- ⭐ **[Star the repo](https://github.com/dipto-thakur/localpeek)** the easiest way to help others find it
+- 🐛 Open an issue if something breaks on your setup
+- 👀 **[Follow @dipto-thakur](https://github.com/dipto-thakur)** for more small, focused dev tools like this one
+
+## License
+
+MIT see [LICENSE](./LICENSE).
+
+Built by [Dipto Thakur](https://github.com/dipto-thakur).

package/bin/localpeek.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+'use strict';
+
+// CAVEMAN: This file just hands off to src/cli.js.
+// Keep it tiny so `require` overhead on startup stays low.
+
+const { run } = require('../src/cli.js');
+
+run(process.argv.slice(2)).catch((err) => {
+  // Last-resort catch. Anything expected should already be handled
+  // inside cli.js with a friendly message. This is only for truly
+  // unexpected crashes.
+  // eslint-disable-next-line no-console
+  console.error('\nLocalPeek hit an unexpected error:\n');
+  // eslint-disable-next-line no-console
+  console.error(err && err.stack ? err.stack : err);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "localpeek",
+  "version": "1.0.0",
+  "description": "Open your local dev project on your phone over LAN. Zero cloud, zero tunnels, zero setup.",
+  "keywords": [
+    "cli",
+    "lan",
+    "dev-server",
+    "qr-code",
+    "mobile",
+    "localhost",
+    "vite",
+    "nextjs"
+  ],
+  "homepage": "https://github.com/dipto-thakur/localpeek",
+  "bugs": {
+    "url": "https://github.com/dipto-thakur/localpeek/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dipto-thakur/localpeek.git"
+  },
+  "license": "MIT",
+  "author": "Dipto Thakur (https://github.com/dipto-thakur)",
+  "type": "commonjs",
+  "main": "src/cli.js",
+  "bin": {
+    "localpeek": "bin/localpeek.js",
+    "lp": "bin/localpeek.js"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "GUIDE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/run.js"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/adapters/astro.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// CAVEMAN: Astro's dev CLI takes --host and --port, same shape as Vite
+// (Astro is built on Vite under the hood).
+
+const DEFAULT_PORT = 4321;
+
+function buildCommand({ project, port, host }) {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+
+  if (project.devScript) {
+    return {
+      command: npmCmd,
+      args: ['run', 'dev', '--', '--host', host, '--port', String(port)],
+      env: process.env,
+    };
+  }
+
+  return {
+    command: npxCmd,
+    args: ['astro', 'dev', '--host', host, '--port', String(port)],
+    env: process.env,
+  };
+}
+
+module.exports = { buildCommand, DEFAULT_PORT };

package/src/adapters/generic.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// CAVEMAN: Generic fallback for any framework we don't special-case
+// (Vue, Nuxt, Svelte/SvelteKit, Angular, Remix, or literally anything
+// with a "dev" script). We never invent a command that doesn't exist
+// in the project — we reuse `scripts.dev` and just try to steer it
+// onto the right host/port using common conventions.
+//
+// Strategy, in order of harmlessness:
+//   1. Set PORT and HOST env vars (respected by a lot of tooling).
+//   2. Append framework-appropriate CLI flags after `--`, if the
+//      caller supplied any (see detect.js `defaultFlags`).
+//
+// If none of this works for a particular tool, LocalPeek still shows
+// the correct LAN URL — worst case the user needs to pass their own
+// host flag, which the terminal output points them toward.
+
+function buildCommand({ project, port, host }) {
+  const extraFlags = project.defaultFlags || [];
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+  const args = ['run', 'dev'];
+  if (extraFlags.length > 0) {
+    args.push('--', ...extraFlags, '--port', String(port));
+  }
+
+  return {
+    command: npmCmd,
+    args,
+    env: {
+      ...process.env,
+      PORT: String(port),
+      HOST: host,
+    },
+  };
+}
+
+module.exports = { buildCommand };

package/src/adapters/html.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+// CAVEMAN: This is a plain, dependency-free static file server.
+// Only used when there is no framework and no package.json dev
+// script — just an index.html sitting in a folder.
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+};
+
+function safeJoin(root, urlPath) {
+  const decoded = decodeURIComponent(urlPath.split('?')[0]);
+  const resolved = path.normalize(path.join(root, decoded));
+  // CAVEMAN: Block path traversal (../../etc/passwd style requests).
+  if (!resolved.startsWith(path.normalize(root))) {
+    return null;
+  }
+  return resolved;
+}
+
+/**
+ * Starts a static file server rooted at `dir`, listening on
+ * `host:port`. Resolves with the http.Server instance once listening.
+ */
+function startStaticServer(dir, port, host) {
+  const server = http.createServer((req, res) => {
+    let filePath = safeJoin(dir, req.url || '/');
+
+    if (!filePath) {
+      res.writeHead(400);
+      res.end('Bad request');
+      return;
+    }
+
+    fs.stat(filePath, (err, stats) => {
+      if (!err && stats.isDirectory()) {
+        filePath = path.join(filePath, 'index.html');
+      }
+
+      fs.readFile(filePath, (readErr, data) => {
+        if (readErr) {
+          // Fall back to root index.html for simple client-side
+          // routing setups; otherwise a plain 404.
+          const fallback = path.join(dir, 'index.html');
+          if (filePath !== fallback) {
+            fs.readFile(fallback, (fallbackErr, fallbackData) => {
+              if (fallbackErr) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('404 Not Found');
+              } else {
+                res.writeHead(200, { 'Content-Type': MIME_TYPES['.html'] });
+                res.end(fallbackData);
+              }
+            });
+            return;
+          }
+          res.writeHead(404, { 'Content-Type': 'text/plain' });
+          res.end('404 Not Found');
+          return;
+        }
+
+        const ext = path.extname(filePath).toLowerCase();
+        const mime = MIME_TYPES[ext] || 'application/octet-stream';
+        res.writeHead(200, { 'Content-Type': mime });
+        res.end(data);
+      });
+    });
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+module.exports = { startStaticServer };

package/src/adapters/next.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// CAVEMAN: Next's dev CLI takes -H (hostname) and -p (port).
+// Binding -H 0.0.0.0 is what actually makes it reachable from
+// another device on the LAN — the default is often localhost-only.
+
+const DEFAULT_PORT = 3000;
+
+function buildCommand({ project, port, host }) {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+
+  if (project.devScript) {
+    return {
+      command: npmCmd,
+      args: ['run', 'dev', '--', '-H', host, '-p', String(port)],
+      env: process.env,
+    };
+  }
+
+  return {
+    command: npxCmd,
+    args: ['next', 'dev', '-H', host, '-p', String(port)],
+    env: process.env,
+  };
+}
+
+module.exports = { buildCommand, DEFAULT_PORT };

package/src/adapters/vite.js

@@ -0,0 +1,30 @@
+'use strict';
+
+// CAVEMAN: Vite already understands --host and --port natively.
+// Prefer the project's own "dev" script (it may set up plugins,
+// env files, etc.) and just append flags after `--`.
+
+const DEFAULT_PORT = 5173;
+
+function buildCommand({ project, port, host }) {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+
+  if (project.devScript) {
+    return {
+      command: npmCmd,
+      args: ['run', 'dev', '--', '--host', host, '--port', String(port), '--strictPort'],
+      env: process.env,
+    };
+  }
+
+  // No dev script (unlikely for a real Vite project, but possible
+  // for a minimal setup) — call the Vite CLI directly.
+  return {
+    command: npxCmd,
+    args: ['vite', '--host', host, '--port', String(port), '--strictPort'],
+    env: process.env,
+  };
+}
+
+module.exports = { buildCommand, DEFAULT_PORT };