noo/.claude/context/standards.md

Code standards

Linting

analysis_options.yaml includes package:flutter_lints/flutter.yaml with no rules added/relaxed. Run flutter analyze before considering a change done; it should stay clean.

Comments

Comments are used sparingly and only for non-obvious why — a hidden constraint, a workaround, or the rationale for overriding a framework default. See AppTheme._pageTransitionsTheme/_sliderTheme, NextcloudService._parseDavDate/_davPath, and LoginFlowService's class doc comment for the house style: one short doc comment on the class/function explaining why it exists, not what each line does. Don't add comments that restate the code or describe what a well-named class/method already makes obvious.

Widget structure

• Screens (views/) are typically StatefulWidget when they own controllers/local UI state (e.g. LoginView's form key + text controller); presentation is frequently split into small private StatelessWidgets in the same file (_ServerForm, _WaitingForBrowser in login_view.dart) rather than inlined in one large build. Follow this split for any view complex enough to have more than one visual "mode".
• Private helpers/widgets are prefixed with _ and live in the same file as their one caller; promote to widgets/ only once something is reused across files.
• Read controller state with context.watch<XController>() in build, and context.read<XController>() for one-off calls from callbacks (matches LoginView._handleContinue). Pull in only the specific controller(s) a widget actually needs (e.g. FilesController + SyncStatusController for a Files tile), not a catch-all — see architecture.md's "State management" section for the full controller split and what each one owns.

Controller conventions

• Any method that fetches data and writes it into a shared field (FilesController.refreshData, PhotosController.fetchAllMedia, TrashController.fetchAll, SharesController.fetchAll, RecentController.fetchAll, SessionController._applyCredentialsForAccount) must guard against a stale write from an account the user has since switched away from: capture final gen = session.sessionGeneration; at entry, and check if (gen != session.sessionGeneration) return; immediately after each await before touching any field or calling notifyListeners(). Follow this pattern for any new fetch method added to any controller.
• New persisted state must be classified global vs. per-account (see architecture.md/server.md) up front and live on whichever controller owns that domain — global state (SettingsController) uses a plain _prefsFuture.then((p) => p.setX(key, value)); per-account state goes through _persistAccountPref(key, (p, namespacedKey) => p.setX(namespacedKey, value)) and must also be handled in that controller's own _onAccountCleared/_onAccountActivated listeners (registered via SessionController.addAccountClearedListener/ addAccountActivatedListener in the controller's constructor) so it's correct immediately after a switch, not just at startup.

Testing

• Widget tests must mock platform channels that the app touches on startup — SharedPreferences.setMockInitialValues({}) and a mock MethodChannel('plugins.it_nomads.com/flutter_secure_storage') handler — and disable Google Fonts network fetching (GoogleFonts.config.allowRuntimeFetching = false) in setUpAll. Without these, SessionController's session restore never resolves in the test sandbox (no plugin implementation is registered, so the read future just never completes) and the app stays on _SplashView's indeterminate spinner, which makes pumpAndSettle() hang until its own timeout instead of failing fast. See test/widget_test.dart for the reference setup.
• Run with flutter test.

Local install/deploy

Never use flutter install to push a build to a test device — it always does a full uninstall-then-install (prints "Uninstalling old version..."), and Android deletes all app data (SharedPreferences, secure storage — every saved account/preference) on uninstall. This wipes the app clean on every single deploy, which looks like an account/settings-loss bug but is actually just the install method.

Instead, build then install with adb's replace flag, which updates the APK in place and preserves app data:

flutter build apk --release
adb install -r build/app/outputs/flutter-apk/app-release.apk

This only preserves data if the new APK's signature matches what's already on the device. android/app/build.gradle.kts picks a release signing key in this order: a local android/key.properties (gitignored — points at a gitignored keystore file, e.g. android/app/release-keystore.jks), then CI env vars (RELEASE_KEYSTORE_PATH/_PASSWORD, RELEASE_KEY_ALIAS/ _PASSWORD, set by .gitea/workflows/build.yml from repo secrets), then falls back to the debug key if neither is configured. As long as the same dedicated release keystore backs both key.properties locally and the Gitea secrets, local release builds and CI-built release APKs share one signature, so adb install -r works cleanly either way. A local checkout with no key.properties set up falls back to the (per-machine, ungitted) debug key, which won't match a CI-signed APK — installing one over the other still forces a full uninstall, since there's no way around Android's signature check from the tooling side.

Dependencies

Networking is deliberately split: package:http for simple JSON/XML request-response calls, package:dio only where streaming/progress is needed (downloads). Don't introduce a third HTTP client — extend the existing split instead.