adb-sqlite-viewer 1.0.5 → 1.0.6

package/README.md

@@ -1,151 +1,86 @@
-# SQLite DevTools for Mobile (React Native)
+# ADB SQLite DevTools
 
-A browser-based tool for inspecting SQLite databases on Android devices. Browse tables, view schemas, and execute SQL queries directly on your device.
+Inspect SQLite databases on Android devices. Browse tables, view schemas, and run SQL queries — all from your browser.
 
-## Four Ways to Use
+## Quick Start (npm)
 
-### Option 1: Desktop App (Easiest)
-
-Download the installer from [Releases](https://github.com/amitwinit/SQLite-DevTools-Mobile-ReactNative/releases) and run it. The app bundles the ADB bridge server — it starts automatically when you launch the app. No separate downloads, no terminal commands.
-
-**Requirements:**
-- Windows (NSIS installer)
-- `adb` on your PATH (Android SDK Platform-Tools)
-- Android device with USB debugging enabled
-
-### Option 2: Hosted Version + ADB Bridge (Best for React Native Developers)
+```bash
+npm install --save-dev adb-sqlite-viewer
+npx sqlite-viewer
+```
 
-Use the deployed version at **[amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative](https://amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative/)** together with the **ADB Bridge** — a small localhost server that wraps `adb shell` commands. This lets you inspect databases while ADB stays running for React Native development.
+Opens a local server at `http://127.0.0.1:8085` with the full UI and ADB bridge built in. One command, no extra downloads.
 
-**Setup:**
+```bash
+# Custom port
+npx sqlite-viewer --port 3000
+```
 
-1. Download `adb-bridge.exe` from [Releases](https://github.com/amitwinit/SQLite-DevTools-Mobile-ReactNative/releases), or build it yourself:
-   ```bash
-   cd bridge
-   npm install
-   npm run build    # produces adb-bridge.exe
-   ```
+**Requirements:** `adb` on your PATH ([Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools)) and a USB-connected Android device with debugging enabled.
 
-2. Run the bridge:
-   ```bash
-   # Either run the exe directly:
-   adb-bridge.exe
+## All Options
 
-   # Or with Node.js:
-   cd bridge && node server.js
-   ```
+### npm Package (Recommended for dev workflows)
 
-3. Open the hosted website — it auto-detects the bridge and connects through it.
+Install into any project and run alongside your app:
 
-**How it works:**
-```
-Hosted website (HTTPS) ──HTTP──> localhost:15555 (bridge) ──> adb shell ──> Device
+```bash
+npm install --save-dev adb-sqlite-viewer
 ```
-The website detects the bridge on startup and routes all commands through HTTP instead of WebUSB. No need to kill ADB.
-
-### Option 3: Hosted Version with WebUSB (No Setup Required)
 
-Use the deployed version at **[amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative](https://amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative/)**
+Add to your `package.json` scripts:
 
-This version uses **WebUSB** to communicate with your Android device directly from the browser. No backend server needed.
-
-**Requirements:**
-- Chrome or Edge (WebUSB is not supported in Firefox/Safari)
-- Android device with USB debugging enabled
-- You must **stop the local ADB server** first: `adb kill-server`
+```json
+{
+  "scripts": {
+    "sqlite-viewer": "sqlite-viewer"
+  }
+}
+```
 
-**Important:** WebUSB and the local ADB server cannot use the USB interface at the same time. If you are actively developing a React Native app and need ADB running, use **Option 1** or **Option 2** instead.
+Then `npm run sqlite-viewer` opens the viewer. Works great alongside React Native, Flutter, or any Android project.
 
-**Steps:**
-1. Run `adb kill-server` in your terminal
-2. Open the hosted URL in Chrome/Edge
-3. Click **Connect Device** and select your phone from the USB picker
-4. Approve the USB debugging prompt on your phone (first time only)
-5. Select a package and database, then start querying
+### Desktop App
 
-### Option 4: Local Flask Server (Legacy)
+Download the Windows installer from [Releases](https://github.com/amitwinit/SQLite-DevTools-Mobile-ReactNative/releases). Double-click to launch — the bridge server starts automatically.
 
-If you are developing a React Native app and need ADB running alongside, use the local Flask backend. Both tools share the same ADB server so there is no conflict.
+### Hosted Version + ADB Bridge
 
-**Setup:**
+Use the deployed version at **[amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative](https://amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative/)** together with the standalone ADB Bridge.
 
-1. Install Python dependencies:
-   ```bash
-   pip install -r requirements.txt
-   ```
+1. Download `adb-bridge.exe` from [Releases](https://github.com/amitwinit/SQLite-DevTools-Mobile-ReactNative/releases)
+2. Run `adb-bridge.exe`
+3. Open the hosted website — it auto-detects the bridge
 
-2. Copy and configure environment:
-   ```bash
-   cp .env.example .env
-   ```
+```
+Website (HTTPS) ──HTTP──> localhost:15555 (bridge) ──> adb shell ──> Device
+```
 
-   Update `.env` with your configuration:
-   - `DEVICE_SERIAL` — run `adb devices` to find it
-   - `PACKAGE_NAME` — your app's package name
-   - `DB_NAME` — the SQLite database filename
-   - `PYTHON_TOOLS_PATH` — path to the python_tools directory
+### Hosted Version with WebUSB (No install required)
 
-3. Run the server:
-   ```bash
-   python app.py
-   ```
+Open **[amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative](https://amitwinit.github.io/SQLite-DevTools-Mobile-ReactNative/)** in Chrome/Edge. Uses WebUSB to talk directly to the device — no server needed.
 
-4. Open http://localhost:5001 in any browser
+**Note:** Requires `adb kill-server` first (WebUSB and ADB can't share the USB interface). Not suitable when you need ADB running for development.
 
 ## When to Use Which
 
-| Scenario | Use |
-|----------|-----|
-| Just want it to work, one click | Desktop App (Option 1) |
-| Active React Native development | Desktop App (Option 1) or ADB Bridge (Option 2) |
-| Quick DB inspection, no local setup | WebUSB (Option 3) |
-| Sharing with teammates who don't have Python | WebUSB (Option 3) |
-| Need ADB for other tools simultaneously | Desktop App (Option 1) or ADB Bridge (Option 2) |
-
-## Environment Variables (Option 4)
-
-### Application Configuration
-- `PACKAGE_NAME`: Android app package name
-- `DB_NAME`: Database name on the device
-- `DEVICE_SERIAL`: ADB device serial number
-- `PYTHON_TOOLS_PATH`: Path to python_tools directory
-
-### Flask Server Configuration
-- `FLASK_HOST`: Flask server host (default: 0.0.0.0)
-- `FLASK_PORT`: Flask server port (default: 5001)
-- `FLASK_DEBUG`: Enable debug mode (default: True)
-
-### Cache Configuration
-- `USE_CACHE`: Enable database caching (default: True)
-- `FORCE_LOCAL`: Force local database operations (default: False)
+| Scenario | Recommended |
+|----------|-------------|
+| Active development (React Native, Flutter, etc.) | `npx sqlite-viewer` or Desktop App |
+| Quick one-off DB inspection | WebUSB (hosted version) |
+| CI or shared dev environment | `npx sqlite-viewer` |
+| No Node.js installed | Desktop App or WebUSB |
 
 ## Development
 
-To work on the WebUSB frontend:
-
 ```bash
 npm install
-npm run dev
-```
-
-To build for production (GitHub Pages):
-
-```bash
-npm run build
+npm run dev          # Vite dev server
+npm run build        # Build for GitHub Pages
+npm run electron:dev # Build + launch Electron app
+npm run electron:build # Build Electron installer
 ```
 
-The built files go to `dist/` and are deployed to GitHub Pages automatically on push to `main`.
-
-To run the Electron desktop app in development:
-
-```bash
-npm run electron:dev
-```
-
-To build the Electron installer:
-
-```bash
-npm run electron:build
-```
+## License
 
-The installer is output to `electron-dist/`.
+MIT

package/bridge/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "adb-bridge",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Localhost HTTP bridge that wraps adb shell commands for the SQLite DevTools website",
+  "scripts": {
+    "start": "node server.js",
+    "build": "pkg server.js --target node20-win-x64 --output adb-bridge.exe"
+  },
+  "devDependencies": {
+    "@yao-pkg/pkg": "^5.11.0"
+  }
+}

package/cli/ensure-adb.cjs

@@ -0,0 +1,150 @@
+"use strict";
+
+const { execFile } = require("child_process");
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const CACHE_DIR = path.join(os.homedir(), ".adb-sqlite-viewer");
+const PLATFORM_TOOLS_DIR = path.join(CACHE_DIR, "platform-tools");
+
+const DOWNLOAD_URLS = {
+  win32: "https://dl.google.com/android/repository/platform-tools-latest-windows.zip",
+  darwin: "https://dl.google.com/android/repository/platform-tools-latest-darwin.zip",
+  linux: "https://dl.google.com/android/repository/platform-tools-latest-linux.zip",
+};
+
+const ADB_BIN = process.platform === "win32" ? "adb.exe" : "adb";
+
+/** Check if adb works at the given path. Returns version string or null. */
+function tryAdb(adbPath) {
+  return new Promise((resolve) => {
+    execFile(adbPath, ["version"], { timeout: 5000 }, (err, stdout) => {
+      if (err) return resolve(null);
+      resolve(stdout.split("\n")[0].trim());
+    });
+  });
+}
+
+/** Download a file via HTTPS, following redirects. */
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    const request = (u) => {
+      https.get(u, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          file.close();
+          request(res.headers.location);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          file.close();
+          fs.unlinkSync(dest);
+          reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+          return;
+        }
+        const total = parseInt(res.headers["content-length"], 10) || 0;
+        let downloaded = 0;
+        res.on("data", (chunk) => {
+          downloaded += chunk.length;
+          if (total > 0) {
+            const pct = Math.round((downloaded / total) * 100);
+            process.stdout.write(`\r  Downloading... ${pct}%`);
+          }
+        });
+        res.pipe(file);
+        file.on("finish", () => {
+          file.close();
+          if (total > 0) process.stdout.write("\n");
+          resolve();
+        });
+      }).on("error", (err) => {
+        file.close();
+        fs.unlinkSync(dest);
+        reject(err);
+      });
+    };
+    request(url);
+  });
+}
+
+/** Extract a zip file using OS tools. */
+function extractZip(zipPath, destDir) {
+  return new Promise((resolve, reject) => {
+    const cmd = process.platform === "win32"
+      ? `tar -xf "${zipPath}" -C "${destDir}"`
+      : `unzip -q -o "${zipPath}" -d "${destDir}"`;
+    execFile(cmd.split(" ")[0], cmd.split(" ").slice(1), { shell: true, timeout: 60000 }, (err) => {
+      if (err) reject(new Error(`Extract failed: ${err.message}`));
+      else resolve();
+    });
+  });
+}
+
+/**
+ * Ensure adb is available. Checks PATH, then cached download, then downloads.
+ * Prepends the adb directory to process.env.PATH if needed.
+ * Returns the adb version string.
+ */
+async function ensureAdb() {
+  // 1. Check system PATH
+  const systemVersion = await tryAdb("adb");
+  if (systemVersion) {
+    return systemVersion;
+  }
+
+  // 2. Check cached download
+  const cachedAdb = path.join(PLATFORM_TOOLS_DIR, ADB_BIN);
+  if (fs.existsSync(cachedAdb)) {
+    const cachedVersion = await tryAdb(cachedAdb);
+    if (cachedVersion) {
+      prependToPath(PLATFORM_TOOLS_DIR);
+      return cachedVersion;
+    }
+  }
+
+  // 3. Download from Google
+  const url = DOWNLOAD_URLS[process.platform];
+  if (!url) {
+    throw new Error(`Unsupported platform: ${process.platform}. Install adb manually.`);
+  }
+
+  console.log("  adb not found. Downloading Android Platform-Tools...");
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  const zipPath = path.join(CACHE_DIR, "platform-tools.zip");
+
+  await download(url, zipPath);
+  console.log("  Extracting...");
+  await extractZip(zipPath, CACHE_DIR);
+
+  // Clean up zip
+  try { fs.unlinkSync(zipPath); } catch {}
+
+  // Verify
+  if (!fs.existsSync(cachedAdb)) {
+    throw new Error("Download succeeded but adb binary not found in extracted files.");
+  }
+
+  // Make executable on Unix
+  if (process.platform !== "win32") {
+    fs.chmodSync(cachedAdb, 0o755);
+  }
+
+  const version = await tryAdb(cachedAdb);
+  if (!version) {
+    throw new Error("Downloaded adb binary is not working.");
+  }
+
+  prependToPath(PLATFORM_TOOLS_DIR);
+  console.log(`  Downloaded: ${version}`);
+  return version;
+}
+
+function prependToPath(dir) {
+  const sep = process.platform === "win32" ? ";" : ":";
+  process.env.PATH = dir + sep + (process.env.PATH || "");
+}
+
+module.exports = { ensureAdb };

package/cli/server.cjs

@@ -4,7 +4,8 @@ const http = require("http");
 const path = require("path");
 const fs = require("fs");
 const { exec } = require("child_process");
-const { handleRequest: bridgeHandler, checkAdb } = require("../bridge/server.js");
+const { handleRequest: bridgeHandler } = require("../bridge/server.js");
+const { ensureAdb } = require("./ensure-adb.cjs");
 
 const DIST_DIR = path.join(__dirname, "..", "dist");
 
@@ -86,13 +87,13 @@ async function start(port) {
     process.exit(1);
   }
 
-  // Check adb (warn only — WebUSB still works without it)
+  // Ensure adb is available (downloads if needed)
   try {
-    const version = await checkAdb();
-    console.log(`Found: ${version}`);
+    const version = await ensureAdb();
+    console.log(`  adb: ${version}`);
   } catch (err) {
-    console.warn(`WARNING: ${err.message}`);
-    console.warn("ADB bridge features will not work.");
+    console.warn(`  WARNING: ${err.message}`);
+    console.warn("  ADB bridge features will not work.");
   }
 
   const server = http.createServer(requestHandler);

package/electron/main.cjs

@@ -5,6 +5,14 @@ const path = require("path");
 let bridge = null;
 let mainWindow = null;
 
+function setupBundledAdb() {
+  if (app.isPackaged) {
+    const toolsDir = path.join(process.resourcesPath, "tools");
+    const sep = process.platform === "win32" ? ";" : ":";
+    process.env.PATH = toolsDir + sep + (process.env.PATH || "");
+  }
+}
+
 function getBridgePath() {
   if (app.isPackaged) {
     return path.join(process.resourcesPath, "bridge", "server.js");
@@ -73,6 +81,7 @@ function createWindow() {
 }
 
 app.whenReady().then(async () => {
+  setupBundledAdb();
   try {
     console.log("Starting ADB bridge server...");
     await startBridge();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-sqlite-viewer",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "ADB SQLite database viewer for Android — inspect tables, schemas, and run queries on-device",
   "type": "module",
   "main": "electron/main.cjs",
@@ -10,6 +10,7 @@
   "files": [
     "cli/",
     "bridge/server.js",
+    "bridge/package.json",
     "dist/"
   ],
   "scripts": {
@@ -66,6 +67,10 @@
       {
         "from": "bridge/package.json",
         "to": "bridge/package.json"
+      },
+      {
+        "from": "tools/",
+        "to": "tools/"
       }
     ],
     "win": {