Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

6.7 KB
Raw Blame
import 'dart:async';
import 'dart:collection';

import 'package:flutter/foundation.dart';

import 'app_log.dart';

/// How a [LogEntry] ended, as the Debug list draws it.
enum LogStatus { running, ok, failed, warned, event }

/// One thing the app did, held in memory for Settings ▸ Debug.
///
/// The same events the file sinks write — this is a *mirror* of them, not a
/// second stream (see `log_stream_sinks.dart`), so what the screen shows and
/// what a support bundle would carry can never disagree.
///
/// Deliberately mutable, unlike Grid's `GridCommandLog`, which is immutable and
/// re-created through `copyWith` because Riverpod compares state objects. This
/// buffer is a [ChangeNotifier]: a command that is still running collects its
/// output lines and its exit code in place, and the one notification that
/// follows is what the list rebuilds on.
class LogEntry {
  LogEntry({
    required this.id,
    required this.at,
    required this.level,
    required this.category,
    required this.message,
    this.error,
    this.stackTrace,
    this.command,
  });

  /// Monotonic within a session — also the id [LogStream] updates a running
  /// command by.
  final int id;

  final DateTime at;

  /// `app`, `ws`, `cli`, `api`, `flutter` — [AppLog]'s own tag, which is what
  /// the Debug screen's lenses are built from.
  final String category;

  /// The line as the log file holds it, minus the stamp and the level.
  final String message;

  /// Decided when a command ends, so a non-zero exit reads as an error without
  /// the caller having to say so twice.
  AppLogLevel level;

  final String? error;
  final String? stackTrace;

  /// Present only for a CLI invocation — the transcript behind [message].
  final LogCommand? command;

  LogStatus get status {
    final invocation = command;
    if (invocation == null) {
      return switch (level) {
        AppLogLevel.error => LogStatus.failed,
        AppLogLevel.warn => LogStatus.warned,
        _ => LogStatus.event,
      };
    }
    if (invocation.running) return LogStatus.running;
    return invocation.failed ? LogStatus.failed : LogStatus.ok;
  }

  /// Whether opening the row would show anything the row itself does not.
  bool get hasDetail =>
      error != null ||
      stackTrace != null ||
      (command?.output.isNotEmpty ?? false);
}

/// One CLI invocation's transcript: its output as it arrives, and how it ended.
class LogCommand {
  /// Output lines, oldest first. `!` lines are stderr, tagged at the sink so
  /// the detail dialog can colour them without a second list.
  final List<String> output = [];

  bool running = true;
  int? exitCode;
  Duration? duration;
  String? error;

  /// Set once [LogStream.maxOutputLines] is reached — said out loud rather than
  /// trailing off, so nobody reads a clipped transcript as the whole one.
  bool clipped = false;

  bool get failed => error != null || (exitCode != null && exitCode != 0);
}

/// The app's own log, as the running app still holds it: a bounded ring of the
/// most recent entries, newest first.
///
/// Fed by [StreamAppLog]/[StreamCliLog], read by Settings ▸ Debug. A singleton
/// like `appLog`, and for the same reason: the things that
/// write to it — the socket, the CLI runners, the HTTP clients — hold no `Ref`
/// and no notifier between them.
class LogStream extends ChangeNotifier {
  LogStream({this.maxEntries = 500, this.maxOutputLines = 300});

  /// How many entries the buffer keeps. Past this the oldest are dropped: this
  /// is the tail of a session, and the whole day is on disk.
  final int maxEntries;

  /// Per-command output cap. An installer prints a progress line per second;
  /// two hundred of those is the app's memory, not a debug aid.
  final int maxOutputLines;

  final List<LogEntry> _entries = [];
  int _seq = 0;
  bool _notifyScheduled = false;

  /// Newest first — the order the Debug list reads in, so the newest line is
  /// the one on screen without scrolling.
  late final UnmodifiableListView<LogEntry> entries = UnmodifiableListView(
    _entries,
  );

  /// Records one event. Returns its id, which [appendOutput] and [finish] take.
  int add(
    AppLogLevel level,
    String category,
    String message, {
    String? error,
    String? stackTrace,
    LogCommand? command,
  }) {
    final id = ++_seq;
    _entries.insert(
      0,
      LogEntry(
        id: id,
        at: DateTime.now(),
        level: level,
        category: category,
        message: message,
        error: error,
        stackTrace: stackTrace,
        command: command,
      ),
    );
    if (_entries.length > maxEntries) {
      _entries.removeRange(maxEntries, _entries.length);
    }
    _scheduleNotify();
    return id;
  }

  /// Appends one line of a running command's output.
  void appendOutput(int id, String line, {bool isError = false}) {
    final command = _commandFor(id);
    if (command == null) return;
    if (command.output.length >= maxOutputLines) {
      command.clipped = true;
      return;
    }
    command.output.add('${isError ? '! ' : '  '}$line');
    _scheduleNotify();
  }

  /// Closes a command out. A non-zero exit or an [error] also raises the
  /// entry's level, so it lands in the Failed lens without a second call.
  void finish(int id, {int? exitCode, Duration? duration, String? error}) {
    final entry = _entryFor(id);
    final command = entry?.command;
    if (entry == null || command == null || !command.running) return;
    command
      ..running = false
      ..exitCode = exitCode
      ..duration = duration
      ..error = error;
    if (command.failed) entry.level = AppLogLevel.error;
    _scheduleNotify();
  }

  void clear() {
    if (_entries.isEmpty) return;
    _entries.clear();
    _scheduleNotify();
  }

  LogEntry? _entryFor(int id) {
    // A command finishes near where it started, and the newest entries are at
    // the front — so this walks a handful of rows, not the buffer.
    for (final entry in _entries) {
      if (entry.id == id) return entry;
    }
    return null;
  }

  LogCommand? _commandFor(int id) {
    final command = _entryFor(id)?.command;
    return command != null && command.running ? command : null;
  }

  /// One notification per microtask, however many lines arrived in it.
  ///
  /// A CLI command's output lands line by line and a busy socket writes several
  /// frames per frame of UI; notifying on each would rebuild the Debug list
  /// dozens of times for one visible change.
  void _scheduleNotify() {
    if (_notifyScheduled) return;
    _notifyScheduled = true;
    scheduleMicrotask(() {
      _notifyScheduled = false;
      notifyListeners();
    });
  }
}

/// The app's in-memory log mirror. Empty unless [installFileLogs] wired the
/// mirroring sinks — which it only does where the Debug screen exists.
final LogStream logStream = LogStream();