view release on metacpan or  search on metacpan

lib/Developer/Dashboard/Runtime/Result.pm  view on Meta::CPAN

    return 'dashboard' if $normalized eq '' || $normalized eq '/' || $normalized eq '\\' || $normalized =~ m{\A[A-Za-z]:[\\/]?\z};

    my $base = basename($normalized);
    return $base if $base ne '' && $base ne '/' && $base ne '\\' && $base ne 'run';

    my $parent = basename( dirname($normalized) );
    return $parent if $parent ne '' && $parent ne '/' && $parent ne '\\';

    my $name = $ENV{DEVELOPER_DASHBOARD_COMMAND} || '';
    return $name if $name ne '';
    return 'dashboard';
}

1;

__END__

=head1 NAME

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

=head1 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();

=head1 DESCRIPTION

This module decodes the hook-result payload populated by C<dashboard> command
hook execution. Small payloads stay inline in C<RESULT>. Oversized payloads
spill into C<RESULT_FILE> before later C<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 C<LAST_RESULT>, and the explicit C<[[STOP]]> marker
contract from Perl hook scripts.

=head1 FUNCTIONS

=head2 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 C<RESULT> or spilled into C<RESULT_FILE>. The same helpers
also manage the immediate previous-hook payload in C<LAST_RESULT> /
C<LAST_RESULT_FILE> and detect the explicit C<[[STOP]]> stderr marker.

=for comment FULL-POD-DOC START

=head1 PURPOSE

This module manages the structured C<RESULT> and C<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 C<RESULT_FILE> or C<LAST_RESULT_FILE> when the
environment would become too large.

=head1 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 C<[[STOP]]> marker, and avoids
argument-list failures when a long hook chain produces too much output for
C<ENV{RESULT}> alone.

=head1 WHEN TO USE

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

=head1 HOW TO USE

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

=head1 WHAT USES IT

It is used by C<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.

=head1 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 C<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.