test(studio): seven FaiLog cases + visibleForTesting path override

FaiLog used to compute its destination directly from HOME, which
made it impossible to test without scribbling on the operator's
real ~/.fai/logs/. Adds a static testPathOverride seam tagged
@visibleForTesting so the singleton can be redirected at a per-
test temp file.

The new test/fai_log_test.dart covers:

  - append() writes one JSON-shaped line per event
  - context field round-trips when supplied
  - tail() returns oldest-first
  - tail(maxLines:) caps and keeps the newest entries
  - rotation moves the previous log to .log.1 past 256 KiB
  - path getter honours the override
  - writes to an impossible path do not throw — best-effort
    contract that protects the UI from log-write failures

Production behaviour is unchanged: when the override is null
the path getter still computes from HOME/USERPROFILE.

Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>

lib/data/fai_log.dart

@@ -23,6 +23,7 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:meta/meta.dart';
 import 'package:path/path.dart' as p;
 
 class FaiLog {
@@ -37,7 +38,15 @@ class FaiLog {
 
   static const int _rotateBytes = 256 * 1024;
 
+  /// Test seam. Set this in `setUp` to redirect the singleton at
+  /// a per-test temp file; reset to `null` in `tearDown`. Production
+  /// code never touches it — the default getter computes from HOME.
+  @visibleForTesting
+  static String? testPathOverride;
+
   String get _path {
+    final override = testPathOverride;
+    if (override != null) return override;
     final home =
         Platform.environment['HOME'] ??
         Platform.environment['USERPROFILE'] ??

pubspec.lock

@@ -126,7 +126,7 @@ packages:
       path: "../fai_studio_flow_editor"
       relative: true
     source: path
-    version: "0.15.0"
+    version: "0.15.1"
   fake_async:
     dependency: transitive
     description:

test/fai_log_test.dart

@@ -0,0 +1,103 @@
+// Unit tests for FaiLog — the central error log that
+// `~/.fai/logs/studio-errors.log` is the operator-visible
+// surface of. The tests redirect the singleton at a temp file
+// via `FaiLog.testPathOverride` so the real log under HOME is
+// never touched.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:fai_studio/data/fai_log.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('FaiLog', () {
+    late Directory tmp;
+    late File logFile;
+
+    setUp(() {
+      tmp = Directory.systemTemp.createTempSync('fai_log_test_');
+      logFile = File('${tmp.path}/studio-errors.log');
+      FaiLog.testPathOverride = logFile.path;
+    });
+
+    tearDown(() {
+      FaiLog.testPathOverride = null;
+      try {
+        tmp.deleteSync(recursive: true);
+      } catch (_) {/* best-effort */}
+    });
+
+    test('append writes one JSON-shaped line per event', () async {
+      await FaiLog.instance.error('flows.run', 'boom');
+      final lines = await FaiLog.instance.tail();
+      expect(lines, hasLength(1));
+      final entry = jsonDecode(lines.single) as Map<String, Object?>;
+      expect(entry['source'], 'flows.run');
+      expect(entry['error'], 'boom');
+      expect(entry['level'], 'error');
+      expect(entry['ts'], isA<String>());
+    });
+
+    test('context field is preserved when supplied', () async {
+      await FaiLog.instance.error(
+        'theme.plugin.load',
+        Exception('endpoint unreachable'),
+        context: 'capability=studio.theme.space',
+      );
+      final lines = await FaiLog.instance.tail();
+      final entry = jsonDecode(lines.single) as Map<String, Object?>;
+      expect(entry['context'], 'capability=studio.theme.space');
+      expect(entry['error'], contains('endpoint unreachable'));
+    });
+
+    test('tail returns oldest first', () async {
+      await FaiLog.instance.error('a', '1');
+      await FaiLog.instance.error('b', '2');
+      await FaiLog.instance.error('c', '3');
+      final lines = await FaiLog.instance.tail();
+      expect(lines, hasLength(3));
+      final sources = lines.map((l) => jsonDecode(l)['source']).toList();
+      expect(sources, ['a', 'b', 'c']);
+    });
+
+    test('tail caps output at maxLines and keeps the newest', () async {
+      for (var i = 0; i < 20; i++) {
+        await FaiLog.instance.error('burst', 'event-$i');
+      }
+      final lines = await FaiLog.instance.tail(maxLines: 5);
+      expect(lines, hasLength(5));
+      final last = jsonDecode(lines.last) as Map<String, Object?>;
+      expect(last['error'], 'event-19');
+    });
+
+    test('rotation moves the live log to .log.1 past 256 KiB', () async {
+      // Pre-seed the active log just over the cap. The next
+      // append should rotate, leaving the rotated file at
+      // `.log.1` and a short fresh `.log`.
+      logFile.parent.createSync(recursive: true);
+      logFile.writeAsBytesSync(List.filled(257 * 1024, 0x20));
+      await FaiLog.instance.error('rotation', 'after-cap');
+      expect(File('${logFile.path}.1').existsSync(), isTrue);
+      final newSize = logFile.lengthSync();
+      expect(newSize, lessThan(2 * 1024));
+      final newText = logFile.readAsStringSync();
+      expect(newText, contains('"source":"rotation"'));
+    });
+
+    test('path getter returns the override when set', () {
+      expect(FaiLog.instance.path, logFile.path);
+    });
+
+    test('writes failing silently does not throw', () async {
+      // Redirect to a deliberately impossible path. The error()
+      // call must complete cleanly; the operator UI must never
+      // crash because the disk is full / read-only / missing.
+      FaiLog.testPathOverride = '/this/path/does/not/exist/ever/x.log';
+      await expectLater(
+        FaiLog.instance.error('bad.path', 'boom'),
+        completes,
+      );
+    });
+  });
+}