view release on metacpan or  search on metacpan

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

        %$resolved,
        stdout    => $stdout,
        stderr    => $stderr,
        exit_code => $exit_code,
    };
}

# _discover_base_files($root)
# Finds standard base compose files under a project root.
# Input: project root directory path.
# Output: ordered list of existing compose file paths.
sub _discover_base_files {
    my ( $self, $root ) = @_;
    my @candidates = qw(compose.yml compose.yaml docker-compose.yml docker-compose.yaml);
    return grep { -f $_ } map { File::Spec->catfile( $root, $_ ) } @candidates;
}

# _service_disabled_marker_path(%args)
# Resolves the disabled.yml marker path in the deepest runtime docker root for one isolated service.
# Input: service name and optional project_root.
# Output: absolute disabled.yml marker file path string.
sub _service_disabled_marker_path {
    my ( $self, %args ) = @_;
    my $service = $args{service} || die 'Missing service';
    my $root = $self->_service_toggle_root(%args);
    return File::Spec->catfile( $root, $service, 'disabled.yml' );
}

# _service_toggle_root(%args)
# Returns the deepest participating docker root where isolated-service toggle markers should be written.
# Input: optional project_root.
# Output: absolute docker root directory path string.
sub _service_toggle_root {
    my ( $self, %args ) = @_;
    my @layers = $self->{paths}->runtime_layers;
    my $runtime_root = @layers ? $layers[-1] : $self->{paths}->home_runtime_root;
    my $home_runtime_root = $self->{paths}->home_runtime_root;
    return $runtime_root eq $home_runtime_root
      ? File::Spec->catdir( $runtime_root, 'config', 'docker' )
      : File::Spec->catdir( $runtime_root, 'docker' );
}

1;

__END__

=head1 NAME

Developer::Dashboard::DockerCompose - compose resolver and launcher

=head1 SYNOPSIS

  my $docker = Developer::Dashboard::DockerCompose->new(
      config  => $config,
      paths   => $paths,
      plugins => $plugins,
  );

=head1 DESCRIPTION

This module resolves layered docker compose inputs into a final transparent
docker compose command line and can optionally execute it.

=head1 METHODS

=head2 new, resolve, list_services, run

Construct, resolve, list, and optionally execute compose operations.

=for comment FULL-POD-DOC START

=head1 PURPOSE

This module resolves and runs dashboard-managed Docker Compose stacks. It maps wrapper flags to compose files under layered runtime config roots, infers service names, exports the effective docker config root, and builds the final C<docker compose> c...

=head1 WHY IT EXISTS

It exists because dashboard-specific Compose resolution has more rules than a plain passthrough wrapper: isolated service folders, disabled markers, addon/mode selection, and layered runtime lookup all need one tested owner.

=head1 WHEN TO USE

Use this file when changing compose file discovery, wrapper-only flags, service inference, environment exports such as C<DDDC>, or the dry-run versus exec behavior of the docker helper.

=head1 HOW TO USE

Feed the parsed wrapper arguments into this module and let it return or execute the effective docker compose command. Avoid rebuilding compose discovery logic in the CLI wrapper or in project-local scripts.

=head1 WHAT USES IT

It is used by the C<dashboard docker compose> helper, by docker-focused tests, and by developers who keep Compose stacks under F<.developer-dashboard/config/docker/> instead of shell aliases.

=head1 EXAMPLES

Example 1:

  perl -Ilib -MDeveloper::Dashboard::DockerCompose -e 1

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

Example 2:

  prove -lv t/10-extension-action-docker.t

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

Example 3:

  dashboard docker list --disabled

Inspect the effective disabled-service view through the same resolver rules as
compose discovery.

Example 4:

  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 4:

  prove -lr t