proxlens 1.2.1

package/README.md

@@ -0,0 +1,161 @@
+# Proxlens
+
+> Share your localhost with clients instantly. Built-in feedback widget, optional password protection, zero setup.
+
+Proxlens is an open-source Electron desktop app. It wraps your local dev server in a public HTTPS URL via Cloudflare Tunnel, injects a feedback widget into every page your client sees, and saves their feedback locally on your machine — no accounts, no hosting, no cost.
+
+---
+
+## What makes it different
+
+Most tunnel tools just give you a URL. Proxlens adds a layer that's actually useful for client work:
+
+- **Feedback widget** — automatically injected into every page. Clients click any element, leave a comment, hit Send. No browser extensions, no separate tool, no client setup required.
+- **Local feedback storage** — every submission is saved to a JSON file on your machine, visible in the Feedback tab, persistent across sessions. Works with zero configuration.
+- **GitHub Issues sync** — optional. If you configure a GitHub token and repo, feedback is also posted as Issues in a private repo you own. Useful for keeping a permanent record per project.
+- **Password protection** — optional. Set a password in Settings; clients see a branded password page before accessing the preview.
+
+---
+
+## Setup
+
+**Requirements:** Node.js 18+, npm
+
+```bash
+git clone https://github.com/Chiarinze/proxlens.git
+cd proxlens
+npm install
+npm start
+```
+
+That's it. No `.env` file. No API keys. No accounts. The app opens and works immediately.
+
+---
+
+## How feedback works
+
+### Default (no configuration needed)
+
+1. Start a tunnel on any port
+2. Send the URL to your client
+3. Client sees your site with a **Feedback** button in the bottom-right corner
+4. They click it, click any element on the page, type a comment, press Send
+5. You get a desktop notification immediately
+6. The feedback appears in the **Feedback tab** of the app
+7. It's saved permanently to your machine — still there the next time you open Proxlens
+
+### With GitHub Issues (optional upgrade)
+
+When you configure a GitHub token and private repo in Settings:
+
+- Feedback is saved locally **and** posted as a GitHub Issue in the background
+- The Issue includes the page URL, the element selector, and the client's comment
+- The feedback card in the app updates to show a link to the Issue
+- If GitHub fails for any reason, the local save is unaffected — the client never sees an error
+
+**To set up GitHub sync:**
+
+1. Create a private GitHub repo to collect feedback (e.g. `yourname/client-feedback`)
+2. Go to [github.com/settings/tokens/new](https://github.com/settings/tokens/new?scopes=repo&description=Proxlens), select the `repo` scope, generate the token
+3. In Proxlens → Settings, enter the token and repo name, click Test, then Save
+
+GitHub tokens expire. When yours expires, feedback will continue saving locally without interruption — you just won't get new Issues until you generate a fresh token and update Settings.
+
+---
+
+## Password protection
+
+1. Open Settings in the app
+2. Toggle **Require a password** on
+3. Type any password you want your client to use
+4. Click Save
+
+Clients see a simple password page before accessing the preview. The check happens locally in the proxy — the password never leaves your machine.
+
+---
+
+## Architecture
+
+```
+Client Browser
+     │  HTTPS
+     ▼
+Cloudflare Quick Tunnel  (free, temporary *.trycloudflare.com URL)
+     │
+     ▼
+Proxlens Proxy  (localhost:19xxx — runs silently on your machine)
+  ├─ Password gate (if enabled)
+  ├─ Injects feedback widget into all HTML responses
+  ├─ Handles /feedback submissions:
+  │    1. Saves to local JSON file immediately
+  │    2. Posts to GitHub Issues in background (if configured)
+  └─ Tracks visits → desktop + in-app notifications
+     │
+     ▼
+Your Dev Server  (localhost:3000 or whichever port you set)
+```
+
+---
+
+## Privacy & security
+
+- Settings (password, GitHub token) are stored in your OS user data folder via Electron's `app.getPath('userData')`. They are never uploaded anywhere.
+- Feedback is stored locally in the same folder as a plain JSON file.
+- Your GitHub token is only ever used to call `POST /repos/{owner}/{repo}/issues` on the repo you specify. It is never logged or transmitted to any Proxlens server (there is no Proxlens server).
+- The tunnel URL changes on every session. When you click Stop, the URL is dead instantly.
+
+---
+
+## Exporting feedback
+
+In the Feedback tab, click **Export JSON**. This opens the raw `proxlens-feedback.json` file from your user data folder. You can copy it, import it into a spreadsheet, or share it with a client directly.
+
+---
+
+## Contributing
+
+Contributions are welcome. To keep the codebase stable, all changes go through Pull Requests.
+
+**How to contribute:**
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feature/your-feature-name`
+3. Make your changes
+4. Commit with a clear message: `git commit -m "add: description of what you did"`
+5. Push to your fork: `git push origin feature/your-feature-name`
+6. Open a Pull Request describing what you changed and why
+
+**Before submitting a PR:**
+- Open an issue first for anything beyond small bug fixes, so we can discuss it before you invest time building it
+- Keep PRs focused — one change per PR is easier to review than many changes bundled together
+- Test that `npm start` runs cleanly before submitting
+
+**Project structure:**
+
+```
+proxlens/
+├── src/
+│   ├── main/
+│   │   ├── index.js      # App entry — window creation only
+│   │   ├── ipc.js        # All IPC handlers in one place
+│   │   ├── proxy.js      # HTTP proxy, widget injection, password gate
+│   │   ├── tunnel.js     # Cloudflare tunnel lifecycle
+│   │   ├── storage.js    # Settings + feedback read/write
+│   │   └── github.js     # GitHub API calls only
+│   ├── renderer/
+│   │   ├── index.html    # Clean HTML shell
+│   │   ├── index.js      # All UI logic
+│   │   └── styles.css    # All styles
+│   └── preload/
+│       └── index.js      # Context bridge
+├── widget/
+│   └── index.js          # Injected client widget
+├── package.json
+└── README.md
+```
+
+---
+
+## License
+
+MIT

package/bin/proxlens.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+/**
+ * Proxlens CLI launcher.
+ * Invoked when the user runs `proxlens` in their terminal.
+ * Finds the Electron binary from the local install and launches the app.
+ */
+
+const path  = require('path');
+const { spawn } = require('child_process');
+
+let electronBin;
+try {
+  electronBin = require('electron');
+} catch (_) {
+  console.error(
+    '\n  Proxlens could not find the Electron runtime.\n' +
+    '  Try reinstalling: npm install -g proxlens\n'
+  );
+  process.exit(1);
+}
+
+// __dirname is .../node_modules/proxlens/bin
+// The app root is one level up
+const appRoot = path.join(__dirname, '..');
+
+const proc = spawn(electronBin, [appRoot], {
+  stdio:       'inherit',
+  windowsHide: false
+});
+
+proc.on('close', code => process.exit(code ?? 0));
+proc.on('error', err  => {
+  console.error('\n  Failed to launch Proxlens:', err.message, '\n');
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "proxlens",
+  "version": "1.2.1",
+  "description": "Share your localhost with clients. Built-in feedback widget + password protection.",
+  "main": "src/main/index.js",
+  "bin": {
+    "proxlens": "bin/proxlens.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "widget/index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "electron .",
+    "dev": "electron . --dev",
+    "build:widget": "node widget/build.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "localhost",
+    "tunnel",
+    "client-preview",
+    "feedback",
+    "cloudflare",
+    "electron"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "cloudflared": "0.7.1",
+    "electron": "40.7.0"
+  }
+}

package/src/main/github.js

@@ -0,0 +1,107 @@
+const https = require('https');
+
+/**
+ * Post a feedback entry as a GitHub Issue.
+ * Returns { ok, issueUrl } or { ok: false, error }.
+ */
+function postIssue(entry, settings) {
+  return new Promise((resolve) => {
+    const { githubToken, githubRepo } = settings;
+    if (!githubToken || !githubRepo) {
+      return resolve({ ok: false, error: 'GitHub not configured' });
+    }
+
+    const issueBody =
+      `**Page:** \`${entry.page}\` — ${entry.pageTitle || ''}\n` +
+      `**Element:** ${entry.elementLabel || entry.selector}\n` +
+      (entry.selector ? `**Selector:** \`${entry.selector}\`\n` : '') +
+      `\n**Feedback:**\n${entry.comment}`;
+
+    const payload = JSON.stringify({
+      title:  `[Feedback] ${entry.pageTitle || entry.page}`,
+      body:   issueBody,
+      labels: ['client-feedback']
+    });
+
+    const [owner, repo] = githubRepo.split('/');
+    const options = {
+      hostname: 'api.github.com',
+      path:     `/repos/${owner}/${repo}/issues`,
+      method:   'POST',
+      headers: {
+        'Content-Type':   'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+        'Authorization':  `Bearer ${githubToken}`,
+        'User-Agent':     'Proxlens-App',
+        'Accept':         'application/vnd.github+json'
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => {
+        try {
+          const data = JSON.parse(Buffer.concat(chunks).toString());
+          if (res.statusCode === 201) {
+            resolve({ ok: true, issueUrl: data.html_url });
+          } else {
+            resolve({ ok: false, error: data.message || 'GitHub API error' });
+          }
+        } catch (_) {
+          resolve({ ok: false, error: 'Failed to parse GitHub response' });
+        }
+      });
+    });
+
+    req.on('error', err => resolve({ ok: false, error: err.message }));
+    req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * Test whether a token has access to a given repo.
+ * Returns { ok, name } or { ok: false, error }.
+ */
+function testConnection(token, repo) {
+  return new Promise((resolve) => {
+    const [owner, repoName] = (repo || '').split('/');
+    if (!owner || !repoName) {
+      return resolve({ ok: false, error: 'Repo must be in format: owner/repo' });
+    }
+
+    const options = {
+      hostname: 'api.github.com',
+      path:     `/repos/${owner}/${repoName}`,
+      method:   'GET',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'User-Agent':    'Proxlens-App',
+        'Accept':        'application/vnd.github+json'
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => {
+        try {
+          const data = JSON.parse(Buffer.concat(chunks).toString());
+          if (res.statusCode === 200) {
+            resolve({ ok: true, name: data.full_name });
+          } else {
+            resolve({ ok: false, error: data.message || 'Repo not found or no access' });
+          }
+        } catch (_) {
+          resolve({ ok: false, error: 'Failed to parse GitHub response' });
+        }
+      });
+    });
+
+    req.on('error', err => resolve({ ok: false, error: err.message }));
+    req.end();
+  });
+}
+
+module.exports = { postIssue, testConnection };

package/src/main/index.js

@@ -0,0 +1,43 @@
+const { app, BrowserWindow } = require('electron');
+const path = require('path');
+
+const ipc   = require('./ipc');
+const proxy = require('./proxy');
+
+let mainWindow;
+
+function createWindow() {
+  mainWindow = new BrowserWindow({
+    width:     640,
+    height:    860,
+    minWidth:  560,
+    minHeight: 700,
+    resizable: true,
+    titleBarStyle: process.platform === 'darwin' ? 'hiddenInset' : 'default',
+    backgroundColor: '#0c0c0e',
+    webPreferences: {
+      preload:          path.join(__dirname, '../preload/index.js'),
+      contextIsolation: true,
+      nodeIntegration:  false
+    }
+  });
+
+  mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
+
+  // Give the proxy access to the window for sending IPC events
+  proxy.setMainWindow(mainWindow);
+}
+
+app.whenReady().then(() => {
+  ipc.register();
+  createWindow();
+});
+
+app.on('window-all-closed', () => {
+  ipc.cleanup();
+  app.quit();
+});
+
+app.on('activate', () => {
+  if (BrowserWindow.getAllWindows().length === 0) createWindow();
+});

package/src/main/ipc.js

@@ -0,0 +1,78 @@
+const { ipcMain, clipboard, shell } = require('electron');
+
+const storage = require('./storage');
+const github  = require('./github');
+const tunnel  = require('./tunnel');
+const proxy   = require('./proxy');
+
+let proxyServer  = null;
+let settings     = {};
+
+function getSettings() {
+  return settings;
+}
+
+function register(mainWindow) {
+  settings = storage.loadSettings();
+
+  // ── Settings ────────────────────────────────────────────────────────────
+  ipcMain.handle('get-settings', () => settings);
+
+  ipcMain.handle('save-settings', (_, newSettings) => {
+    settings = newSettings;
+    storage.saveSettings(newSettings);
+    return { ok: true };
+  });
+
+  ipcMain.handle('test-github', (_, { token, repo }) => {
+    return github.testConnection(token, repo);
+  });
+
+  // ── Tunnel ──────────────────────────────────────────────────────────────
+  ipcMain.handle('start-tunnel', async (_, localPort) => {
+    try {
+      // Stop any existing session first
+      tunnel.stopTunnel();
+      if (proxyServer) { proxyServer.close(); proxyServer = null; }
+      proxy.resetVisitCooldowns();
+
+      const proxyPort = await tunnel.getFreePort(19000);
+
+      proxyServer = proxy.buildProxyServer(localPort, settings);
+      await new Promise((resolve, reject) => {
+        proxyServer.listen(proxyPort, resolve);
+        proxyServer.on('error', reject);
+      });
+
+      return await tunnel.startTunnel(proxyPort);
+
+    } catch (err) {
+      tunnel.stopTunnel();
+      if (proxyServer) { proxyServer.close(); proxyServer = null; }
+      return { error: err.message };
+    }
+  });
+
+  ipcMain.handle('stop-tunnel', () => {
+    tunnel.stopTunnel();
+    if (proxyServer) { proxyServer.close(); proxyServer = null; }
+    proxy.resetVisitCooldowns();
+    return { ok: true };
+  });
+
+  // ── Feedback storage ────────────────────────────────────────────────────
+  ipcMain.handle('get-feedback',   () => storage.loadFeedback());
+  ipcMain.handle('clear-feedback', () => { storage.clearFeedback(); return { ok: true }; });
+  ipcMain.handle('export-feedback',() => storage.FEEDBACK_PATH);
+
+  // ── Utilities ───────────────────────────────────────────────────────────
+  ipcMain.handle('copy-to-clipboard', (_, text) => { clipboard.writeText(text); return true; });
+  ipcMain.handle('open-url',          (_, url)  => { shell.openExternal(url); return true; });
+}
+
+function cleanup() {
+  tunnel.stopTunnel();
+  if (proxyServer) { proxyServer.close(); proxyServer = null; }
+}
+
+module.exports = { register, cleanup, getSettings };