DXBE-20: Add source:config:push command with SAS API client

config/prod/services.yml

@@ -33,6 +33,8 @@ services:
       - ../../src/DataStore/YamlStore.php
       - ../../src/DataStore/JsonDataStore.php
       - ../../src/CloudApi/AccessTokenConnector.php
+      # SourceConfig is instantiated by the command with the SAS client.
+      - ../../src/SasApi/SourceConfig.php
       - ../../src/Command/App/From/**
     public: true
     resource: ../../src
@@ -55,10 +57,23 @@ services:
       - ../../src/Command/Api/ApiBaseCommand.php
       - ../../src/Command/Api/ApiListCommand.php
       - ../../src/Command/Api/ApiListCommandBase.php
+      # The Source config commands inherit from ConfigCommandBase instead.
+      - ../../src/Command/Source/**
       - ../../src/Command/App/From/**
   Acquia\Cli\Command\CommandBase:
     abstract: true
 
+  # Source config commands share a common abstract base (which carries the
+  # same constructor as CommandBase plus the SAS client service).
+  Acquia\Cli\Command\Source\ConfigCommandBase:
+    abstract: true
+    parent: Acquia\Cli\Command\CommandBase
+  Acquia\Cli\Command\Source\:
+    resource: ../../src/Command/Source
+    parent: Acquia\Cli\Command\Source\ConfigCommandBase
+    exclude:
+      - ../../src/Command/Source/ConfigCommandBase.php
+
   Acquia\Cli\EventListener\ExceptionListener:
     tags:
       # @see Symfony\Component\Console\ConsoleEvents
@@ -79,6 +94,9 @@ services:
   acsf.credentials:
     class: Acquia\Cli\AcsfApi\AcsfCredentials
 
+  sas.credentials:
+    class: Acquia\Cli\SasApi\SasCredentials
+
   # AcquiaCloudApi services.
   Acquia\Cli\Command\Api\ApiCommandFactory: ~
   Acquia\Cli\Command\Api\ApiBaseCommand:
@@ -132,6 +150,22 @@ services:
     arguments:
       Acquia\Cli\ApiCredentialsInterface: '@acsf.credentials'
 
+  # Sites Aggregation Service (SAS) API services.
+  # SAS shares the Accounts authentication layer with the Cloud API, so it
+  # reuses the standard cloud credentials; only the base URI differs.
+  Acquia\Cli\SasApi\SasConnectorFactory:
+    arguments:
+      $config:
+        # @see https://symfony.com/doc/current/service_container/expression_language.html
+        key: '@=service("cloud.credentials").getCloudKey()'
+        secret: '@=service("cloud.credentials").getCloudSecret()'
+        accessToken: '@=service("cloud.credentials").getCloudAccessToken()'
+        accessTokenExpiry: '@=service("cloud.credentials").getCloudAccessTokenExpiry()'
+      $baseUri: '@=service("sas.credentials").getBaseUri()'
+      $accountsUri: '@=service("cloud.credentials").getAccountsUri()'
+  Acquia\Cli\SasApi\SasConnector:
+    alias: Acquia\Cli\SasApi\SasConnectorFactory
+
   # Symfony services.
   Acquia\Cli\Application:
       arguments:

src/Command/Source/ConfigCommandBase.php

@@ -0,0 +1,171 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Acquia\Cli\Command\Source;
+
+use Acquia\Cli\ApiCredentialsInterface;
+use Acquia\Cli\CloudApi\ClientService;
+use Acquia\Cli\Command\CommandBase;
+use Acquia\Cli\DataStore\AcquiaCliDatastore;
+use Acquia\Cli\DataStore\CloudDataStore;
+use Acquia\Cli\Exception\AcquiaCliException;
+use Acquia\Cli\Helpers\LocalMachineHelper;
+use Acquia\Cli\Helpers\LoopHelper;
+use Acquia\Cli\Helpers\SshHelper;
+use Acquia\Cli\Helpers\TelemetryHelper;
+use Acquia\Cli\SasApi\SasClientService;
+use Acquia\Cli\SasApi\SourceConfig;
+use Psr\Log\LoggerInterface;
+use SelfUpdate\SelfUpdateManager;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Base class for Source config commands.
+ *
+ * Both directions are thin triggers over the SAS API: they ask SAS to run a
+ * `drush source:config:*` command on the environment. Push (import) reads
+ * config from the site's git repository into the CMS; pull (export) does the
+ * reverse and returns the exported config for the command to write to disk.
+ * No push payload travels through these commands.
+ */
+abstract class ConfigCommandBase extends CommandBase
+{
+    public function __construct(
+        LocalMachineHelper $localMachineHelper,
+        CloudDataStore $datastoreCloud,
+        AcquiaCliDatastore $datastoreAcli,
+        ApiCredentialsInterface $cloudCredentials,
+        TelemetryHelper $telemetryHelper,
+        string $projectDir,
+        ClientService $cloudApiClientService,
+        SshHelper $sshHelper,
+        string $sshDir,
+        LoggerInterface $logger,
+        SelfUpdateManager $selfUpdateManager,
+        private readonly SasClientService $sasClient,
+    ) {
+        parent::__construct(
+            $localMachineHelper,
+            $datastoreCloud,
+            $datastoreAcli,
+            $cloudCredentials,
+            $telemetryHelper,
+            $projectDir,
+            $cloudApiClientService,
+            $sshHelper,
+            $sshDir,
+            $logger,
+            $selfUpdateManager,
+        );
+    }
+
+    protected function configure(): void
+    {
+        $this
+            ->acceptEnvironmentId()
+            ->acceptSiteInstanceId()
+            ->addOption('force', 'f', InputOption::VALUE_NONE, 'Do not ask for confirmation');
+    }
+
+    /**
+     * Trigger the config operation on the environment and return the decoded response.
+     */
+    abstract protected function triggerOperation(SourceConfig $sourceConfig, string $environmentId): object;
+
+    /**
+     * A short verb phrase describing the operation, e.g. "Importing configuration".
+     */
+    abstract protected function operationLabel(): string;
+
+    /**
+     * Handle a successfully completed operation.
+     *
+     * The default does nothing (push). Pull overrides this to fetch the
+     * exported payload and write it to disk.
+     *
+     * @infection-ignore-all ProtectedVisibility mutates this to private, which
+     *   is killed by the pull command overriding it, but Infection does not
+     *   attribute the subclass test's coverage back to this base declaration.
+     */
+    protected function onSuccess(SourceConfig $sourceConfig, string $operationId): int
+    {
+        $this->io->success($this->operationLabel() . ' completed successfully.');
+
+        return Command::SUCCESS;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->setDirAndRequireProjectCwd($input);
+
+        $siteInstance = $this->determineSiteInstance($input);
+        if ($siteInstance === null) {
+            throw new AcquiaCliException(
+                'Could not determine a Source site instance. Run this command from a repository linked to an Acquia Cloud application, or pass --siteInstanceId.'
+            );
+        }
+
+        $environment = $siteInstance->environment;
+
+        if (!$input->getOption('force')) {
+            $answer = $this->io->confirm(
+                sprintf('%s on the %s environment?', $this->operationLabel(), $environment->name),
+                false,
+            );
+            if (!$answer) {
+                return Command::SUCCESS;
+            }
+        }
+
+        $sourceConfig = new SourceConfig($this->sasClient->getClient());
+
+        $response = $this->triggerOperation($sourceConfig, $environment->id);
+        // @todo DXBE-20: Confirm the operation ID field name with the SAS team.
+        $operationId = $response->id ?? null;
+        if (!is_string($operationId)) {
+            throw new AcquiaCliException('The SAS API response did not include an operation ID.');
+        }
+
+        $this->io->writeln(sprintf('%s submitted (operation %s). Waiting for it to complete...', $this->operationLabel(), $operationId));
+
+        if (!$this->waitForOperation($sourceConfig, $operationId)) {
+            return Command::FAILURE;
+        }
+
+        return $this->onSuccess($sourceConfig, $operationId);
+    }
+
+    /**
+     * Poll the operation until it leaves the in-progress states.
+     *
+     * @todo DXBE-20: Confirm the status field name and its values with the
+     *   SAS team. Assumes a `status` field mirroring the task gateway's
+     *   phases (pending/running/succeeded/failed).
+     */
+    private function waitForOperation(SourceConfig $sourceConfig, string $operationId): bool
+    {
+        $status = null;
+        $checkStatus = static function () use ($sourceConfig, $operationId, &$status): bool {
+            $response = $sourceConfig->getStatus($operationId);
+            $status = $response->status ?? 'unknown';
+            return !in_array($status, ['pending', 'running'], true);
+        };
+        $onDone = static function (): void {
+        };
+
+        // @infection-ignore-all The spinner message is transient (overwritten
+        // as the spinner advances) and never appears in the captured output,
+        // so its concatenation cannot be asserted by a test.
+        LoopHelper::getLoopy($this->output, $this->io, $this->operationLabel() . '...', $checkStatus, $onDone);
+
+        if ($status !== 'succeeded') {
+            $this->io->error(sprintf('%s ended with status: %s', $this->operationLabel(), $status));
+        }
+
+        return $status === 'succeeded';
+    }
+}

src/Command/Source/ConfigPullCommand.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Acquia\Cli\Command\Source;
+
+use Acquia\Cli\Attribute\RequireAuth;
+use Acquia\Cli\Exception\AcquiaCliException;
+use Acquia\Cli\SasApi\SourceConfig;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Filesystem\Filesystem;
+use Symfony\Component\Yaml\Yaml;
+
+/**
+ * Trigger a Source config export on a site via the Sites Aggregation Service.
+ *
+ * Asks SAS to run a config export on the environment, which exports config
+ * from the CMS. The exported config comes back as a single YAML document keyed
+ * by collection, then config name; this command writes it out to
+ * .acquia/config/ as individual files, replacing whatever is there.
+ */
+#[RequireAuth]
+#[AsCommand(name: 'source:config:pull', description: 'Export Source configuration from a site')]
+final class ConfigPullCommand extends ConfigCommandBase
+{
+    /**
+     * The directory (relative to the project root) config is written to.
+     */
+    private const CONFIG_DIR = '.acquia/config';
+
+    /**
+     * The inline depth and indentation for dumped config YAML.
+     *
+     * @infection-ignore-all Increment/DecrementInteger on the depth is not
+     *   observable: any depth beyond the config's actual nesting produces
+     *   identical output, and the indent behavior is covered by the nested
+     *   structure test. The values only need to be "deep enough".
+     */
+    private const DUMP_DEPTH = 10;
+
+    private const DUMP_INDENT = 2;
+
+    protected function triggerOperation(SourceConfig $sourceConfig, string $environmentId): object
+    {
+        return $sourceConfig->pull($environmentId);
+    }
+
+    protected function operationLabel(): string
+    {
+        return 'Exporting configuration';
+    }
+
+    /**
+     * Fetch the exported payload and write it to .acquia/config/.
+     *
+     * The directory is wiped and rewritten so the local files mirror the
+     * remote state exactly — config removed in the CMS disappears locally too.
+     */
+    protected function onSuccess(SourceConfig $sourceConfig, string $operationId): int
+    {
+        $yaml = $sourceConfig->getExportPayload($operationId);
+        $payload = Yaml::parse($yaml);
+
+        if (!is_array($payload)) {
+            throw new AcquiaCliException('The SAS API returned an invalid config payload.');
+        }
+
+        $this->writePayload($payload);
+
+        $this->io->success(sprintf('Configuration exported to %s.', self::CONFIG_DIR));
+
+        return Command::SUCCESS;
+    }
+
+    /**
+     * Wipe and rewrite .acquia/config/ from the payload.
+     *
+     * The payload maps collection names to config items. The default
+     * collection ("") writes to the config root; other collections write to
+     * dotted subdirectories (language.es becomes language/es).
+     *
+     * @param array<string, array<string, mixed>> $payload
+     */
+    private function writePayload(array $payload): void
+    {
+        $configDir = $this->dir . '/' . self::CONFIG_DIR;
+        $filesystem = new Filesystem();
+
+        // Wipe the directory so the local files mirror the remote state.
+        $filesystem->remove($configDir);
+        $filesystem->mkdir($configDir);
+
+        foreach ($payload as $collection => $items) {
+            if (!is_array($items)) {
+                continue;
+            }
+            // The default collection ("") is the config root; other collections
+            // map their dotted name to a subdirectory (language.es -> language/es).
+            $collectionDir = $collection === ''
+                ? $configDir
+                : $configDir . '/' . str_replace('.', '/', $collection);
+
+            foreach ($items as $name => $values) {
+                $filesystem->dumpFile(
+                    sprintf('%s/%s.yml', $collectionDir, $name),
+                    Yaml::dump($values, self::DUMP_DEPTH, self::DUMP_INDENT),
+                );
+            }
+        }
+    }
+}

src/Command/Source/ConfigPushCommand.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Acquia\Cli\Command\Source;
+
+use Acquia\Cli\Attribute\RequireAuth;
+use Acquia\Cli\SasApi\SourceConfig;
+use Symfony\Component\Console\Attribute\AsCommand;
+
+/**
+ * Trigger a Source config import on a site via the Sites Aggregation Service.
+ *
+ * Asks SAS to run `drush source:config:import` on the environment, which
+ * reads config from the site's git repository and applies it to the CMS.
+ */
+#[RequireAuth]
+#[AsCommand(name: 'source:config:push', description: 'Import deployed Source configuration on a site')]
+final class ConfigPushCommand extends ConfigCommandBase
+{
+    protected function triggerOperation(SourceConfig $sourceConfig, string $environmentId): object
+    {
+        return $sourceConfig->push($environmentId);
+    }
+
+    protected function operationLabel(): string
+    {
+        return 'Importing configuration';
+    }
+}

src/SasApi/SasClient.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Acquia\Cli\SasApi;
+
+use AcquiaCloudApi\Connector\Client;
+
+/**
+ * Client for the Sites Aggregation Service (SAS) API.
+ *
+ * Response processing is inherited unchanged from the Cloud API client.
+ */
+class SasClient extends Client
+{
+}