Moved several methods out of the installer command class. (#2308)

Author: AlexSkrypnyk

.vortex/installer/src/Command/InstallCommand.php

@@ -0,0 +1,274 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\VortexInstaller\Prompts;
+
+use DrevOps\VortexInstaller\Downloader\Artifact;
+use DrevOps\VortexInstaller\Prompts\Handlers\Starter;
+use DrevOps\VortexInstaller\Utils\Config;
+use DrevOps\VortexInstaller\Utils\Strings;
+use DrevOps\VortexInstaller\Utils\Tui;
+
+/**
+ * Presents installer headers, footers, and post-build messages.
+ *
+ * @package DrevOps\VortexInstaller\Prompts
+ */
+class InstallerPresenter {
+
+  const BUILD_RESULT_SUCCESS = 'success';
+
+  const BUILD_RESULT_SKIPPED = 'skipped';
+
+  const BUILD_RESULT_FAILED = 'failed';
+
+  /**
+   * The prompt manager.
+   */
+  protected ?PromptManager $promptManager = NULL;
+
+  public function __construct(
+    protected Config $config,
+  ) {}
+
+  public function setPromptManager(PromptManager $prompt_manager): void {
+    $this->promptManager = $prompt_manager;
+  }
+
+  public function header(Artifact $artifact, string $version): void {
+    $logo_large = <<<EOT
+
+██╗   ██╗  ██████╗  ██████╗  ████████╗ ███████╗ ██╗  ██╗
+██║   ██║ ██╔═══██╗ ██╔══██╗ ╚══██╔══╝ ██╔════╝ ╚██╗██╔╝
+██║   ██║ ██║   ██║ ██████╔╝    ██║    █████╗    ╚███╔╝
+╚██╗ ██╔╝ ██║   ██║ ██╔══██╗    ██║    ██╔══╝    ██╔██╗
+ ╚████╔╝  ╚██████╔╝ ██║  ██║    ██║    ███████╗ ██╔╝ ██╗
+  ╚═══╝    ╚═════╝  ╚═╝  ╚═╝    ╚═╝    ╚══════╝ ╚═╝  ╚═╝
+
+               Drupal project template
+
+                                              by DrevOps
+EOT;
+
+    $logo_small = <<<EOT
+▗▖  ▗▖ ▗▄▖ ▗▄▄▖▗▄▄▄▖▗▄▄▄▖▗▖  ▗▖
+▐▌  ▐▌▐▌ ▐▌▐▌ ▐▌ █  ▐▌    ▝▚▞▘
+▐▌  ▐▌▐▌ ▐▌▐▛▀▚▖ █  ▐▛▀▀▘  ▐▌
+ ▝▚▞▘ ▝▚▄▞▘▐▌ ▐▌ █  ▐▙▄▄▖▗▞▘▝▚▖
+
+   Drupal project template
+
+                     by DrevOps
+EOT;
+
+    $max_header_width = 200;
+
+    $logo = Tui::terminalWidth() >= 80 ? $logo_large : $logo_small;
+    $logo = Tui::center($logo, Tui::terminalWidth($max_header_width), '─');
+    $logo = Tui::cyan($logo);
+
+    // Depending on how the installer is run, the version may be set to
+    // the placeholder value or actual version (PHAR packager will replace
+    // the placeholder with the actual version).
+    // We need to fence the replacement below only if the version is still set
+    // to the placeholder value.
+    if (str_contains($version, 'vortex-installer-version')) {
+      $version = str_replace('@vortex-installer-version@', 'development', $version);
+    }
+
+    $logo .= PHP_EOL . Tui::dim(str_pad(sprintf('Installer version: %s', $version), Tui::terminalWidth($max_header_width) - 2, ' ', STR_PAD_LEFT));
+
+    Tui::note($logo);
+
+    $title = 'Welcome to the Vortex interactive installer';
+    $content = '';
+
+    if ($artifact->isStable()) {
+      $content .= 'This tool will guide you through installing the latest ' . Tui::underscore('stable') . ' version of Vortex into your project.' . PHP_EOL;
+    }
+    elseif ($artifact->isDevelopment()) {
+      $content .= 'This tool will guide you through installing the latest ' . Tui::underscore('development') . ' version of Vortex into your project.' . PHP_EOL;
+    }
+    else {
+      $content .= sprintf('This tool will guide you through installing a ' . Tui::underscore('custom') . ' version of Vortex into your project at commit "%s".', $artifact->getRef()) . PHP_EOL;
+    }
+
+    $content .= PHP_EOL;
+
+    if ($this->config->isVortexProject()) {
+      $content .= 'It looks like Vortex is already installed into this project.' . PHP_EOL;
+      $content .= PHP_EOL;
+    }
+
+    if ($this->config->getNoInteraction()) {
+      $content .= 'Vortex installer will try to discover the settings from the environment and will install configuration relevant to your site.' . PHP_EOL;
+      $content .= PHP_EOL;
+      $content .= 'Existing committed files may be modified. You may need to resolve some of the changes manually.' . PHP_EOL;
+
+      $title = 'Welcome to the Vortex non-interactive installer';
+    }
+    else {
+      $content .= 'You will be asked a few questions to tailor the configuration to your site.' . PHP_EOL;
+      $content .= 'No changes will be made until you confirm everything at the end.' . PHP_EOL;
+      $content .= PHP_EOL;
+
+      if ($this->config->isVortexProject()) {
+        $content .= 'If you proceed, some committed files may be modified after confirmation, and you may need to resolve some of the changes manually.' . PHP_EOL;
+        $content .= PHP_EOL;
+      }
+
+      $content .= 'Press ' . Tui::yellow('Ctrl+C') . ' at any time to exit the installer.' . PHP_EOL;
+      $content .= 'Press ' . Tui::yellow('Ctrl+U') . ' at any time to go back to the previous step.' . PHP_EOL;
+    }
+
+    Tui::box($content, $title);
+  }
+
+  public function footer(): void {
+    $output = '';
+    $prefix = '  ';
+
+    if ($this->config->isVortexProject()) {
+      $title = 'Finished updating Vortex';
+      $output .= 'Please review the changes and commit the required files.';
+    }
+    else {
+      $title = 'Finished installing Vortex';
+
+      // Check for required tools and provide conditional instructions.
+      $missing_tools = $this->checkRequiredTools();
+      if (!empty($missing_tools)) {
+        $tools_output = 'Install required tools:' . PHP_EOL;
+        foreach ($missing_tools as $tool => $instructions) {
+          $tools_output .= sprintf('  %s: %s', $tool, $instructions) . PHP_EOL;
+        }
+        $output .= Strings::wrapLines($tools_output, $prefix);
+        $output .= PHP_EOL;
+      }
+
+      $output .= 'Add and commit all files:' . PHP_EOL;
+      $output .= $prefix . 'git add -A' . PHP_EOL;
+      $output .= $prefix . 'git commit -m "Initial commit."' . PHP_EOL;
+    }
+
+    Tui::box($output, $title);
+  }
+
+  /**
+   * Display footer after build succeeded.
+   */
+  public function footerBuildSucceeded(): void {
+    $output = '';
+
+    $output .= 'Get site info: ahoy info' . PHP_EOL;
+    $output .= 'Login:         ahoy login' . PHP_EOL;
+    $output .= PHP_EOL;
+
+    $handler_output = $this->promptManager->runPostBuild(self::BUILD_RESULT_SUCCESS);
+    if (!empty($handler_output)) {
+      $output .= $handler_output;
+    }
+
+    Tui::box($output, 'Site is ready');
+  }
+
+  /**
+   * Display footer after build was skipped.
+   */
+  public function footerBuildSkipped(): void {
+    $output = '';
+    $prefix = '  ';
+
+    $responses = $this->promptManager->getResponses();
+    $starter = $responses[Starter::id()] ?? Starter::LOAD_DATABASE_DEMO;
+    $is_profile = in_array($starter, [Starter::INSTALL_PROFILE_CORE, Starter::INSTALL_PROFILE_DRUPALCMS], TRUE);
+
+    $output .= 'Build the site:' . PHP_EOL;
+    if ($is_profile) {
+      $output .= $prefix . 'VORTEX_PROVISION_TYPE=profile ahoy build' . PHP_EOL;
+    }
+    else {
+      $output .= $prefix . 'ahoy build' . PHP_EOL;
+    }
+    $output .= PHP_EOL;
+
+    if ($is_profile) {
+      $output .= 'Export database after build:' . PHP_EOL;
+      $output .= $prefix . 'ahoy export-db db.sql' . PHP_EOL;
+      $output .= PHP_EOL;
+    }
+
+    $handler_output = $this->promptManager->runPostBuild(self::BUILD_RESULT_SKIPPED);
+    if (!empty($handler_output)) {
+      $output .= $handler_output;
+    }
+
+    Tui::box($output, 'Ready to build');
+  }
+
+  /**
+   * Display footer after build failed.
+   */
+  public function footerBuildFailed(): void {
+    $output = '';
+    $prefix = '  ';
+
+    $output .= 'Vortex was installed, but the build process failed.' . PHP_EOL;
+    $output .= PHP_EOL;
+    $output .= 'Troubleshooting:' . PHP_EOL;
+    $output .= $prefix . 'Check logs:' . $prefix . $prefix . 'ahoy logs' . PHP_EOL;
+    $output .= $prefix . 'Retry build:' . $prefix . 'ahoy build' . PHP_EOL;
+    $output .= $prefix . 'Diagnostics:' . $prefix . 'ahoy doctor' . PHP_EOL;
+    $output .= PHP_EOL;
+
+    $handler_output = $this->promptManager->runPostBuild(self::BUILD_RESULT_FAILED);
+    if (!empty($handler_output)) {
+      $output .= $handler_output;
+    }
+
+    Tui::box($output, 'Build encountered errors');
+  }
+
+  /**
+   * Check for required development tools.
+   *
+   * @return array<string, string>
+   *   Array of missing tools with installation instructions.
+   */
+  protected function checkRequiredTools(): array {
+    $tools = [
+      'docker' => [
+        'name' => 'Docker',
+        'command' => 'docker',
+        'instructions' => 'https://www.docker.com/get-started',
+      ],
+      'pygmy' => [
+        'name' => 'Pygmy',
+        'command' => 'pygmy',
+        'instructions' => 'https://github.com/pygmystack/pygmy',
+      ],
+      'ahoy' => [
+        'name' => 'Ahoy',
+        'command' => 'ahoy',
+        'instructions' => 'https://github.com/ahoy-cli/ahoy',
+      ],
+    ];
+
+    $missing = [];
+
+    foreach ($tools as $tool) {
+      // Use exec with output capture to avoid output to console.
+      $output = [];
+      $return_code = 0;
+      exec(sprintf('command -v %s 2>/dev/null', $tool['command']), $output, $return_code);
+
+      if ($return_code !== 0) {
+        $missing[$tool['name']] = $tool['instructions'];
+      }
+    }
+
+    return $missing;
+  }
+
+}

.vortex/installer/src/Prompts/InstallerPresenter.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\VortexInstaller\Schema;
+
+/**
+ * Renders AI agent instructions for the installer.
+ *
+ * @package DrevOps\VortexInstaller\Schema
+ */
+class AgentHelp {
+
+  /**
+   * Render agent help text.
+   *
+   * @return string
+   *   The agent help text.
+   */
+  public static function render(): string {
+    return <<<'AGENT_HELP'
+# Vortex Installer - AI Agent Instructions
+
+You are interacting with the Vortex installer, a CLI tool that sets up Drupal
+projects from the Vortex template. This guide explains how to use the installer
+programmatically.
+
+## Workflow
+
+1. **Discover prompts**: Run with `--schema` to get a JSON manifest of all
+   available configuration prompts, their types, valid values, defaults, and
+   dependencies.
+
+2. **Build a config**: Using the schema, construct a JSON object where keys are
+   either prompt IDs (e.g., `hosting_provider`) or environment variable names
+   (e.g., `VORTEX_INSTALLER_PROMPT_HOSTING_PROVIDER`). Set values according to
+   the prompt types and allowed options from the schema.
+
+3. **Validate the config**: Run with `--validate --config='<json>'` to check
+   your config without performing an installation. The output is a JSON object
+   with `valid`, `errors`, `warnings`, and `resolved` fields.
+
+4. **Install**: Run with `--no-interaction --config='<json>' --destination=<dir>`
+   to perform the actual installation using your validated config.
+
+## Commands
+
+```bash
+# Get the prompt schema
+php installer.php --schema
+
+# Validate a config (JSON string)
+php installer.php --validate --config='{"name":"My Project","hosting_provider":"lagoon"}'
+
+# Validate a config (JSON file)
+php installer.php --validate --config=config.json
+
+# Install non-interactively
+php installer.php --no-interaction --config='<json>' --destination=./my-project
+```
+
+## Schema Format
+
+The `--schema` output contains a `prompts` array. Each prompt has:
+
+- `id`: The prompt identifier (use as config key).
+- `env`: The environment variable name (alternative config key).
+- `type`: One of `text`, `select`, `multiselect`, `confirm`, `suggest`.
+- `label`: Human-readable label.
+- `description`: Optional description text.
+- `options`: For `select`/`multiselect`, an array of `{value, label}` objects
+  representing the allowed values.
+- `default`: The default value if not provided.
+- `required`: Whether the prompt requires a value.
+- `depends_on`: Dependency conditions. If set, this prompt only applies when
+  the referenced prompt has one of the specified values. A `_system` key
+  indicates a system-state dependency (not config-based).
+
+## Value Types by Prompt Type
+
+- `text` / `suggest`: string value.
+- `select`: string value matching one of the option values.
+- `multiselect`: array of strings, each matching an option value.
+- `confirm`: boolean (`true` or `false`).
+
+## Dependencies
+
+Some prompts depend on other prompts. For example, `hosting_project_name`
+depends on `hosting_provider` being `lagoon` or `acquia`. If you set
+`hosting_provider` to `none`, you do not need to provide `hosting_project_name`.
+
+When a dependency is not met:
+- Omitting the dependent value is OK (it will be skipped).
+- Providing a value triggers a warning (it will be ignored).
+
+When a dependency is met:
+- Required prompts must have a value or they produce an error.
+
+## Validation Output
+
+The `--validate` output contains:
+
+- `valid`: boolean - whether the config is valid.
+- `errors`: array of `{prompt, message}` objects for invalid values.
+- `warnings`: array of `{prompt, message}` objects for ignored values.
+- `resolved`: object with the final merged config (your values + defaults).
+
+## Tips
+
+- Start with `--schema` to understand what prompts exist.
+- Provide values only for prompts you want to customize; defaults will be
+  used for the rest.
+- Use `--validate` to check your config before installing.
+- The `resolved` field in validation output shows the complete config that
+  would be used, including defaults.
+AGENT_HELP;
+  }
+
+}