Fix JsonCacheInfoRepository metadata loss on quick exit (#491)

[rickdijk]

✨ What kind of change does this PR introduce? (Bug fix, feature, docs update...)

Bug fix for JsonCacheInfoRepository persistence, plus ignore local AGENTS.md files.

⤵️ What is the current behavior?

JsonCacheInfoRepository debounces disk writes by 3 seconds. If the app is force-stopped or killed before that timer fires (and dispose()/close() is not called), cache metadata updates are lost. Direct writeAsString to the JSON file can also leave an empty/corrupt file if interrupted mid-write.

🆕 What is the new behavior (if this is a feature change)?

• Mutations update memory immediately and await a serialized write-through queue, so completing an insert/update/delete Future means the change is on disk.
• Concurrent updates coalesce via a dirty flag so bursts do not rewrite the file once per mutation.
• Saves write to a .tmp sibling with flush: true, then rename over the destination for atomic replace.
• Write failures are reported with FlutterError.reportError and retried on a later mutation or close().
• deleteDataFile() also removes an orphaned .tmp file.
• Local AGENTS.md is gitignored so agent/contributor notes stay out of the shared repo.

💥 Does this PR introduce a breaking change?

No.

🐛 Recommendations for testing

• Run from flutter_cache_manager/:
  • dart format --set-exit-if-changed .
  • flutter analyze
  • flutter test
• Pay attention to test/repositories/json_file_repository_test.dart storage tests (persist without close, no leftover temp file, failed write reported and retried on close).

📝 Links to relevant issues/docs

Fixes #491

Related durability concerns also touch empty/corrupt JSON reads (#450), but this PR focuses on write timing and atomic replace rather than read recovery.

🤔 Checklist before submitting

• All projects build
• Follows style guide lines (code style guide)
• Relevant documentation was updated
• Rebased onto current develop

Made with Cursor