moasdawiki-app/AGENTS.md

AGENTS.md

Guidance for agentic coding tools working in moasdawiki-app.

Project Snapshot

• Android app module: :app
• Language: Java 17 (no Kotlin sources currently)
• Build system: Gradle wrapper (./gradlew) + Android Gradle Plugin
• Main package: net.moasdawiki.app
• App depends on MoasdaWiki server module artifact: net.moasdawiki:moasdawiki-server

Environment And Baseline

• Use the wrapper, not a globally installed Gradle: ./gradlew ...
• Run commands from repository root.
• Keep changes scoped; do not refactor unrelated files.
• Preserve license headers in Java files.
• Prefer additive, minimal-risk edits.

Build / Lint / Test Commands

Common Lifecycle Commands

• Clean: ./gradlew clean
• Build everything (assemble + checks): ./gradlew :app:build
• Assemble debug APK: ./gradlew :app:assembleDebug
• Assemble release APK: ./gradlew :app:assembleRelease
• Install debug on connected device: ./gradlew :app:installDebug

Lint Commands

• Run lint (default variant): ./gradlew :app:lint
• Run debug lint only: ./gradlew :app:lintDebug
• Run release lint only: ./gradlew :app:lintRelease
• Apply safe lint fixes: ./gradlew :app:lintFix

Unit Test Commands

• Run all unit tests: ./gradlew :app:test
• Run debug unit tests: ./gradlew :app:testDebugUnitTest
• Run release unit tests: ./gradlew :app:testReleaseUnitTest

Run A Single Unit Test (Important)

• Single test class: ./gradlew :app:testDebugUnitTest --tests "net.moasdawiki.app.YourTestClass"
• Single test method: ./gradlew :app:testDebugUnitTest --tests "net.moasdawiki.app.YourTestClass.yourTestMethod"
• Wildcard match: ./gradlew :app:testDebugUnitTest --tests "*YourTestClass*"

Notes:

• Use fully-qualified class names for reliable filtering.
• If the filter reports no tests found, verify package + method names.
• Keep Debug test task unless you specifically need release behavior.

Instrumentation Test Commands

• Run all connected instrumentation tests: ./gradlew :app:connectedDebugAndroidTest
• Run one instrumentation class: ./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=net.moasdawiki.app.YourAndroidTestClass
• Run one instrumentation method: ./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=net.moasdawiki.app.YourAndroidTestClass#yourTestMethod

High-Value Working Agreement

• Before editing, inspect nearby code and follow existing patterns.
• After editing, run the narrowest meaningful verification first.
• For behavior changes, prefer adding/updating tests when test infra exists.
• Do not introduce new build tools or formatting frameworks unless asked.

Source Layout (Current)

• App code: app/src/main/java/net/moasdawiki/app/
• Resources: app/src/main/res/
• Manifest: app/src/main/AndroidManifest.xml
• Gradle module config: app/build.gradle
• Root build config: build.gradle, settings.gradle, gradle.properties

There are currently no app/src/test or app/src/androidTest files in this repository snapshot.

Java Style Conventions To Follow

Formatting

• 4-space indentation, no tabs.
• Opening brace on same line for classes/methods/control blocks.
• Keep methods reasonably focused; avoid large unrelated rewrites.
• Prefer one statement per line for readability.
• Preserve existing block comments and Javadoc style.

Imports

• Use explicit imports; avoid wildcard imports.
• Group imports with blank lines by domain:
  1. android.*
  2. androidx.*
  3. net.moasdawiki.*
  4. java.*
• Keep import order stable and consistent within each group.

Types And Nullability

• Use concrete types unless abstraction improves clarity.
• Follow existing nullability annotations (@NonNull, @Nullable).
• Annotate parameters/returns where null-safety is non-obvious.
• Prefer immutable locals/fields (final) where practical.
• Use boxed types only when null is a real state.

Naming

• Classes: PascalCase (MainActivity, SynchronizeWikiClient).
• Methods/fields/local variables: camelCase.
• Constants: UPPER_SNAKE_CASE.
• Android log tags: short static constant named TAG.
• Preference keys/constants belong in Constants-style central locations.

Control Flow And Readability

• Prefer early returns for invalid preconditions.
• Keep nesting shallow when possible.
• Extract helper methods for repeated logic.
• Use descriptive method names that reflect side effects.

Error Handling And Logging

• Catch specific exceptions whenever practical.
• Log with Android Log at appropriate level (d, i, w, e).
• Include exception object when logging failures.
• Convert low-level failures into domain-friendly outcomes for callers.
• For user-visible failures, pair logs with UI feedback (Toast/status text).
• Avoid swallowing exceptions silently.

Threading / Android Behavior

• Keep network and disk work off the UI thread.
• UI updates must run on UI thread (runOnUiThread(...) pattern).
• Continue using executor-based async style already present.
• Preserve lifecycle-safe behavior in Activity/Fragment methods.

Testing Expectations For Agents

• If you change pure logic, add or update a unit test.
• If you change Android component behavior, prefer instrumentation tests when feasible.
• For low-risk refactors, run at least targeted lint + targeted tests.
• For broader edits, run :app:lint and :app:testDebugUnitTest.

Dependency And Build File Edits

• Keep dependency changes minimal and justified.
• Match existing dependency declaration style in touched file.
• Do not upgrade AGP/Gradle/SDK versions unless explicitly requested.
• Call out deprecation warnings you encounter during Gradle runs.

Commit And PR Hygiene (For Agents)

• Make small, reviewable commits with clear intent.
• In commit messages, explain why the change is needed.
• Include verification commands run and their outcome in PR notes.
• Do not include unrelated formatting churn.

Cursor/Copilot Rule Ingestion

Checked in this repository:

• .cursorrules: not present
• .cursor/rules/: not present
• .github/copilot-instructions.md: not present

If these files are added later, agents should treat them as higher-priority repository instructions and merge them into this guidance.