/ 
Developer-Dashboard-4.45
/ Developer::Dashboard::Pax::CLI::Progress

NAME

Developer::Dashboard::Pax::CLI::Progress - DD-style terminal task board for long-running PAX CLI work

SYNOPSIS

my $progress = Developer::Dashboard::Pax::CLI::Progress->new(
    title => 'pax build progress',
    tasks => [
        { id => 'compile_code_units', label => 'Compile Perl code units' },
        { id => 'compile_launcher',   label => 'Compile standalone launcher' },
    ],
    stream  => \*STDERR,
    dynamic => 1,
    color   => 1,
);

my $callback = $progress->callback;
$callback->({ task_id => 'compile_code_units', status => 'running' });
$callback->({ task_id => 'compile_code_units', status => 'done' });
$progress->finish;

DESCRIPTION

This module renders the same style of ordered task rundown used by Developer Dashboard lifecycle and skill-install commands. PAX uses it for long-running CLI work such as pax build so operators can see phase-level progress on stderr while structured results stay on stdout.

METHODS

new, callback, update, finish, render, render_text

Construct and drive one task board.

USE

Use this module when a public PAX CLI command takes long enough that operators need visible phase progress without losing machine-readable command output.

PURPOSE

This module keeps build-progress rendering separate from command parsing and build planning so long-running CLI work can report useful progress without tangling presentation logic into the compiler and packaging code.

WHY IT EXISTS

pax build can take a real, noticeable amount of wall-clock time (source discovery, entrypoint compilation, dependency compilation, native artifact emission), and PAX's own CLI contract requires machine-readable results to stay on stdout while progress is purely cosmetic. Without a dedicated renderer, either progress output would contaminate the structured stdout payload (breaking any caller parsing it as JSON) or operators would get no feedback at all during a multi-second build. This module solves both by writing exclusively to a configurable stream (stderr by default) and redrawing in place when dynamic is set.

WHEN TO USE

Edit this file when adding a new task-status style (beyond pending, running, done, failed), when the redraw/clear-line escape sequence logic needs to change for a different terminal target, or when a new PAX CLI command needs the same phase-rundown presentation pax build already uses.

HOW TO USE

Construct with a title and an ordered tasks array (each needing an id, optionally a label); this renders the initial board immediately. Get a callback via callback and pass it into whatever PAX pipeline stage emits progress events shaped { task_id => ..., status => ... }; each event triggers a re-render. Call finish once the whole task board is done so the terminal cursor is left on a fresh line.

WHAT USES IT

The public pax build flow uses this module for the DD-style progress rundown shown on stderr.

EXAMPLES

Example 1:

my $progress = Developer::Dashboard::Pax::CLI::Progress->new(
    title => 'pax build progress',
    tasks => [ { id => 'compile', label => 'Compile entrypoint' } ],
);
$progress->callback->({ task_id => 'compile', status => 'done' });
$progress->finish;

Example 2:

# PAX_PROGRESS=0 disables the rundown entirely (t/183 exercises this);
# this module is simply not constructed in that mode.
local $ENV{PAX_PROGRESS} = 0;