If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/amitshekhariitbhu/Android-Debug-Database shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3mo ago
• 11 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live amitshekhariitbhu/Android-Debug-Database repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/amitshekhariitbhu/Android-Debug-Database.

What it runs against: a local clone of amitshekhariitbhu/Android-Debug-Database — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in amitshekhariitbhu/Android-Debug-Database | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 122 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of amitshekhariitbhu/Android-Debug-Database. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/amitshekhariitbhu/Android-Debug-Database.git
#   cd Android-Debug-Database
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of amitshekhariitbhu/Android-Debug-Database and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "amitshekhariitbhu/Android-Debug-Database(\\.git)?\\b" \\
  && ok "origin remote is amitshekhariitbhu/Android-Debug-Database" \\
  || miss "origin remote is not amitshekhariitbhu/Android-Debug-Database (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "debug-db-base/src/main/java/com/amitshekhar/DebugDB.java" \\
  && ok "debug-db-base/src/main/java/com/amitshekhar/DebugDB.java" \\
  || miss "missing critical file: debug-db-base/src/main/java/com/amitshekhar/DebugDB.java"
test -f "debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java" \\
  && ok "debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java" \\
  || miss "missing critical file: debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java"
test -f "debug-db-base/src/main/java/com/amitshekhar/sqlite/DBFactory.java" \\
  && ok "debug-db-base/src/main/java/com/amitshekhar/sqlite/DBFactory.java" \\
  || miss "missing critical file: debug-db-base/src/main/java/com/amitshekhar/sqlite/DBFactory.java"
test -f "debug-db-base/src/main/java/com/amitshekhar/server/ClientServer.java" \\
  && ok "debug-db-base/src/main/java/com/amitshekhar/server/ClientServer.java" \\
  || miss "missing critical file: debug-db-base/src/main/java/com/amitshekhar/server/ClientServer.java"
test -f "debug-db-base/src/main/assets/index.html" \\
  && ok "debug-db-base/src/main/assets/index.html" \\
  || miss "missing critical file: debug-db-base/src/main/assets/index.html"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 122 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~92d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/amitshekhariitbhu/Android-Debug-Database"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Android Debug Database is a library that exposes a local HTTP server (running on the Android device) serving a web UI to inspect and modify SQLite databases and SharedPreferences in real-time via a browser. It eliminates the need to root devices or use Android Studio's database inspector by providing direct SQL query execution, row editing, and bulk operations through DataTables-powered web interface. Modular library structure: debug-db-base/src/main/java/com/amitshekhar/ contains core logic split into server/ (ClientServer.java, RequestHandler.java), sqlite/ (DBFactory.java, SQLiteDB.java, InMemoryDebugSQLiteDB.java), model/ (data classes), and utils/. Web UI assets (HTML, JS, CSS) live in /assets/; RequestHandler maps HTTP requests to SQL operations and file downloads.

Android developers building production and debug versions of apps who need runtime inspection and modification of local SQLite data and SharedPreferences without USB debugging setup—particularly useful during QA, local testing, and development iteration cycles where quick data manipulation is critical.

Actively maintained and production-ready: the repo shows regular updates (latest version 1.0.7), comprehensive feature set, and clear documentation. No public test suite is visible in the file listing (only androidTest/ with basic ExampleInstrumentedTest.java), suggesting testing may be primarily manual. It has adoption from the community given the polished README and explicit Room in-memory database support.

Low risk for debug-only usage (debugImplementation), but single-maintainer repository (Amit Shekhar) creates long-term maintenance risk. Includes external dependencies (Bootstrap, jQuery DataTables, jQuery) bundled as assets in /main/assets/, which may lag behind security patches. The library is explicitly debug-only, mitigating production risk.

No specific recent commit data visible, but the CHANGELOG.md and feature list suggest the library is feature-complete with support for encrypted databases (separate debug-db-encrypt artifact), Room in-memory databases, and full CRUD operations. Active enough to maintain documentation and version releases on JitPack.

git clone https://github.com/amitshekhariitbhu/Android-Debug-Database.git
cd Android-Debug-Database
./gradlew build

Then add debugImplementation 'com.github.amitshekhariitbhu.Android-Debug-Database:debug-db:1.0.7' to your app's build.gradle and sync. Start the app in debug build variant and access the web UI (URL provided in logcat or via adb command).

Daily commands: Gradle-based Android project. Run ./gradlew build to compile. To test with an actual app: add the debugImplementation dependency, build the debug variant (./gradlew assembleDebug), and run the app. The library auto-initializes via DebugDB.java entry point and starts the HTTP server; access it via the URL printed in logcat or by running adb forward tcp:8080 tcp:<random_port> (port varies).

• debug-db-base/src/main/java/com/amitshekhar/DebugDB.java — Main entry point and API surface for the entire library—initializes the debug server and exposes configuration methods that every feature depends on.
• debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java — Core HTTP request dispatcher that routes all browser queries to database/SharedPreferences operations—critical for understanding request flow.
• debug-db-base/src/main/java/com/amitshekhar/sqlite/DBFactory.java — Factory abstraction for database access that determines whether to use real SQLite or in-memory debug databases—enables encryption and testing support.
• debug-db-base/src/main/java/com/amitshekhar/server/ClientServer.java — Embedded HTTP server that serves the web UI and API endpoints—foundational for the browser-based debugging interface.
• debug-db-base/src/main/assets/index.html — Frontend entry point for the browser-based debugger UI—orchestrates the DataTables/Bootstrap interface for viewing and editing data.
• debug-db-base/src/main/java/com/amitshekhar/utils/DatabaseHelper.java — Centralizes database querying and connection logic—handles SQL execution, table metadata, and data serialization across all operations.
• debug-db-encrypt/src/main/java/com/amitshekhar/debug/encrypt/DebugDBEncryptInitProvider.java — Content provider that enables encrypted database support via DBFactory pattern—critical extension point for production-safe debugging.

Add Support for a New Database Encryption Library

1. Create a new DBFactory implementation similar to DebugDBEncryptFactory that wraps SQLiteDatabase and handles your encryption library's decrypt operations. (debug-db-encrypt/src/main/java/com/amitshekhar/debug/encrypt/sqlite/DebugDBEncryptFactory.java)
2. Implement SQLiteDB interface in a new class (e.g., DebugEncryptSQLiteDB) that intercepts cursor results and decrypts column values before returning them to RequestHandler. (debug-db-encrypt/src/main/java/com/amitshekhar/debug/encrypt/sqlite/DebugEncryptSQLiteDB.java)
3. Register your DBFactory globally using DBFactory.setDebugSQLiteDBFactory() or create a Content Provider similar to DebugDBEncryptInitProvider to auto-register on app startup. (debug-db-encrypt/src/main/java/com/amitshekhar/debug/encrypt/DebugDBEncryptInitProvider.java)

Add a New HTTP API Endpoint for Custom Data Inspection

1. Define a new request/response model in the com.amitshekhar.model package, extending Response if needed. (debug-db-base/src/main/java/com/amitshekhar/model/Response.java)
2. Add a new request handler method in RequestHandler.java that checks the endpoint path (e.g., if (path.contains("/api/custom"))) and executes your custom query via DatabaseHelper. (debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java)
3. Add a corresponding AJAX call and UI element in app.js and index.html to invoke your new endpoint from the browser. (debug-db-base/src/main/assets/app.js)

Add a New SharedPreferences Viewer or Editor Tab

1. Extend PrefHelper.java to add a new method that collects SharedPreferences from an additional PreferenceManager or context source. (debug-db-base/src/main/java/com/amitshekhar/utils/PrefHelper.java)
2. Update RequestHandler.java to expose a new endpoint (e.g., /api/sharedpref/custom) that calls your new PrefHelper method and returns the JSON response. (debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java)
3. Add a new nav tab and table in index.html, and corresponding AJAX handlers in app.js to load and render the new SharedPreferences data. (debug-db-base/src/main/assets/index.html)

Customize Database Filtering or Table Metadata Parsing

1. Modify TableNameParser.java to add custom logic for filtering which tables to display or rename tables for clarity in the UI. (debug-db-base/src/main/java/com/amitshekhar/utils/TableNameParser.java)
2. Update DatabaseHelper.getTableList() or getColumnNames() to use your custom TableNameParser logic before returning table metadata to RequestHandler. (debug-db-base/src/main/java/com/amitshekhar/utils/DatabaseHelper.java)
3. If you need custom data type handling, extend DataType enum and update ConverterUtils to serialize/deserialize those types correctly. (debug-db-base/src/main/java/com/amitshekhar/utils/DataType.java)

No explicit port configuration visible: the library chooses a random port and prints it to logcat; users must check logs or use adb forwarding commands, not obvious from README. In-memory database debugging requires specific Room setup: InMemoryDebugSQLiteDB.java exists but seamless Room integration details not documented in file list. SharedPreferences path assumptions: library infers SharedPreferences locations from package name; non-standard SharedPreferences files may not be detected. HTTPS not supported: custom HTTP server only, no TLS/SSL support, limiting use on stricter Android versions or network policies. Browser compatibility: front-end uses older jQuery (dataTables 1.10.x) and Bootstrap 3/4—may have compatibility issues on very new Chrome versions if CSP headers are strict.

• LocalServerSocket — Core to how Debug Database runs an embedded HTTP server on the Android device without external services; understanding socket-based communication is essential for modifying server.java.
• Android Cursor (SQLite result set) — The library wraps Cursor objects and converts them to JSON for web display; knowledge of Cursor iteration and type retrieval (getInt, getString, getBlob) is critical for extending database features.
• DataTables (jQuery plugin) — Front-end uses DataTables for sortable, searchable, paginated tables with inline editing (altEditor plugin); modifying UI requires understanding DataTables API and initialization options.
• Room in-memory databases — Debug Database supports Room's in-memory DB variant (InMemoryDebugSQLiteDB.java); developers need to understand Room's architecture to properly inject or expose in-memory instances.
• HTTP request routing / URL path mapping — RequestHandler.java parses HTTP paths and query parameters to route to SQL operations; extending API endpoints requires understanding custom HTTP parsing without a framework.
• Factory Pattern (DBFactory) — The library uses Factory pattern to instantiate correct SQLiteDB implementation based on database metadata; valuable for supporting multiple storage backends without tight coupling.
• SharedPreferences (Android key-value store) — Library debugs both SQLite databases and SharedPreferences; contributors need to understand SharedPreferences file locations, XML parsing, and encryption nuances.

• facebook/stetho — Alternative Chrome DevTools integration for Android debugging that includes database inspection; competes on ease of use but less focused on real-time editing.
• square/okhttp — While not a debugger, OkHttp is often used in conjunction with Debug Database apps for inspecting network requests; commonly used together in test setups.
• room-kotlin/room — Google's official Room library that this project explicitly supports for in-memory database debugging; users of Room often adopt Debug Database for runtime inspection.
• google/android-studio — Android Studio's built-in Database Inspector is the official alternative; Debug Database wins on no-USB simplicity but Studio is more feature-complete.
• amitshekhariitbhu/Android-Networking — Same author's networking library; often used in the same development environment, enabling developers to debug both network requests and local storage together.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for DatabaseHelper.java and SQLiteDB.java

The core database interaction logic in debug-db-base/src/main/java/com/amitshekhar/sqlite/ and debug-db-base/src/main/java/com/amitshekhar/utils/DatabaseHelper.java lacks unit test coverage. Currently only ExampleUnitTest.java exists as a placeholder. Adding tests for database operations (querying, updating, deleting rows) would catch regressions and improve reliability for a debugging tool where correctness is critical.

• [ ] Create DatabaseHelperTest.java in debug-db-base/src/test/java/com/amitshekhar/utils/
• [ ] Create SQLiteDBTest.java in debug-db-base/src/test/java/com/amitshekhar/sqlite/ covering table listing, row operations, and query execution
• [ ] Add tests for edge cases: empty tables, special characters in data, SQL injection attempts
• [ ] Test DBFactory.java logic for selecting appropriate database implementation
• [ ] Run tests and verify coverage for critical paths

Add instrumented tests for RequestHandler.java API endpoints

The RequestHandler.java file serves HTTP requests but has no automated tests validating the API responses. The ExampleInstrumentedTest.java is a placeholder. Adding instrumented tests would verify that the web interface correctly serializes database/SharedPreferences data, handles malformed requests, and returns proper error responses.

• [ ] Create RequestHandlerInstrumentedTest.java in debug-db-base/src/androidTest/java/com/amitshekhar/server/
• [ ] Add tests for all request endpoints: list databases, list tables, fetch table data, execute SQL
• [ ] Test request/response serialization with RowDataRequest.java, TableDataResponse.java, UpdateRowResponse.java
• [ ] Add tests for error cases: invalid database names, malformed SQL, missing parameters
• [ ] Verify that responses match the JavaScript UI expectations in app.js

Add GitHub Actions CI workflow for automated testing and static analysis

The repo has no CI/CD pipeline (.github/workflows/ directory is missing). For a debugging library used in production apps, automated testing on each PR would catch Android version compatibility issues, build failures, and lint violations. This is especially important given the library supports minSdk 14 through compileSdk 33.

• [ ] Create .github/workflows/android-ci.yml with build matrix for multiple Android SDK versions
• [ ] Add gradle tasks: assembleDebug, assembleRelease, test (unit), connectedAndroidTest (instrumented)
• [ ] Integrate Android Lint checks and fail on critical issues
• [ ] Test against minSdk 14 and compileSdk 33 to validate version compatibility
• [ ] Add status badge to README.md showing workflow status

• Add unit tests for ConverterUtils.java data type conversions (BLOB, NULL, numeric, text); currently only ExampleInstrumentedTest.java exists with minimal coverage.
• Document the exact port selection and adb forwarding workflow in a step-by-step DEBUGGING_GUIDE.md with screenshots, since users often struggle to find the correct port in logcat.
• Implement search/filter for database list in the web UI (app.js): add a text input that filters the database dropdown and SharedPreferences list by name, similar to the existing row-level search in DataTables.

• Critical · Unauthenticated Network Debug Server — debug-db-base/src/main/java/com/amitshekhar/server/ClientServer.java, RequestHandler.java. The Debug Database library exposes a local HTTP server (ClientServer.java) that provides direct access to databases and shared preferences without any authentication mechanism. This allows any application or network entity with access to the device to query, modify, or delete sensitive data. Fix: Implement authentication and authorization controls. Add token-based authentication, restrict to localhost only, or limit access to specific IP ranges. Consider requiring a PIN or password before enabling debug features.
• Critical · SQL Injection Vulnerability — debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java, debug-db-base/src/main/java/com/amitshekhar/sqlite/SQLiteDB.java. The RequestHandler likely processes SQL queries directly from user input without proper parameterization. The ability to 'run any sql query on the given database' suggests raw SQL execution which is vulnerable to SQL injection attacks. Fix: Use parameterized queries and prepared statements exclusively. Never concatenate user input into SQL queries. Implement input validation and sanitization for all query parameters.
• High · Cross-Site Scripting (XSS) Vulnerability — debug-db-base/src/main/assets/app.js, index.html, dataTables.altEditor.free.js. The web interface (app.js, index.html) displays database and shared preferences data directly in the browser without proper HTML escaping. User-controlled data from databases could contain malicious JavaScript that executes in the debug interface context. Fix: Implement proper HTML entity encoding and sanitization for all displayed content. Use Content Security Policy (CSP) headers. Use frameworks or libraries that automatically escape content. Never use innerHTML with unsanitized data.
• High · Unencrypted Data Transmission — debug-db-base/src/main/java/com/amitshekhar/server/ClientServer.java. The ClientServer establishes an HTTP server without TLS/SSL encryption. Sensitive database contents and shared preferences are transmitted in plaintext over the network, exposing them to network eavesdropping. Fix: Implement HTTPS/TLS encryption for all network communication. Generate and use self-signed certificates for local debugging. Consider disabling network access entirely and using adb port forwarding instead.
• High · No Access Control on Sensitive Operations — debug-db-base/src/main/java/com/amitshekhar/server/RequestHandler.java. The library allows direct deletion of database rows, clearing shared preferences, and modifying sensitive data without any access controls, audit logging, or confirmation mechanisms. Fix: Implement granular access controls for destructive operations. Add audit logging for all database modifications. Require explicit confirmation for delete operations. Consider implementing role-based access control.
• High · Outdated Dependencies — build.gradle, debug-db-base/src/main/assets/. The build.gradle specifies Android Gradle Plugin 7.3.0 and API level 33, which may contain known vulnerabilities. The frontend uses outdated libraries like jQuery and DataTables without version pinning. Fix: Update all dependencies to their latest secure versions. Pin specific versions in build.gradle. Run dependency vulnerability checks regularly using tools like gradle-dependency-check or OWASP DependencyCheck.
• Medium · Information Disclosure via Debug Interface — debug-db-base/src/main/java/com/amitshekhar/sqlite/DBFactory.java, DatabaseHelper.java. The debug database interface reveals sensitive application structure including database schema, table names, and all data contents. This information can be used for targeted attacks. Fix: Ensure debug features are only enabled in debug builds (debuggable=true). Add feature flags to completely disable in production. Implement data masking for sensitive columns in the debug interface.
• Medium · Hardcoded Ports and Constants — debug-db-base/src/main/java/com/amitshekhar/utils. The library likely uses hardcoded port numbers and configuration constants without allowing customization, making it predictable and potentially conflicting with other services. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.