docs: add CLAUDE.md and AGENTS.md for AI coding agents - #908
Conversation
WalkthroughAdds repository-wide AI agent instructions and reference documentation covering coding style, commands, documentation updates, Git workflow, common pitfalls, and testing conventions. ChangesAgent guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 36-54: Update the project-structure Markdown code fence in
CLAUDE.md to specify the text language identifier, changing the opening fence to
```text while preserving the directory listing unchanged.
- Around line 162-167: Update the PR titles entry in the Git Workflow section to
document the exceptions defined in references/git-workflow.md: allow “ignore
title check” and “dependencies” for applicable non-package PRs while retaining
the af:/afpi: requirements for package changes. Keep the always-loaded guidance
consistent with the referenced workflow documentation.
In `@references/commands.md`:
- Around line 63-66: Update the Windows CMake command’s CMAKE_TOOLCHAIN_FILE
placeholder to be shell-safe, using a path such as /path/to/vcpkg or a quoted
placeholder, and clearly indicate that users must replace it with their actual
vcpkg location.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 842b8242-a180-42c1-aaab-19e16a46cee3
📒 Files selected for processing (8)
AGENTS.mdCLAUDE.mdreferences/code-style.mdreferences/commands.mdreferences/docs-update.mdreferences/git-workflow.mdreferences/pitfalls.mdreferences/testing.md
| ``` | ||
| auth0-flutter/ | ||
| ├── auth0_flutter/ # Published package: public Dart API + native glue | ||
| │ ├── lib/ | ||
| │ │ ├── auth0_flutter.dart # Mobile/desktop entry point (Auth0 class) | ||
| │ │ ├── auth0_flutter_web.dart # Web entry point (Auth0Web class) | ||
| │ │ └── src/ | ||
| │ │ ├── mobile/ # Auth, MFA, My Account, Passwordless, CredentialsManager, WebAuthentication | ||
| │ │ ├── web/ # JS interop with auth0-spa-js | ||
| │ │ └── desktop/ # Windows web authentication | ||
| │ ├── android/, ios/, macos/, darwin/ # Native platform implementations (Kotlin, Swift) | ||
| │ ├── windows/ # Native C++ implementation (no native SDK dependency) | ||
| │ ├── example/ # Sample app used for manual verification and native/integration tests | ||
| │ └── test/ # Dart unit tests | ||
| ├── auth0_flutter_platform_interface/ # Published package: platform contract | ||
| │ └── lib/src/ # MethodChannel platform implementations, options/models, exceptions | ||
| ├── scripts/generate-symlinks.sh # Keeps ios/macos/darwin native sources in sync (see Boundaries) | ||
| └── .github/workflows/ # CI: analyze, test, native unit tests, publish, security scans | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language identifier to this Markdown fence.
The project-structure block triggers markdownlint MD040. Use ```text so documentation lint passes.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 36-36: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 36 - 54, Update the project-structure Markdown code
fence in CLAUDE.md to specify the text language identifier, changing the opening
fence to ```text while preserving the directory listing unchanged.
Source: Linters/SAST tools
| # Windows (native C++ client, no vendor SDK — built via CMake + vcpkg) | ||
| cd auth0_flutter/windows | ||
| cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake \ | ||
| -DAUTH0_FLUTTER_ENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the vcpkg placeholder shell-safe.
When pasted literally, <path-to-vcpkg> is interpreted by Bash as input redirection, so this command fails before CMake runs. Use a placeholder such as /path/to/vcpkg or quote it and explicitly instruct users to replace it.
Proposed fix
-cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake \
+cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Windows (native C++ client, no vendor SDK — built via CMake + vcpkg) | |
| cd auth0_flutter/windows | |
| cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake \ | |
| -DAUTH0_FLUTTER_ENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug | |
| # Windows (native C++ client, no vendor SDK — built via CMake + vcpkg) | |
| cd auth0_flutter/windows | |
| cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \ | |
| -DAUTH0_FLUTTER_ENABLE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@references/commands.md` around lines 63 - 66, Update the Windows CMake
command’s CMAKE_TOOLCHAIN_FILE placeholder to be shell-safe, using a path such
as /path/to/vcpkg or a quoted placeholder, and clearly indicate that users must
replace it with their actual vcpkg location.
Documents build/test/lint commands, project structure, boundaries, and security considerations for the federated Flutter plugin so AI agents (and human contributors) have accurate, repo-specific context.
d15e3a0 to
d55c6cc
Compare
| - **Framework:** `flutter_test` + `mockito` (Dart); JUnit/Robolectric (Android, via `./gradlew koverXmlReportDebug`); XCTest (iOS/macOS); a custom C++ test binary built via CMake (Windows) | ||
| - **Test Location:** `auth0_flutter/test/`, `auth0_flutter_platform_interface/test/` | ||
| - **Coverage Tool:** `flutter test --coverage` (lcov) for Dart; JaCoCo/Kover for Android; xcresultparser→Cobertura for iOS; OpenCppCoverage for Windows — all uploaded to Codecov | ||
| - **Coverage Threshold:** project target 2%, patch target 50% (`codecov.yml`) |
There was a problem hiding this comment.
These aren't "targets" — in codecov.yml, 2 and 50 are threshold values (max allowed coverage drop), and project.target is auto. Your own references/testing.md:39 says it correctly ("50% patch threshold, 2% project-drop threshold"). Make this line match that: Coverage Threshold: patch threshold 50%, project-drop threshold 2% (\codecov.yml).
|
|
||
| ## Security Considerations | ||
|
|
||
| - **Token storage:** Credentials are persisted via the native `CredentialsManager` — SimpleKeychain 1.3.0 on iOS/macOS (`auth0_flutter/darwin/.../CredentialsManager/CredentialsManagerHandler.swift`), `EncryptedSharedPreferences` (Android Keystore-backed) on Android (`auth0_flutter/android/.../request_handlers/credentials_manager/`), and OS-level secure storage on Windows. Never log tokens, and never bypass `CredentialsManager` to persist credentials by hand. |
There was a problem hiding this comment.
EncryptedSharedPreferences is the wrong class. Android delegates to Auth0.Android's SecureCredentialsManager (see the handlers/tests under credentials_manager/), which does its own Keystore-backed AES over SharedPreferencesStorage — not the Jetpack EncryptedSharedPreferences. Reword to "the native SecureCredentialsManager (Android Keystore-backed encrypted storage)."
2 participants
Summary
CLAUDE.mdwith project overview, structure, boundaries, security considerations, and lazy-loaded reference pointers for AI coding agents working in this repo.AGENTS.mdimportingCLAUDE.mdper the agent-files convention, so non-Claude tools pick up the same guidance.references/(commands, testing, code-style, git-workflow, pitfalls, docs-update) with the detailed content offloaded from the root file.Test plan
CLAUDE.md/references/*.mdresolves on disk..github/workflows/main.yml,publish-af.yml,publish-afpi.yml, andDEVELOPMENT.md.Note: this PR's title doesn't have an
af:/afpi:prefix since it touches the whole repo, not a single package — may need theignore title checklabel if thepr-title-checkerworkflow flags it.