feat: track installed versions and annotate ChangeLog with install dates (#457)

lib/core/db_schema_version.dart

@@ -1 +1 @@
-const int dbSchemaVersion = 39;
+const int dbSchemaVersion = 40;

lib/data/db/database.dart

@@ -338,6 +338,17 @@ class EmailNotes extends Table {
   Set<Column> get primaryKey => {id};
 }
 
+/// Records the first time the user ran each app version (identified by GIT_HASH).
+/// Added in schema v40.
+@DataClassName('InstalledVersionRow')
+class InstalledVersions extends Table {
+  TextColumn get gitHash => text()();
+  DateTimeColumn get installedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {gitHash};
+}
+
 /// App-wide user preferences, stored as a singleton row (id always 1).
 @DataClassName('UserPreferencesRow')
 class UserPreferences extends Table {
@@ -384,6 +395,7 @@ class UserPreferences extends Table {
     UserPreferences,
     ImageTrustedSenders,
     EmailNotes,
+    InstalledVersions,
   ],
 )
 class AppDatabase extends _$AppDatabase {
@@ -663,8 +675,30 @@ class AppDatabase extends _$AppDatabase {
           if (from < 39) {
             await m.createTable(emailNotes);
           }
+          if (from < 40) {
+            await m.createTable(installedVersions);
+          }
         },
       );
+
+  /// Inserts a row for [gitHash] the first time that version is seen.
+  /// Subsequent calls for the same hash are silently ignored so the original
+  /// install timestamp is preserved.
+  Future<void> recordInstalledVersionIfNew(String gitHash) async {
+    if (gitHash.isEmpty) return;
+    await into(installedVersions).insert(
+      InstalledVersionsCompanion.insert(
+        gitHash: gitHash,
+        installedAt: DateTime.now(),
+      ),
+      mode: InsertMode.insertOrIgnore,
+    );
+  }
+
+  Future<Map<String, DateTime>> loadInstalledVersions() async {
+    final rows = await select(installedVersions).get();
+    return {for (final r in rows) r.gitHash: r.installedAt};
+  }
 }
 
 // Resolved once in main() via initDatabasePath() before runApp().

lib/di.dart

@@ -294,6 +294,10 @@ final noteRepositoryProvider = Provider<NoteRepository>((ref) {
   );
 });
 
+final installedVersionsProvider = FutureProvider<Map<String, DateTime>>((ref) {
+  return ref.watch(dbProvider).loadInstalledVersions();
+});
+
 /// Stream of notes for a specific email, identified by (accountId, messageId).
 final notesProvider =
     StreamProvider.autoDispose.family<List<EmailNote>, (String, String)>(

lib/main.dart

@@ -86,6 +86,8 @@ class SharedInboxApp extends ConsumerStatefulWidget {
   ConsumerState<SharedInboxApp> createState() => _SharedInboxAppState();
 }
 
+const _kGitHash = String.fromEnvironment('GIT_HASH');
+
 class _SharedInboxAppState extends ConsumerState<SharedInboxApp> {
   @override
   void initState() {
@@ -93,6 +95,11 @@ class _SharedInboxAppState extends ConsumerState<SharedInboxApp> {
     // Start background IMAP sync once — runs for the lifetime of the app.
     ref.read(syncManagerProvider).start();
     ref.read(reliabilityRunnerProvider).start();
+    if (_kGitHash.isNotEmpty) {
+      unawaited(
+        ref.read(dbProvider).recordInstalledVersionIfNew(_kGitHash),
+      );
+    }
   }
 
   @override

lib/ui/screens/changelog_screen.dart

@@ -2,21 +2,79 @@ import 'dart:async';
 
 import 'package:flutter/material.dart';
 import 'package:flutter_markdown_plus/flutter_markdown_plus.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:sharedinbox/di.dart';
 import 'package:url_launcher/url_launcher.dart';
 
-class ChangeLogScreen extends StatelessWidget {
+class ChangeLogScreen extends ConsumerWidget {
   const ChangeLogScreen({super.key});
 
+  static const _months = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+  ];
+
+  static String _formatInstallDate(DateTime dt) {
+    final h = dt.hour.toString().padLeft(2, '0');
+    final m = dt.minute.toString().padLeft(2, '0');
+    final month = _months[dt.month - 1];
+    return '$h:$m, ${dt.day} $month ${dt.year}';
+  }
+
+  // Changelog lines have the form:
+  //   * 2026-06-05 [abc1234](https://...): subject
+  // This pattern captures the short hash inside the markdown link.
+  static final _hashPattern = RegExp(r'\[([0-9a-f]{6,12})\]\(');
+
+  static String _injectInstallMarkers(
+    String changelog,
+    Map<String, DateTime> versions,
+  ) {
+    if (versions.isEmpty) return changelog;
+    final lines = changelog.split('\n');
+    final buf = StringBuffer();
+    for (final line in lines) {
+      final match = _hashPattern.firstMatch(line);
+      if (match != null) {
+        final lineHash = match.group(1)!;
+        for (final entry in versions.entries) {
+          final stored = entry.key;
+          final matches = stored == lineHash ||
+              stored.startsWith(lineHash) ||
+              lineHash.startsWith(stored);
+          if (!matches) continue;
+          buf.write(
+            '\n---\n\n**Installed: ${_formatInstallDate(entry.value)}**\n\n',
+          );
+          break;
+        }
+      }
+      buf.writeln(line);
+    }
+    return buf.toString();
+  }
+
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
+    final installedVersions = ref.watch(installedVersionsProvider);
     return Scaffold(
       appBar: AppBar(title: const Text('ChangeLog')),
       body: FutureBuilder<String>(
-        future: DefaultAssetBundle.of(
-          context,
-        ).loadString('assets/changelog.txt'),
+        future:
+            DefaultAssetBundle.of(context).loadString('assets/changelog.txt'),
         builder: (context, snapshot) {
-          if (snapshot.connectionState == ConnectionState.waiting) {
+          if (snapshot.connectionState == ConnectionState.waiting ||
+              installedVersions.isLoading) {
             return const Center(child: CircularProgressIndicator());
           }
           if (snapshot.hasError) {
@@ -25,8 +83,10 @@ class ChangeLogScreen extends StatelessWidget {
             );
           }
           final content = snapshot.data ?? 'No changelog entries found.';
+          final versions = installedVersions.value ?? {};
+          final annotated = _injectInstallMarkers(content, versions);
           return Markdown(
-            data: content,
+            data: annotated,
             onTapLink: (text, href, title) {
               if (href != null) {
                 unawaited(