adb-sqlite-viewer 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Siddharth Bisht
+
+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,151 @@
+# SQLite DevTools for Mobile (React Native)
+
+A browser-based tool for inspecting SQLite databases on Android devices. Browse tables, view schemas, and execute SQL queries directly on your device.
+
+## Four Ways to Use
+
+### 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)
+
+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.
+
+**Setup:**
+
+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
+   ```
+
+2. Run the bridge:
+   ```bash
+   # Either run the exe directly:
+   adb-bridge.exe
+
+   # Or with Node.js:
+   cd bridge && node server.js
+   ```
+
+3. Open the hosted website — it auto-detects the bridge and connects through it.
+
+**How it works:**
+```
+Hosted website (HTTPS) ──HTTP──> localhost:15555 (bridge) ──> adb shell ──> Device
+```
+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/)**
+
+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`
+
+**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.
+
+**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
+
+### Option 4: Local Flask Server (Legacy)
+
+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.
+
+**Setup:**
+
+1. Install Python dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Copy and configure environment:
+   ```bash
+   cp .env.example .env
+   ```
+
+   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
+
+3. Run the server:
+   ```bash
+   python app.py
+   ```
+
+4. Open http://localhost:5001 in any browser
+
+## 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)
+
+## Development
+
+To work on the WebUSB frontend:
+
+```bash
+npm install
+npm run dev
+```
+
+To build for production (GitHub Pages):
+
+```bash
+npm run build
+```
+
+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
+```
+
+The installer is output to `electron-dist/`.

package/bridge/server.js

@@ -0,0 +1,251 @@
+const http = require("http");
+const { execFile, spawn } = require("child_process");
+
+const TIMEOUT = 30_000;
+const MAX_BUFFER = 10 * 1024 * 1024;
+
+// ── Helpers ────────────────────────────────────────────
+
+function cors(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+}
+
+function json(res, status, data) {
+  cors(res);
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > 1_000_000) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+    req.on("error", reject);
+  });
+}
+
+/** Run adb with simple args (devices, version). Rejects on non-zero exit. */
+function adb(args) {
+  return new Promise((resolve, reject) => {
+    execFile("adb", args, { timeout: TIMEOUT, maxBuffer: MAX_BUFFER }, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(stderr?.trim() || err.message));
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+
+/**
+ * Run a shell command on device via stdin piping.
+ * Avoids Windows argument quoting issues with complex shell commands.
+ * Returns stdout even on non-zero exit codes (common for probe scripts).
+ */
+function adbShell(command, serial) {
+  return new Promise((resolve, reject) => {
+    const args = [];
+    if (serial) args.push("-s", serial);
+    args.push("shell");
+
+    const proc = spawn("adb", args, { windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        proc.kill();
+        reject(new Error("Command timed out"));
+      }
+    }, TIMEOUT);
+
+    proc.stdout.on("data", (data) => { stdout += data; });
+    proc.stderr.on("data", (data) => { stderr += data; });
+
+    proc.on("close", () => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      // Always resolve with stdout — device commands often exit non-zero
+      // (e.g. probe scripts where some iterations fail) but still produce
+      // valid output. Only reject if we got nothing and stderr has content.
+      if (!stdout && stderr.trim()) {
+        reject(new Error(stderr.trim()));
+      } else {
+        resolve(stdout);
+      }
+    });
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      reject(err);
+    });
+
+    // Send command through stdin — bypasses Windows command-line quoting entirely
+    proc.stdin.write(command + "\n");
+    proc.stdin.end();
+  });
+}
+
+// ── Routes ─────────────────────────────────────────────
+
+async function handlePing(_req, res) {
+  json(res, 200, { ok: true });
+}
+
+async function handleDevices(_req, res) {
+  try {
+    const raw = await adb(["devices", "-l"]);
+    const lines = raw.split("\n").slice(1); // skip header
+    const devices = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("*")) continue;
+      const parts = trimmed.split(/\s+/);
+      const serial = parts[0];
+      const state = parts[1];
+      if (state !== "device") continue;
+
+      // Extract model from "model:<value>" token
+      let model = "";
+      for (const p of parts.slice(2)) {
+        if (p.startsWith("model:")) {
+          model = p.slice(6);
+          break;
+        }
+      }
+      devices.push({
+        serial,
+        display_name: model ? `${model} (${serial})` : serial,
+      });
+    }
+    json(res, 200, { devices });
+  } catch (err) {
+    json(res, 500, { error: err.message });
+  }
+}
+
+async function handleShell(req, res) {
+  let body;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    json(res, 400, { error: "Invalid JSON body" });
+    return;
+  }
+
+  const { command, serial } = body;
+  if (!command || typeof command !== "string") {
+    json(res, 400, { error: "Missing 'command' string in body" });
+    return;
+  }
+
+  try {
+    const output = await adbShell(command, serial);
+    json(res, 200, { output });
+  } catch (err) {
+    json(res, 500, { error: err.message });
+  }
+}
+
+// ── Exports (for use by cli/server.cjs and electron) ───
+
+/**
+ * Dispatch an incoming request to the appropriate API handler.
+ * Returns true if a route was matched, false otherwise.
+ */
+async function handleRequest(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const p = url.pathname;
+
+  if (req.method === "OPTIONS") {
+    cors(res);
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
+  try {
+    if (p === "/api/ping" && req.method === "GET") {
+      await handlePing(req, res);
+      return true;
+    } else if (p === "/api/devices" && req.method === "GET") {
+      await handleDevices(req, res);
+      return true;
+    } else if (p === "/api/shell" && req.method === "POST") {
+      await handleShell(req, res);
+      return true;
+    }
+  } catch (err) {
+    json(res, 500, { error: err.message });
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Verify adb is in PATH. Returns the version string, or rejects.
+ */
+function checkAdb() {
+  return new Promise((resolve, reject) => {
+    execFile("adb", ["version"], { timeout: 5000 }, (err, stdout) => {
+      if (err) {
+        reject(new Error("'adb' not found in PATH. Install Android SDK Platform-Tools."));
+        return;
+      }
+      resolve(stdout.split("\n")[0].trim());
+    });
+  });
+}
+
+module.exports = { handleRequest, checkAdb };
+
+// ── Standalone startup (node bridge/server.js) ─────────
+
+if (require.main === module) {
+  const PORT = 15555;
+  const HOST = "127.0.0.1";
+
+  const server = http.createServer(async (req, res) => {
+    const handled = await handleRequest(req, res);
+    if (!handled) {
+      json(res, 404, { error: "Not found" });
+    }
+  });
+
+  checkAdb()
+    .then((versionLine) => {
+      console.log(`Found: ${versionLine}`);
+      server.listen(PORT, HOST, () => {
+        console.log(`ADB Bridge listening on http://${HOST}:${PORT}`);
+        console.log("Endpoints:");
+        console.log("  GET  /api/ping     — health check");
+        console.log("  GET  /api/devices  — list connected devices");
+        console.log("  POST /api/shell    — run adb shell command");
+        console.log("\nPress Ctrl+C to stop.");
+        if (process.send) process.send({ type: "ready" });
+      });
+    })
+    .catch((err) => {
+      console.error("ERROR:", err.message);
+      if (process.send) process.send({ type: "error", message: err.message });
+      process.exit(1);
+    });
+}

package/cli/bin.cjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+"use strict";
+
+let port = 8085;
+const args = process.argv.slice(2);
+
+for (let i = 0; i < args.length; i++) {
+  if ((args[i] === "--port" || args[i] === "-p") && args[i + 1]) {
+    port = parseInt(args[i + 1], 10);
+    i++;
+  } else if (args[i].startsWith("--port=")) {
+    port = parseInt(args[i].split("=")[1], 10);
+  } else if (args[i] === "--help" || args[i] === "-h") {
+    console.log("Usage: sqlite-viewer [--port <number>]");
+    console.log("  --port, -p   Port to listen on (default: 8085)");
+    process.exit(0);
+  }
+}
+
+if (isNaN(port) || port < 1 || port > 65535) {
+  console.error("Invalid port number.");
+  process.exit(1);
+}
+
+require("./server.cjs").start(port);

package/cli/server.cjs

@@ -0,0 +1,121 @@
+"use strict";
+
+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 DIST_DIR = path.join(__dirname, "..", "dist");
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+function serveStatic(req, res) {
+  let urlPath = new URL(req.url, "http://localhost").pathname;
+  if (urlPath === "/") urlPath = "/index.html";
+
+  const filePath = path.join(DIST_DIR, urlPath);
+  const resolved = path.resolve(filePath);
+
+  // Prevent path traversal
+  if (!resolved.startsWith(path.resolve(DIST_DIR))) {
+    res.writeHead(403);
+    res.end("Forbidden");
+    return;
+  }
+
+  fs.readFile(resolved, (err, data) => {
+    if (err) {
+      // SPA fallback — serve index.html for unknown paths
+      fs.readFile(path.join(DIST_DIR, "index.html"), (err2, html) => {
+        if (err2) {
+          res.writeHead(500);
+          res.end("dist/index.html not found. Was the package built?");
+          return;
+        }
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+      });
+      return;
+    }
+    const ext = path.extname(resolved);
+    const mime = MIME[ext] || "application/octet-stream";
+    const isHashed = /assets[\\/].*\.[a-f0-9A-Z_-]{5,}\.(js|css)$/.test(resolved);
+    res.writeHead(200, {
+      "Content-Type": mime,
+      "Cache-Control": isHashed ? "public, max-age=31536000, immutable" : "no-cache",
+    });
+    res.end(data);
+  });
+}
+
+async function requestHandler(req, res) {
+  const urlPath = new URL(req.url, "http://localhost").pathname;
+
+  if (urlPath.startsWith("/api/") || req.method === "OPTIONS") {
+    const handled = await bridgeHandler(req, res);
+    if (handled) return;
+  }
+
+  serveStatic(req, res);
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === "win32" ? `start "" "${url}"`
+    : process.platform === "darwin" ? `open "${url}"`
+    : `xdg-open "${url}"`;
+  exec(cmd, () => {});
+}
+
+async function start(port) {
+  // Verify dist/ exists
+  if (!fs.existsSync(path.join(DIST_DIR, "index.html"))) {
+    console.error("ERROR: dist/index.html not found.");
+    console.error("Run: npm run build:npm");
+    process.exit(1);
+  }
+
+  // Check adb (warn only — WebUSB still works without it)
+  try {
+    const version = await checkAdb();
+    console.log(`Found: ${version}`);
+  } catch (err) {
+    console.warn(`WARNING: ${err.message}`);
+    console.warn("ADB bridge features will not work.");
+  }
+
+  const server = http.createServer(requestHandler);
+
+  server.listen(port, "127.0.0.1", () => {
+    const url = `http://127.0.0.1:${port}`;
+    console.log("");
+    console.log("  ADB SQLite DevTools");
+    console.log(`  Running at ${url}`);
+    console.log("");
+    console.log("  Press Ctrl+C to stop.");
+    console.log("");
+    setTimeout(() => openBrowser(url), 300);
+  });
+
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`Port ${port} is already in use. Try: sqlite-viewer --port ${port + 1}`);
+    } else {
+      console.error("Server error:", err.message);
+    }
+    process.exit(1);
+  });
+}
+
+module.exports = { start };