chore: update AGENTS.md
This commit is contained in:
cogwheel0
158
AGENTS.md
158
AGENTS.md
@@ -1,23 +1,143 @@
|
|||||||
# Conduit - Flutter Mobile App for Open-WebUI
|
# AGENTS.md
|
||||||
|
|
||||||
|
Guidelines for AI coding agents working in this repository. Follow these guardrails to make safe, minimal, and effective changes.
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
- Define how agents contribute changes safely to this Flutter mobile app.
|
||||||
|
- Provide project‑specific commands, structure, and do/don’t rules.
|
||||||
|
- Ensure consistency with existing code style and workflows.
|
||||||
|
|
||||||
|
## Guardrails
|
||||||
|
|
||||||
|
- Minimal, targeted changes only; don’t refactor broadly without a clear reason.
|
||||||
|
- Don’t edit generated files or vendored sources (see “Do Not Edit” list).
|
||||||
|
- Don’t introduce new dependencies without a clear justification.
|
||||||
|
- Don’t commit secrets, tokens, or credentials. Use env/config only.
|
||||||
|
- Don’t change licensing headers or LICENSE.
|
||||||
|
- Prefer surgical fixes over sweeping rewrites; match existing patterns.
|
||||||
|
- Update or add documentation when behavior changes.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
- Stack: Flutter/Dart mobile app for interacting with Open‑WebUI.
|
||||||
|
- Notable packages: `flutter_riverpod`, `dio`, `freezed`, `json_serializable`, `flutter_secure_storage`.
|
||||||
|
- Codegen: `build_runner` (freezed/json_serializable) and Flutter gen‑l10n.
|
||||||
|
- State management: Riverpod.
|
||||||
|
|
||||||
|
## Key Commands
|
||||||
|
|
||||||
|
Run from repository root.
|
||||||
|
|
||||||
## Build & Test Commands
|
|
||||||
```bash
|
```bash
|
||||||
flutter pub get # Install dependencies
|
# Install deps
|
||||||
flutter pub run build_runner build --delete-conflicting-outputs # Generate code
|
flutter pub get
|
||||||
flutter analyze # Run static analysis
|
|
||||||
flutter run -d ios/android # Run debug build
|
# Generate code (freezed/json_serializable)
|
||||||
flutter build apk --release # Build Android release
|
flutter pub run build_runner build --delete-conflicting-outputs
|
||||||
flutter build ipa --release # Build iOS release
|
|
||||||
|
# Localization codegen (auto during run/build)
|
||||||
|
flutter gen-l10n
|
||||||
|
|
||||||
|
# Analyze & format
|
||||||
|
flutter analyze
|
||||||
|
dart format .
|
||||||
|
|
||||||
|
# Run app (pick a platform)
|
||||||
|
flutter run -d ios
|
||||||
|
flutter run -d android
|
||||||
|
|
||||||
|
# Build release artifacts
|
||||||
|
flutter build apk --release
|
||||||
|
flutter build appbundle --release
|
||||||
|
flutter build ios --release
|
||||||
```
|
```
|
||||||
|
|
||||||
## Code Style Guidelines
|
## Repository Structure (high‑level)
|
||||||
- **State Management**: Use Riverpod providers in `providers/` folders
|
|
||||||
- **Architecture**: Follow clean architecture - `core/`, `features/`, `shared/`
|
```
|
||||||
- **Imports**: Group by package/relative, use absolute paths for project files
|
lib/
|
||||||
- **Models**: Use Freezed for data classes with `.freezed.dart` and `.g.dart` generated files
|
core/ # models, services, providers, utils
|
||||||
- **Error Handling**: Use ApiErrorHandler and error interceptors, avoid print statements
|
features/ # feature‑scoped UI/logic (auth, chat, server, settings)
|
||||||
- **Naming**: snake_case files, PascalCase classes, camelCase methods/variables
|
l10n/ # ARB + generated localization
|
||||||
- **Async**: Prefer async/await over raw Futures, handle errors with try-catch
|
shared/ # shared widgets, theme, utils
|
||||||
- **Widgets**: Separate presentation (widgets/) from business logic (services/)
|
```
|
||||||
- **UI Design**: Use AppTheme colors/styles and ConduitThemeExtension for consistent design
|
|
||||||
- **Dependencies**: Check pubspec.yaml before adding packages - prefer existing solutions
|
Follow existing folder conventions when adding code. Prefer feature folders for new UI or logic.
|
||||||
|
|
||||||
|
## Code Generation
|
||||||
|
|
||||||
|
- Freezed/JSON: run `flutter pub run build_runner build --delete-conflicting-outputs` after changes to models/DTOs.
|
||||||
|
- Localization: edit ARB files and run `flutter gen-l10n` (or `flutter run`). See `docs/localization.md`.
|
||||||
|
|
||||||
|
## Do Not Edit (Generated/Vendored)
|
||||||
|
|
||||||
|
- `build/`
|
||||||
|
- `lib/l10n/app_localizations*.dart` (generated by gen‑l10n)
|
||||||
|
- `openwebui-src/` (vendored upstream; only update by syncing from upstream, not ad‑hoc edits)
|
||||||
|
- Any other generated files created by build tools
|
||||||
|
|
||||||
|
If a change appears necessary to a generated file, modify its source (e.g., ARB or model) and regenerate.
|
||||||
|
|
||||||
|
## Patterns & Style
|
||||||
|
|
||||||
|
- Riverpod: prefer providers/notifiers consistent with existing usage.
|
||||||
|
- Networking: use the shared `Dio` provider and interceptors if present.
|
||||||
|
- Models: use `freezed`/`json_serializable` patterns matching current models.
|
||||||
|
- UI: reuse shared widgets where possible; keep styling consistent.
|
||||||
|
- Null safety: follow strict null‑safety conventions already in the codebase.
|
||||||
|
- Lints: keep `flutter analyze` clean; fix warnings you introduce.
|
||||||
|
|
||||||
|
## Validation Checklist (before opening a PR)
|
||||||
|
|
||||||
|
- Ran `flutter pub get` and codegen commands.
|
||||||
|
- App compiles and runs on at least one target (`ios` or `android`).
|
||||||
|
- `flutter analyze` passes with no new issues.
|
||||||
|
- Updated docs/README if behavior or setup changed.
|
||||||
|
- No changes to generated/vendored files.
|
||||||
|
- No secrets, tokens, or credentials added to the repo.
|
||||||
|
|
||||||
|
## Localization
|
||||||
|
|
||||||
|
- Add/edit strings in `lib/l10n/app_en.arb`; mirror in other `app_<lang>.arb` as needed.
|
||||||
|
- Provide `@key` metadata with descriptions and placeholders.
|
||||||
|
- Don’t edit `app_localizations*.dart` directly. See `docs/localization.md`.
|
||||||
|
|
||||||
|
## Releases
|
||||||
|
|
||||||
|
- Primary release flow is CI‑driven. A helper exists at `scripts/release.sh`.
|
||||||
|
- Don’t bump versions casually. If required, coordinate and follow `scripts/release.sh` prompts.
|
||||||
|
|
||||||
|
## When Adding Dependencies
|
||||||
|
|
||||||
|
- Justify why it’s needed and whether an existing dependency covers the use case.
|
||||||
|
- Prefer well‑maintained packages with strong adoption.
|
||||||
|
- Keep `pubspec.yaml` tidy; avoid overlapping functionality.
|
||||||
|
|
||||||
|
## When Touching Platform Code
|
||||||
|
|
||||||
|
- iOS: ensure entitlements, Info.plist keys, and signing remain valid.
|
||||||
|
- Android: check permissions, minSdk (23+), and manifest changes.
|
||||||
|
- Test basic run on the affected platform.
|
||||||
|
|
||||||
|
## Security & Privacy
|
||||||
|
|
||||||
|
- Credentials must use platform secure storage (`flutter_secure_storage`).
|
||||||
|
- Avoid logging sensitive information.
|
||||||
|
- Network calls should respect the configured Open‑WebUI endpoint and headers.
|
||||||
|
|
||||||
|
## PR Expectations
|
||||||
|
|
||||||
|
- Keep diffs focused; include a short rationale in the PR description.
|
||||||
|
- Link related issues or TODOs when possible.
|
||||||
|
- Include screenshots or short clips for UI changes.
|
||||||
|
|
||||||
|
## If You’re Unsure
|
||||||
|
|
||||||
|
- Prefer creating a small draft PR or documenting assumptions inline with the PR description rather than pushing risky changes.
|
||||||
|
- When in doubt about ownership or expectations, open a GitHub issue first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Thank you for keeping changes safe, minimal, and consistent. This helps maintain velocity and quality for the Conduit app.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user