view release on metacpan or  search on metacpan

lib/App/karr/Foundation/Overview.pm  view on Meta::CPAN

# ABSTRACT: karr-foundation read-only overview — multi-board status dashboard

package App::karr::Foundation::Overview;
our $VERSION = '0.500';
use Moo;


has foundation => (
  is       => 'ro',
  weak_ref => 1,
  required => 1,
);

# ---------------------------------------------------------------------------
# Overview (read-only dashboard)
# ---------------------------------------------------------------------------

sub _print_overview {
  my ( $self, $repos ) = @_;
  for my $repo (@$repos) {
    my $karr   = $self->foundation->_load_karr($repo);
    my %states = $self->foundation->_task_states($repo);

    my %count;
    my ( @in_progress, @blocked );
    for my $id ( sort { $a <=> $b } keys %states ) {
      my $st = $states{$id};
      $count{ $st->{status} // 'unknown' }++;
      push @in_progress, $id if ( $st->{status} // '' ) eq 'in-progress';
      push @blocked,     $id if $st->{blocked};
    }

    # The board's own opt-out (refs/karr/config: foundation.enabled) is the
    # dominant fact about a board, so it leads the flag list — and suppresses
    # the 'agent' flag, because that agent will never run here.
    my $disabled = $self->foundation->_board_disabled($repo);

    my @flags;
    push @flags, 'disabled' if $disabled;
    push @flags, 'agent-running' if $self->foundation->_lock_held($repo);
    if ( $self->foundation->_cooldown_active($repo) ) {
      my $until = $self->foundation->_state_get( $repo, 'cooldown_until' ) // 0;
      # Why, not just how long: a board sitting in cooldown is a board doing
      # nothing, and the only other record of the reason is a COMMON-ERROR
      # line somewhere in .karr.log (#160). last_error belongs to the run that
      # set this deadline — the next run that is not a common error drops it.
      my $why = $self->foundation->_state_get( $repo, 'last_error' );
      push @flags, 'cooldown ' . ( $until - time ) . 's'
                 . ( defined $why ? " ($why)" : '' );
    }
    push @flags, 'agent'
      if !$disabled && defined $self->foundation->_agent_command( $repo, $karr );

    my $total = keys %states;
    printf "%s\n", $repo->basename;
    printf "  %d tasks", $total;
    print '  [' . join( ', ', @flags ) . ']' if @flags;
    print "\n";
    if (%count) {
      printf "  %s\n", join( '  ', map { "$_:$count{$_}" } sort keys %count );
    }
    printf "  disabled:    %s\n", $disabled->{reason} // 'no reason given'
      if $disabled;
    printf "  in-progress: %s\n", join( ', ', map { "#$_" } @in_progress ) if @in_progress;
    printf "  blocked:     %s\n", join( ', ', map { "#$_" } @blocked )     if @blocked;
    print "\n";
  }
  return;
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

App::karr::Foundation::Overview - karr-foundation read-only overview — multi-board status dashboard

=head1 VERSION

version 0.500

=head1 DESCRIPTION

L<App::karr::Foundation::Overview> renders the read-only cross-board dashboard
shown by C<karr-foundation --status> and whenever no board has an agent
configured: per repo it prints the task-status counts, the in-progress and
blocked task ids, and disabled / lock / cooldown / agent flags. A board that
opted out of automated agent runs (C<karr disable>) is shown with a C<disabled>
flag and a C<disabled:> line carrying its reason; its C<agent> flag is
suppressed, because no agent runs there. A board in cooldown carries the
remaining wait and the error that caused it (C<cooldown 240s (rate limit)>),
since a parked board is a board doing nothing. A weak back-reference to the
owning foundation supplies the board data and state helpers.

=head1 SUPPORT

=head2 Issues

Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/karr/issues>.

=head2 IRC

Join C<#langertha> on C<irc.perl.org> or message Getty directly.

=head1 CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

=head1 AUTHOR

Torsten Raudssus <getty@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> L<https://raudssus.de/>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut