/ 
Developer-Dashboard-2.20
/ Developer::Dashboard::Runtime::Result

NAME

Developer::Dashboard::Runtime::Result - helper accessors for dashboard hook RESULT JSON

SYNOPSIS

use Developer::Dashboard::Runtime::Result;

my $all    = Developer::Dashboard::Runtime::Result::current();
my $mode   = Developer::Dashboard::Runtime::Result::set_current($all);
my $stdout = Developer::Dashboard::Runtime::Result::stdout('00-first.pl');
my $prev   = Developer::Dashboard::Runtime::Result::last_result();
my $stop   = Developer::Dashboard::Runtime::Result::stop_requested($prev);
my $last   = Developer::Dashboard::Runtime::Result::last_entry();
Developer::Dashboard::Runtime::Result::clear_current();
Developer::Dashboard::Runtime::Result::clear_last_result();

DESCRIPTION

This module decodes the hook-result payload populated by dashboard command hook execution. Small payloads stay inline in RESULT. Oversized payloads spill into RESULT_FILE before later exec() calls would hit the kernel arg/env limit. The helper accessors hide that transport detail and provide one consistent way to read per-hook stdout, stderr, exit codes, the immediate previous hook result in LAST_RESULT, and the explicit [[STOP]] marker contract from Perl hook scripts.

FUNCTIONS

current, set_current, clear_current, last_result, set_last_result, clear_last_result, stop_requested, names, has, entry, stdout, stderr, exit_code, last_name, last_entry, report

Decode, write, clear, and report the current hook-result payload, whether it is stored inline in RESULT or spilled into RESULT_FILE. The same helpers also manage the immediate previous-hook payload in LAST_RESULT / LAST_RESULT_FILE and detect the explicit [[STOP]] stderr marker.

PURPOSE

This module manages the structured RESULT and LAST_RESULT state passed between command hooks and their final command target. It serializes hook stdout, stderr, and exit codes, tracks the immediate previous hook in one stable hash shape, decodes that state for later hooks, and transparently spills oversized payloads into RESULT_FILE or LAST_RESULT_FILE when the environment would become too large.

WHY IT EXISTS

It exists because hook chaining needs a transport format that is explicit and portable. Encoding that state in one module keeps hook readers and writers synchronized, makes the immediate previous-hook handoff predictable, gives the runtime one explicit place to detect the [[STOP]] marker, and avoids argument-list failures when a long hook chain produces too much output for ENV{RESULT} alone.

WHEN TO USE

Use this file when changing hook result serialization, RESULT versus RESULT_FILE overflow rules, LAST_RESULT handoff behavior, or the stop marker/reporting helpers used by command-hook scripts.

HOW TO USE

Use set_current, set_last_result, clear_current, clear_last_result, and the decode/report helpers rather than manipulating ENV{RESULT} or ENV{LAST_RESULT} by hand. Hook scripts should read structured state through this module instead of parsing JSON blobs themselves, and they should use stop_requested when they need to react to the explicit stop marker.

WHAT USES IT

It is used by bin/dashboard command-hook priming, custom CLI hook scripts, update hooks, skill hook dispatch, and tests that cover result overflow, previous-hook chaining, and explicit stop-marker behavior.

EXAMPLES

Example 1:

perl -Ilib -MDeveloper::Dashboard::Runtime::Result -e 1

Do a direct compile-and-load check against the module from a source checkout.

Example 2:

perl -MDeveloper::Dashboard::Runtime::Result -e 'print Developer::Dashboard::Runtime::Result::stop_requested("[[STOP]] from hook\n") ? "stop\n" : "go\n"'

Probe the explicit stop-marker contract directly from one Perl process.

Example 3:

perl -MDeveloper::Dashboard::Runtime::Result -e 'my $last = Developer::Dashboard::Runtime::Result::last_result() || {}; print($last->{file} // "none", "\n")'

Inspect the immediate previous hook payload without parsing ENV{LAST_RESULT} manually.

Example 4:

prove -lv t/21-refactor-coverage.t t/05-cli-smoke.t

Run the focused regression tests that most directly exercise this module's behavior.

Example 5:

HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr t

Recheck the module under the repository coverage gate rather than relying on a load-only probe.

Example 6:

prove -lr t

Put any module-level change back through the entire repository suite before release.