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/guolindev/LitePal 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.

WAIT — Stale — last commit 4y ago

• 4 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Small team — 4 contributors active in 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 guolindev/LitePal repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/guolindev/LitePal.

What it runs against: a local clone of guolindev/LitePal — 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 guolindev/LitePal | 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 ≤ 1388 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of guolindev/LitePal. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/guolindev/LitePal.git
#   cd LitePal
#
# 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 guolindev/LitePal and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "guolindev/LitePal(\\.git)?\\b" \\
  && ok "origin remote is guolindev/LitePal" \\
  || miss "origin remote is not guolindev/LitePal (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 "core/src/main/java/org/litepal/LitePal.kt" \\
  && ok "core/src/main/java/org/litepal/LitePal.kt" \\
  || miss "missing critical file: core/src/main/java/org/litepal/LitePal.kt"
test -f "core/src/main/java/org/litepal/crud/LitePalSupport.java" \\
  && ok "core/src/main/java/org/litepal/crud/LitePalSupport.java" \\
  || miss "missing critical file: core/src/main/java/org/litepal/crud/LitePalSupport.java"
test -f "core/src/main/java/org/litepal/tablemanager/LitePalOpenHelper.java" \\
  && ok "core/src/main/java/org/litepal/tablemanager/LitePalOpenHelper.java" \\
  || miss "missing critical file: core/src/main/java/org/litepal/tablemanager/LitePalOpenHelper.java"
test -f "core/src/main/java/org/litepal/parser/LitePalParser.java" \\
  && ok "core/src/main/java/org/litepal/parser/LitePalParser.java" \\
  || miss "missing critical file: core/src/main/java/org/litepal/parser/LitePalParser.java"
test -f "core/src/main/java/org/litepal/tablemanager/Creator.java" \\
  && ok "core/src/main/java/org/litepal/tablemanager/Creator.java" \\
  || miss "missing critical file: core/src/main/java/org/litepal/tablemanager/Creator.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1388 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1358d)"
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/guolindev/LitePal"
  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).

LitePal is an Android ORM library that eliminates boilerplate SQL code by mapping Java/Kotlin models directly to SQLite tables. It provides fluent query APIs, automatic schema migration, and CRUD operations without writing SQL, making SQLite database access on Android as simple as working with POJOs. Single-module library structure: core/ contains the ORM engine split into crud/ (save/update/delete/query handlers), async/ (background execution with callbacks), annotation/ (Column, Encrypt markers), and exceptions/. Entry points are LitePal.kt (Kotlin facade) and LitePalBase.java (Java legacy). Models extend LitePalSupport and declare relationships via AssociationsAnalyzer.

Android application developers who want to use SQLite databases without SQL complexity. Specifically targets developers building mobile apps who need straightforward object persistence with automatic table creation and schema upgrades.

Production-ready and actively maintained. The library has 14,826 stars on GitHub, supports Android SDK 21+, includes comprehensive CRUD and async execution patterns (SaveExecutor, UpdateOrDeleteExecutor, FindExecutor), and was recently updated to version 3.2.3 with Kotlin support alongside the Java core.

Low risk for active projects; maintained by guolindev with clear versioning and Kotlin-first modern features. Primary risk is single-maintainer dependency (core maintainer crucial), but codebase is stable with well-established patterns for 1:1, 1:N, and N:N relationships. No high-complexity external dependencies visible in the structure.

Active development with Kotlin-first approach (LitePal.kt is the primary entry point alongside Java legacy support). Recent work includes async callback patterns (AverageCallback, FindMultiCallback), encryption support (Encrypt annotation), and fluent query API (FluentQuery.java). Multi-database support is implemented but specific active PRs/issues not visible from provided data.

git clone https://github.com/guolindev/LitePal.git
cd LitePal
./gradlew build

Then integrate into your Android project by adding implementation 'org.litepal.guolindev:core:3.2.3' to build.gradle and create litepal.xml in assets/ with database name, version, and model class mappings.

Daily commands: This is a library, not an app. Build with ./gradlew build in the core/ directory. To test: add to an Android test project's build.gradle, configure litepal.xml in assets/, initialize via LitePalApplication or LitePal.initialize(context), then use LitePal.select(...).from(...).find().

• core/src/main/java/org/litepal/LitePal.kt — Primary public API entry point for all LitePal operations; understand this first to grasp the library's fluent query and CRUD patterns
• core/src/main/java/org/litepal/crud/LitePalSupport.java — Base class for all model entities; defines save, update, delete, and query methods that every data model inherits
• core/src/main/java/org/litepal/tablemanager/LitePalOpenHelper.java — SQLiteOpenHelper subclass managing database creation, upgrades, and schema generation; critical for understanding DB lifecycle
• core/src/main/java/org/litepal/parser/LitePalParser.java — Parses litepal.xml configuration file; required to understand how the library discovers database name, version, and tables
• core/src/main/java/org/litepal/tablemanager/Creator.java — Generates and executes CREATE TABLE statements by analyzing model classes; essential for table auto-generation logic
• core/src/main/java/org/litepal/crud/SaveHandler.java — Handles INSERT/UPDATE logic for models; core implementation of persistence operations
• core/src/main/java/org/litepal/crud/QueryHandler.java — Implements SELECT queries with fluent API support; demonstrates the abstraction over raw SQL

Add a new data model with CRUD support

1. Create a Java/Kotlin class extending LitePalSupport in your app package (core/src/main/java/org/litepal/crud/LitePalSupport.java)
2. Define public fields matching database columns; optionally add @Column and @Encrypt annotations (core/src/main/java/org/litepal/annotation/Column.java)
3. Register the model class in litepal.xml <mapping> element under <list> (core/src/main/java/org/litepal/parser/LitePalContentHandler.java)
4. Call LitePal.getDatabase() or model.save() to trigger auto table creation via Creator (core/src/main/java/org/litepal/tablemanager/Creator.java)

Add a one-to-many or many-to-one relationship

1. In the child model, add a field of the parent type (e.g., Parent parent) with @Column annotation if customization needed (core/src/main/java/org/litepal/annotation/Column.java)
2. Relationship is auto-detected by Many2OneAnalyzer during schema generation (core/src/main/java/org/litepal/crud/Many2OneAnalyzer.java)
3. Query with fluent API: Parent parent = Parent.where(...).find() or Child.findById(id).getParent() (core/src/main/java/org/litepal/crud/QueryHandler.java)

Execute custom SQL query with safer APIs

1. Use LitePal.findBySQL() or findBySQL() on any model instance instead of raw SQLiteDatabase.rawQuery() (core/src/main/java/org/litepal/LitePal.kt)
2. Build WHERE clauses with Operator.where() fluent API for parameterized queries (core/src/main/java/org/litepal/Operator.java)
3. Results are auto-converted to model instances by DataHandler cursor parsing logic (core/src/main/java/org/litepal/crud/DataHandler.java)

Add encryption to sensitive fields

1. Annotate sensitive string fields with @Encrypt in your model class (core/src/main/java/org/litepal/annotation/Encrypt.java)
2. Encryption/decryption is handled automatically by CipherUtil during save and load

litepal.xml config is mandatory: must exist in assets/ folder with <dbname>, <version>, and <list><mapping> entries or initialization fails silently. Models must extend LitePalSupport: plain POJOs won't work—this is not obvious from casual reading. Database version bump required for schema changes: modifying a model's fields requires incrementing <version> in litepal.xml to trigger auto-migration. Relationship loading is lazy by default: accessing associated collections doesn't auto-populate; must call explicit load methods. Encryption annotation exists but details sparse: Encrypt.java is present but usage pattern not obvious from file list alone.

• Object-Relational Mapping (ORM) — Core paradigm of LitePal—maps Java/Kotlin objects to SQL tables automatically; understanding ORM is essential to avoid impedance mismatch surprises (lazy loading, N+1 queries, cascade behavior)
• Fluent Builder Pattern — LitePal's FluentQuery uses method chaining to build SQL queries without strings; critical to understanding how select().where().groupBy().orderBy() avoids SQL injection
• Schema Migration and Database Versioning — LitePal's version tag in litepal.xml triggers auto-migration; developers must understand how version bumps map to table alterations and data preservation to avoid data loss
• Lazy Loading in Relationships — LitePal uses lazy loading for 1:N and N:N relationships; developers must call explicit load methods to avoid missing associated objects and understand performance implications
• Callback Pattern for Async Operations — LitePal's async package uses callback interfaces (SaveCallback, FindCallback, etc.) instead of RxJava or Coroutines; critical for background database operations without blocking UI thread
• Foreign Key Relationships (1:1, 1:N, N:N) — LitePal's AssociationsAnalyzer, Many2OneAnalyzer, Many2ManyAnalyzer implement relational model; understanding these relationships is essential for modeling complex domain objects
• Data Access Object (DAO) Pattern — LitePalSupport base class functions as a DAO, encapsulating database access logic in models; recognizing this pattern helps understand separation of concerns in LitePal architecture

• greenrobot/greenDAO — Comparable Android ORM library with similar object-relational mapping approach; greenDAO emphasizes performance where LitePal prioritizes simplicity
• realm/realm-java — Alternative Android database library with mobile-optimized embedded database; competes with LitePal for zero-SQL use cases but uses proprietary Realm engine instead of SQLite
• square/sqlbrite — Lightweight SQLite wrapper for Android with reactive extensions; lower-level alternative for developers who want more SQL control than LitePal provides
• guolindev/Gank.io-ktx — Sample Android project by same maintainer demonstrating LitePal usage in a real app; good reference for API patterns and integration
• android/architecture-samples — Google's Android architecture guide includes TodoMVC implementations showing modern persistence patterns; useful context for where LitePal fits in Android ecosystem

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 Many-to-Many relationship operations in crud package

The Many2ManyAnalyzer.java exists but there are no visible test files for relationship handling. Testing M2M operations (create, read, update, delete through join tables) is critical for an ORM library. This would improve reliability and prevent regressions when contributors modify association logic.

• [ ] Create core/src/test/java/org/litepal/crud/Many2ManyAnalyzerTest.java with tests for M2M creation, association fetching, and deletion
• [ ] Add test fixtures for models with @ForeignKey annotations representing M2M relationships
• [ ] Test Many2ManyAnalyzer against edge cases: empty associations, circular relationships, cascade deletes
• [ ] Verify join table creation and cleanup with AssociationCreator and AssociationUpdater

Add async callback timeout handling and cancellation support

The async package (AsyncExecutor, FindExecutor, SaveExecutor, etc.) lacks timeout and cancellation mechanisms. For long-running database operations on mobile devices, this is a critical feature. Contributors could add cancellation tokens and timeout support similar to standard async patterns in Android.

• [ ] Extend AsyncExecutor.java base class to accept timeout configuration and CancellationToken
• [ ] Modify FindExecutor.java, FindMultiExecutor.java, and SaveExecutor.java to support operation cancellation mid-execution
• [ ] Add timeout handling in corresponding callbacks (FindCallback, SaveCallback, etc.) to invoke onCancelled() or onTimeout()
• [ ] Add integration tests in core/src/test demonstrating timeout and cancellation workflows

Implement batch operation APIs with transaction support in SaveHandler and UpdateHandler

SaveHandler.java and UpdateHandler.java currently handle single operations. The library lacks explicit batch insert/update operations within transactions, which are essential for performance when dealing with large datasets. This is a high-value feature gap for developers working with bulk operations.

• [ ] Add batchSave(List<LitePalSupport>) and batchUpdate(List<LitePalSupport>) methods to SaveHandler.java and UpdateHandler.java
• [ ] Implement transaction wrapping in DynamicExecutor.java to execute batch operations atomically
• [ ] Add corresponding async variants: BatchSaveExecutor and BatchUpdateExecutor in crud/async package
• [ ] Create integration tests demonstrating batch operations with rollback on partial failure scenarios

• Add missing test coverage for One2OneAnalyzer.java: core/src/main/java/org/litepal/crud/One2OneAnalyzer.java exists but no corresponding test file visible in the list; write unit tests for 1:1 relationship detection and lazy loading.
• Document fluent query API with code examples: FluentQuery.java is powerful but lacks inline Javadoc examples; add method-level documentation with concrete before/after SQL comparisons for select(), where(), groupBy(), orderBy().
• Implement missing AsyncCallback for aggregate functions: AverageCallback and CountCallback exist but no AggregateCallback base class; create generic callback interface with onSuccess(result) for extensibility to sum(), max(), min().

• High · Outdated Gradle Build Plugin — build.gradle (classpath 'com.android.tools.build:gradle:7.0.1'). The project uses Gradle plugin version 7.0.1 (from 2021). This version contains known security vulnerabilities. Current stable versions are 8.x+. Outdated build tools can expose the application to build-time attacks and dependency resolution vulnerabilities. Fix: Update to the latest stable Gradle plugin version (8.x or newer). Review Android Gradle Plugin release notes for security patches.
• High · Outdated Kotlin Version — build.gradle (ext.kotlin_version = '1.5.21'). Kotlin version 1.5.21 is from June 2021 and no longer receives security updates. Current versions are 1.9.x+. Outdated Kotlin may contain known vulnerabilities affecting compilation and runtime security. Fix: Update Kotlin to the latest stable version (1.9.x or newer). Review Kotlin release notes for security improvements.
• High · Potential SQL Injection Vulnerability — core/src/main/java/org/litepal/crud/ (especially DynamicExecutor.java, QueryHandler.java, SaveHandler.java). The codebase implements an ORM library with SQL query generation. Files like DynamicExecutor.java, QueryHandler.java, and SaveHandler.java suggest dynamic SQL construction. Without proper parameterized query validation, there's risk of SQL injection if user input is not properly sanitized or if raw SQL APIs exist. Fix: Ensure all SQL queries use parameterized statements (prepared statements). Implement input validation for all user-provided data. Review the FluentQuery API to verify it doesn't allow raw SQL concatenation. Add unit tests for injection scenarios.
• Medium · Encryption Implementation Not Verified — core/src/main/java/org/litepal/annotation/Encrypt.java and core/src/main/java/org/litepal/util/cipher/. The codebase includes an @Encrypt annotation and cipher utilities (core/src/main/java/org/litepal/util/cipher), but the implementation details are not visible. Custom encryption implementations often have security flaws. Without reviewing the cipher code, it's unclear if industry-standard encryption is used. Fix: Verify that encryption uses well-established algorithms (AES-256). Use Android's Keystore system for key management. Avoid custom encryption implementations. Have the cipher code reviewed by security experts. Consider using established libraries like Conscrypt.
• Medium · Deprecated Repository Configuration — build.gradle (repositories { jcenter() }). The build.gradle uses jcenter() repository which was deprecated and shut down in 2021. Relying on jcenter() can lead to dependency resolution failures and potential use of compromised packages. Fix: Remove jcenter() from repositories. Use only google() and mavenCentral(). Verify all dependencies are available in active repositories.
• Medium · Missing ProGuard Configuration — core/proguard-rules.pro. While a proguard-rules.pro file exists, without visibility into its contents, it's unclear if sensitive package structures and method names are properly obfuscated. This could expose implementation details to reverse engineering. Fix: Ensure ProGuard/R8 rules include: keep rules for public APIs only, obfuscation of sensitive classes, removal of logging statements, and optimization of code. Regularly review and update rules.
• Medium · Potential Information Disclosure via Logging — core/src/main/java/org/litepal/util/LitePalLog.java. The codebase includes LitePalLog.java utility. Database operations may log sensitive data (table names, column values, queries). Insufficient log filtering could expose sensitive information in production builds. Fix: Ensure logging is disabled in production builds. Implement conditional logging based on BuildConfig.DEBUG. Never log sensitive data (passwords, keys, PII). Use appropriate log levels (ERROR/WARN for production).
• Low · No Visible Security Headers Configuration — undefined. While this is an embedded library (not a web service), the infrastructure configuration is not visible. If this library is ever used with a backend API, ensure proper security headers are configured 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.