view release on metacpan or  search on metacpan

lib/Developer/Dashboard/CLI/Progress.pm  view on Meta::CPAN

    return '[ ]';
}

# _colorize($text, $status)
# Wraps one marker with ANSI color escapes when terminal color output is enabled.
# Input: marker text string and status string.
# Output: plain or ANSI-colored marker string.
sub _colorize {
    my ( $self, $text, $status ) = @_;
    return $text if !$self->{color};
    return "\e[32m$text\e[0m" if defined $status && $status eq 'done';
    return "\e[33m$text\e[0m" if defined $status && $status eq 'running';
    return "\e[31m$text\e[0m" if defined $status && $status eq 'failed';
    return $text;
}

1;

__END__

=head1 NAME

Developer::Dashboard::CLI::Progress - terminal task-board renderer for lifecycle commands

=head1 SYNOPSIS

  my $progress = Developer::Dashboard::CLI::Progress->new(
      title => 'dashboard restart progress',
      tasks => [
          { id => 'stop_web',  label => 'Stop dashboard web service' },
          { id => 'start_web', label => 'Start dashboard web service' },
      ],
      stream  => \*STDERR,
      dynamic => 1,
      color   => 1,
  );
  my $callback = $progress->callback;
  $callback->( { task_id => 'stop_web', status => 'running' } );
  $callback->( { task_id => 'stop_web', status => 'done' } );
  $progress->finish;

=head1 DESCRIPTION

This module renders a simple terminal task board for long-running lifecycle
commands such as C<dashboard restart> and C<dashboard stop>.

=head1 METHODS

=head2 new, callback, update, finish, render, render_text

Construct and drive one progress board.

=for comment FULL-POD-DOC START

=head1 PURPOSE

This module turns runtime lifecycle events into a visible task list on the terminal so restart and stop do not leave the user staring at a blank prompt while the runtime waits through managed stability windows.

=head1 WHY IT EXISTS

It exists because the restart and stop flows intentionally wait for collectors and the web service to prove they stayed alive or shut down cleanly. Without a dedicated renderer that delay looks like a hang even when the runtime is behaving exactly as...

=head1 WHEN TO USE

Use this file when changing the terminal progress UX for lifecycle commands, when adding new restart or stop tasks that need to appear in the task list, or when adjusting how task boards redraw in interactive shells versus captured non-interactive ru...

=head1 HOW TO USE

Construct the object with a title and the full ordered task list before work begins, then pass the callback into the runtime lifecycle method. The runtime reports task-id and status updates, and this renderer prints the current state of the whole boa...

=head1 WHAT USES IT

It is used by the private restart and stop CLI helpers so interactive terminal runs show visible progress while the runtime manager stops existing processes, starts configured collectors, and confirms the replacement web service.

=head1 EXAMPLES

Example 1:

  perl -Ilib -MDeveloper::Dashboard::CLI::Progress -e '
    my $p = Developer::Dashboard::CLI::Progress->new(
      title => "demo",
      tasks => [ { id => "one", label => "First task" } ],
      dynamic => 0,
    );
    $p->update({ task_id => "one", status => "running" });
    $p->update({ task_id => "one", status => "done" });
  '

Render a non-interactive progress board and drive one task through running and done states.

Example 2:

  DEVELOPER_DASHBOARD_PROGRESS=1 dashboard restart

Force the restart helper to emit the task board even when stdout and stderr are being captured instead of attached to an interactive terminal.

Example 3:

  dashboard restart

Render the interactive lifecycle board with yellow running markers, green
C<[OK]> completion markers, and red C<[X]> failure markers when stderr is a
real terminal.

=cut