[FEATURE] Introduce command to create local extension artefact

* [FEATURE] Introduce command to create local extension artefact

This commit adds a new `create-artefact` command. It can be used
to create a local artefact file (zip archive) of an extension. This
is basically the same which is already done in the `ter:publish`
command, except for the TER publish part.

The new command is especially useful to test custom configurations
of package exclude files. In addition, it's a useful helper in
cases where the TER REST API might not be accessible.

* [TASK] Use different transaction path for `create-artefact` command

* [TASK] Include transaction path in exception message

* [TASK] Drop AbstractCommand in favor of CommandHelper utility class

* [TASK] Use admonitions and create custom section for packaging excludes

bin/tailor

@@ -36,6 +36,7 @@ foreach ([__DIR__ . '/../vendor/autoload.php', __DIR__ . '/../../../autoload.php
     $application->add(new Command\Auth\CreateTokenCommand('ter:token:create'));
     $application->add(new Command\Auth\RefreshTokenCommand('ter:token:refresh'));
     $application->add(new Command\Auth\RevokeTokenCommand('ter:token:revoke'));
+    $application->add(new Command\Extension\CreateExtensionArtefactCommand('create-artefact'));
     $application->add(new Command\Extension\DeleteExtensionCommand('ter:delete'));
     $application->add(new Command\Extension\ExtensionDetailsCommand('ter:details'));
     $application->add(new Command\Extension\ExtensionVersionsCommand('ter:versions'));

conf/ExcludeFromPackaging.php

@@ -21,6 +21,7 @@
         'bin',
         'build',
         'public',
+        'tailor-version-artefact',
         'tailor-version-upload',
         'tests',
         'tools',

src/Command/AbstractClientRequestCommand.php

@@ -20,9 +20,6 @@
 use Symfony\Component\Console\Style\SymfonyStyle;
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
-use TYPO3\Tailor\Environment\Variables;
-use TYPO3\Tailor\Exception\ExtensionKeyMissingException;
-use TYPO3\Tailor\Filesystem\ComposerReader;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
 use TYPO3\Tailor\HttpClientFactory;
 use TYPO3\Tailor\Service\RequestService;
@@ -95,26 +92,6 @@ protected function setConfirmationRequired(bool $confirmationRequired): self
         return $this;
     }
 
-    protected function getExtensionKey(InputInterface $input): string
-    {
-        if ($input->hasArgument('extensionkey')
-            && ($key = ($input->getArgument('extensionkey') ?? '')) !== ''
-        ) {
-            $extensionKey = $key;
-        } elseif (Variables::has('TYPO3_EXTENSION_KEY')) {
-            $extensionKey = Variables::get('TYPO3_EXTENSION_KEY');
-        } elseif (($extensionKeyFromComposer = (new ComposerReader())->getExtensionKey()) !== '') {
-            $extensionKey = $extensionKeyFromComposer;
-        } else {
-            throw new ExtensionKeyMissingException(
-                'The extension key must either be set as argument, as environment variable or in the composer.json.',
-                1605706548
-            );
-        }
-
-        return $extensionKey;
-    }
-
     abstract protected function getRequestConfiguration(): RequestConfiguration;
     abstract protected function getMessages(): Messages;
 }

src/Command/Extension/CreateExtensionArtefactCommand.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 project - inspiring people to share!
+ * (c) 2020-2023 Oliver Bartsch, Benni Mack & Elias Häußler
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace TYPO3\Tailor\Command\Extension;
+
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+use TYPO3\Tailor\Filesystem;
+use TYPO3\Tailor\Helper\CommandHelper;
+use TYPO3\Tailor\Service\VersionService;
+
+/**
+ * Command to create a local extension artefact (zip archive).
+ */
+class CreateExtensionArtefactCommand extends Command
+{
+    protected function configure(): void
+    {
+        $this->setDescription('Create an artefact file (zip archive) of an extension');
+
+        $this->addArgument(
+            'version',
+            InputArgument::REQUIRED,
+            'The version of the extension, e.g. 1.2.3'
+        );
+        $this->addArgument(
+            'extensionkey',
+            InputArgument::OPTIONAL,
+            'The extension key'
+        );
+        $this->addOption(
+            'path',
+            null,
+            InputOption::VALUE_REQUIRED,
+            'Path to the extension folder'
+        );
+        $this->addOption(
+            'artefact',
+            null,
+            InputOption::VALUE_REQUIRED,
+            'Path or URL to a zip file'
+        );
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $io = new SymfonyStyle($input, $output);
+
+        $version = $input->getArgument('version');
+        $extensionKey = CommandHelper::getExtensionKeyFromInput($input);
+        $path = $input->getOption('path');
+        $artefact = $input->getOption('artefact');
+        $transactionPath = rtrim(realpath(getcwd() ?: './'), '/') . '/tailor-version-artefact';
+
+        if (!(new Filesystem\Directory())->create($transactionPath)) {
+            throw new \RuntimeException(sprintf('Directory could not be created: %s', $transactionPath));
+        }
+
+        $versionService = new VersionService($version, $extensionKey, $transactionPath);
+
+        if ($path !== null) {
+            $versionService->createZipArchiveFromPath($path);
+        } elseif ($artefact !== null) {
+            $versionService->createZipArchiveFromArtefact($artefact);
+        } else {
+            // If neither `path` nor `artefact` are defined, we just
+            // create the ZipArchive from the current directory.
+            $versionService->createZipArchiveFromPath(getcwd() ?: './');
+        }
+
+        $io->success(sprintf('Extension artefact successfully generated: %s', $versionService->getVersionFilePath()));
+
+        return 0;
+    }
+}

src/Command/Extension/DeleteExtensionCommand.php

@@ -19,6 +19,7 @@
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `DELETE /extension/{key}`
@@ -40,7 +41,7 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         return parent::execute($input, $output);
     }
 

src/Command/Extension/ExtensionDetailsCommand.php

@@ -19,6 +19,7 @@
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `GET /extension/{key}`
@@ -39,7 +40,7 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         return parent::execute($input, $output);
     }
 

src/Command/Extension/ExtensionVersionsCommand.php

@@ -19,6 +19,7 @@
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `GET /extension/{key}/versions`
@@ -39,7 +40,7 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         // @todo the response format needs to be adjusted!
         return parent::execute($input, $output);
     }

src/Command/Extension/RegisterExtensionCommand.php

@@ -18,6 +18,7 @@
 use TYPO3\Tailor\Command\AbstractClientRequestCommand;
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `POST /extension/{key}`
@@ -37,7 +38,7 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         return parent::execute($input, $output);
     }
 

src/Command/Extension/TransferExtensionCommand.php

@@ -18,6 +18,7 @@
 use TYPO3\Tailor\Command\AbstractClientRequestCommand;
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `POST /extension/{key}/transfer/{username}`
@@ -43,7 +44,7 @@ protected function configure(): void
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $this->username = $input->getArgument('username');
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         return parent::execute($input, $output);
     }
 

src/Command/Extension/UpdateExtensionCommand.php

@@ -20,6 +20,7 @@
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `PUT /extension/{key}`
@@ -55,7 +56,7 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         return parent::execute($input, $output);
     }
 

src/Command/Extension/UploadExtensionVersionCommand.php

@@ -23,6 +23,7 @@
 use TYPO3\Tailor\Dto\RequestConfiguration;
 use TYPO3\Tailor\Filesystem;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
+use TYPO3\Tailor\Helper\CommandHelper;
 use TYPO3\Tailor\Service\VersionService;
 
 /**
@@ -56,7 +57,7 @@ protected function configure(): void
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $this->version = $input->getArgument('version');
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         $this->transactionPath = rtrim(realpath(getcwd() ?: './'), '/') . '/tailor-version-upload';
 
         if (!(new Filesystem\Directory())->create($this->transactionPath)) {

src/Command/Extension/VersionDetailsCommand.php

@@ -19,6 +19,7 @@
 use TYPO3\Tailor\Dto\Messages;
 use TYPO3\Tailor\Dto\RequestConfiguration;
 use TYPO3\Tailor\Formatter\ConsoleFormatter;
+use TYPO3\Tailor\Helper\CommandHelper;
 
 /**
  * Command for TER REST endpoint `GET /extension/{key}/{version}`
@@ -44,7 +45,7 @@ protected function configure(): void
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $this->version = $input->getArgument('version');
-        $this->extensionKey = $this->getExtensionKey($input);
+        $this->extensionKey = CommandHelper::getExtensionKeyFromInput($input);
         return parent::execute($input, $output);
     }
 

src/Helper/CommandHelper.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 project - inspiring people to share!
+ * (c) 2020-2024 Oliver Bartsch, Benni Mack & Elias Häußler
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace TYPO3\Tailor\Helper;
+
+use Symfony\Component\Console\Input\InputInterface;
+use TYPO3\Tailor\Environment\Variables;
+use TYPO3\Tailor\Exception\ExtensionKeyMissingException;
+use TYPO3\Tailor\Filesystem\ComposerReader;
+
+/**
+ * Helper class for console commands.
+ */
+final class CommandHelper
+{
+    public static function getExtensionKeyFromInput(InputInterface $input): string
+    {
+        if ($input->hasArgument('extensionkey')
+            && ($key = ($input->getArgument('extensionkey') ?? '')) !== ''
+        ) {
+            $extensionKey = $key;
+        } elseif (Variables::has('TYPO3_EXTENSION_KEY')) {
+            $extensionKey = Variables::get('TYPO3_EXTENSION_KEY');
+        } elseif (($extensionKeyFromComposer = (new ComposerReader())->getExtensionKey()) !== '') {
+            $extensionKey = $extensionKeyFromComposer;
+        } else {
+            throw new ExtensionKeyMissingException(
+                'The extension key must either be set as argument, as environment variable or in the composer.json.',
+                1605706548
+            );
+        }
+
+        return $extensionKey;
+    }
+}