view release on metacpan or  search on metacpan

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

inventorying and toggling installed skills without deleting their isolated
runtime trees.

=head1 FAQ

=head2 Is this tied to a specific company or codebase?

No. The core distribution is intended to be reusable for any project.

=head2 Where should project-specific behavior live?

In configuration, saved pages, and user CLI extensions. The core should stay generic.

=head2 Is the software spec implemented?

The current distribution implements the core runtime, page engine, action runner, provider loader, prompt and collector system, web lifecycle manager, and Docker Compose resolver described by the software spec.

What remains intentionally lightweight is breadth, not architecture:

- provider pages and action handlers are implemented in a compact v1 form
- bookmark-file pages are supported, with Template Toolkit rendering and one clean sandpit package per page run so C<CODE*> blocks can share state within a bookmark render without leaking runtime globals into later requests

=head2 How is the browser UI served?

The browser UI runs as the dashboard web service you start with
C<dashboard serve>. Internally that service is a PSGI application served
through the shipped web runtime, while CLI-only commands continue to work
without keeping the browser service running.

=head2 Why does a custom hostname sometimes require login?

Only loopback-origin requests with a loopback hostname such as C<127.0.0.1>,
C<::1>, or C<localhost> receive automatic local-admin treatment. A custom alias
hostname also works as local admin when you list it under
C<web.ssl_subject_alt_names> and the request still arrives from loopback.

=head2 Why does a non-loopback host still get 401 without a login page?

Until at least one helper user exists, outsider access is disabled entirely.
That includes non-loopback IPs, forwarded hostnames, and any hostname that is
not loopback-local for the current request. Add a helper user first, then
outsider requests will receive the login page instead of the disabled-access
response.

=head2 Why is the runtime file-backed?

Because prompt rendering, dashboards, and wrappers should consume prepared state quickly instead of re-running expensive checks inline.

=head2 What JSON implementation does the project use?

The project uses C<JSON::XS> for JSON encoding and decoding, including shell helper decoding paths.

=head2 What does the project use for command capture and HTTP clients?

The project uses C<Capture::Tiny> for command-output capture via C<capture>,
with exit codes returned from the capture block rather than read separately.
It uses C<LWP::UserAgent> for real outbound HTTP in active runtime paths such
as the Java source lookup or mirror path behind C<dashboard of> and
C<dashboard open-file>.

=head1 EMBEDDING IN PERL CODE

Perl code that wants the same runtime the C<dashboard>/C<d2> command line
resolves - a configured path alias, or the output of any other subcommand -
does not need to build a path registry, file registry, and config loader by
hand. C<use Developer::Dashboard> exports C<d2()>, a memoized runtime handle
scoped to the current working directory:

    use Developer::Dashboard;

    my $foo = d2->paths->{foo};                    # in-process, no subprocess
    my $out = d2->doctor->();                       # shells to `dashboard doctor`
    my $lst = d2->collector->list->();               # `dashboard collector.list`
    my $res = d2->run( 'tira.ticket.show', '--ref', 'DD-726' );
                                                      # run() takes words separately

C<< d2->paths >> resolves in-process, the same table C<dashboard paths>
prints. Any other bareword method name starts a B<lazy chain> that mirrors
the CLI's own dotted dispatch at arbitrary depth - C<< d2->foo->bar->() >>
runs C<dashboard foo.bar> - and B<nothing executes until the chain is
terminated with a call>, the trailing C<< ->() >>. An un-terminated chain is
inert in boolean, numeric and string context, and stringifies to something
obviously non-executing such as C<d2 proxy: foo.bar>, so a stray debug print
cannot run a command. C<< d2->run(...) >> remains available and takes its
words as separate arguments. Output is decoded from
JSON into a real Perl structure automatically when it looks like JSON,
otherwise returned as plain text; a failing subcommand raises an exception
with its error output attached rather than returning silently as if it had
succeeded.

=head1 SEE ALSO

L</Main Concepts>,
L</Working With Collectors>,
L</Runtime Lifecycle>,
L</Skills System>

=head1 AUTHOR

Developer Dashboard Contributors

=head1 LICENSE

This library is free software; you can redistribute it and/or modify it under
the terms of the MIT license. The repository root C<LICENSE> file carries the
canonical MIT text used for repository metadata, GitHub license detection, and
distribution packaging.

Like most widely used open-source licenses, those license texts include strong
disclaimers. In practical terms the software is provided C<"as is">, no
warranty is given, and the authors are not accepting liability for damages
caused by somebody using the free software wrongly or suffering a problem on
their own side. That license disclaimer is the main baseline protection for
normal open-source distribution, although it is not unlimited and local law
can still matter.

=cut