feat(meditate): the operator's library on the server, and a course's lessons done synced

An operator's folder (MEDITATE_LIBRARY_DIR) of recordings, pictures and a
YAML manifest, library.yaml (commented sample: library.example.yaml), read
as the server starts and every ten minutes, held in memory. Items without
a licence or credit, files outside the folder, unknown categories and
courses pointing at items not served are refused and logged; a manifest
that doesn't read keeps the library served before. bin/check_library.dart
checks a folder before deploying.

The catalogue goes to signed-in people alone (LibraryEndpoint), with a
12-hour access the server signs; the web server's /library/<served name>
serves the files to that access only, by ranges (relic's StaticHandler).
No request path reaches the file system.

lesson_done: a lesson done, sealed and synced, a row each; the migration
creates the table with its spaceId index and the cascading foreign key to
the sync engine's spaces, as dream's did. ADR 0038, D16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

apps/meditate/halkyon_meditate_server/test/integration/library/library_test.dart

@@ -0,0 +1,123 @@
+import 'dart:io';
+
+import 'package:clock/clock.dart';
+import 'package:halkyon_meditate_server/src/library/library_files.dart';
+import 'package:halkyon_meditate_server/src/library/library_manifest.dart';
+import 'package:halkyon_meditate_server/src/library/meditate_library.dart';
+import 'package:serverpod/serverpod.dart';
+import 'package:test/test.dart';
+
+import '../test_tools/serverpod_test_tools.dart';
+
+void main() {
+  withServerpod('The instance’s library', (sessionBuilder, endpoints) {
+    late Directory folder;
+    late MeditateLibrary library;
+
+    setUp(() async {
+      folder = Directory.systemTemp.createTempSync('library');
+      File('${folder.path}/audio/rain.mp3')
+        ..createSync(recursive: true)
+        ..writeAsBytesSync(List.filled(100, 1));
+      File('${folder.path}/$libraryManifestName').writeAsStringSync('''
+categories:
+  - key: breathwork
+    english: Breathwork
+    german: Atemarbeit
+items:
+  - id: rain
+    title: Rain
+    category: sound
+    language: en
+    licence: CC0 1.0
+    credit: Sample Recordist
+    audio:
+      - file: audio/rain.mp3
+        duration: 60
+courses:
+  - id: listening
+    title: Listening
+    category: sound
+    language: en
+    lessons:
+      - item: rain
+''');
+      library = MeditateLibrary.of(sessionBuilder.build().serverpod)
+        ..folder = folder;
+      await library.reload();
+    });
+
+    tearDown(() async {
+      MeditateLibrary.of(sessionBuilder.build().serverpod).folder = null;
+      await library.reload();
+      folder.deleteSync(recursive: true);
+    });
+
+    final signedIn = sessionBuilder.copyWith(
+      authentication: AuthenticationOverride.authenticationInfo(
+        const Uuid().v7(),
+        {},
+      ),
+    );
+
+    test('gives a signed-in person the catalogue, where the files are and '
+        'an access to fetch them (ADR 0038, D16)', () async {
+      final catalogue = await endpoints.library.catalogue(signedIn);
+
+      expect(catalogue.items.single.id, 'rain');
+      expect(catalogue.items.single.credit, 'Sample Recordist');
+      expect(catalogue.courses.single.lessons.single.item, 'rain');
+      expect(catalogue.categories.single.key, 'breathwork');
+      expect(catalogue.filesUrl, endsWith('/library'));
+      expect(
+        library.access.allows(catalogue.access, clock.now()),
+        isTrue,
+      );
+      expect(catalogue.accessUntil!.isAfter(clock.now()), isTrue);
+    });
+
+    test('gives nobody signed out the catalogue: the content is the '
+        'operator’s, under licences that may not allow it', () async {
+      await expectLater(
+        endpoints.library.catalogue(sessionBuilder),
+        throwsA(isA<ServerpodUnauthenticatedException>()),
+      );
+    });
+
+    test('an instance without a library gives an empty catalogue, and no '
+        'access', () async {
+      library.folder = null;
+      await library.reload();
+
+      final catalogue = await endpoints.library.catalogue(signedIn);
+
+      expect(catalogue.items, isEmpty);
+      expect(catalogue.courses, isEmpty);
+      expect(catalogue.access, isNull);
+    });
+
+    test('a manifest broken while served keeps the last good library, and '
+        'one fixed is read again', () async {
+      final manifest = File('${folder.path}/$libraryManifestName');
+      final good = manifest.readAsStringSync();
+      manifest.writeAsStringSync('items: [broken');
+      expect(await library.reload(), isFalse);
+      expect(library.contents.items.single.id, 'rain');
+
+      manifest.writeAsStringSync(
+        good.replaceFirst('title: Rain', 'title: Rainfall'),
+      );
+      expect(await library.reload(), isTrue);
+      expect(library.contents.items.single.title, 'Rainfall');
+    });
+
+    test('the access it signs lets files be fetched, and no other does', () {
+      final (:token, until: _) = library.access.issue(clock.now());
+      expect(library.access.allows(token, clock.now()), isTrue);
+      expect(
+        LibraryFileAccess().allows(token, clock.now()),
+        isFalse,
+      );
+    });
+  });
+}