NAME

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

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;

DESCRIPTION

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

METHODS

new, callback, update, finish, render, render_text

Construct and drive one progress board.

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.

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 designed.

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 runs.

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 board to the configured stream.

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.

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 [OK] completion markers, and red [X] failure markers when stderr is a real terminal.