From 54887bb0d09e50cbf4a48fd952931d59c5b79899 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Wed, 29 Jul 2026 13:14:45 +1000 Subject: [PATCH 1/4] Added a user-facing CLI reference page to the documentation. --- .vortex/docs/content/cli.mdx | 142 ++++++++++++++++++ .../content/contributing/maintenance/cli.mdx | 2 +- .vortex/docs/content/installation.mdx | 4 + .vortex/docs/content/updating-vortex.mdx | 2 +- 4 files changed, 148 insertions(+), 2 deletions(-) create mode 100644 .vortex/docs/content/cli.mdx diff --git a/.vortex/docs/content/cli.mdx b/.vortex/docs/content/cli.mdx new file mode 100644 index 000000000..bbcf546a0 --- /dev/null +++ b/.vortex/docs/content/cli.mdx @@ -0,0 +1,142 @@ +--- +sidebar_position: 4 +--- + +# CLI + +The **Vortex** CLI is a single self-contained binary that scaffolds a new project from the template and updates an existing one. It ships as a PHAR, so it needs nothing installed beyond PHP. + +```shell title="Download and run" +curl -SsL https://www.vortextemplate.com/install > vortex.phar && php vortex.phar +``` + +For the step-by-step walkthrough of setting up a new project, see [Installation](./installation). + +## Commands + +| Command | Purpose | +|----------------------|------------------------------------------------------| +| `install` | Install **Vortex** from a remote or local repository | +| `check-requirements` | Check that the required tools are installed | +| `build` | Build the site using `ahoy build` | + +`install` is the default command, so `php vortex.phar` and `php vortex.phar install` do the same thing. + +```shell title="List every command and option" +php vortex.phar list +php vortex.phar install --help +``` + +### install + +Downloads the template, asks the configuration questions, and writes the result into the destination directory. Run it in an existing **Vortex** project to update that project instead. + +| Option | Short | Description | +|-----------------------|-------|---------------------------------------------------------------------------------| +| `--destination` | | Destination directory. Defaults to the current directory | +| `--root` | | Path used to resolve relative paths. Defaults to the current directory | +| `--uri` | `-l` | Remote or local repository URI, with an optional git ref after `#` | +| `--no-interaction` | `-n` | Do not ask any interactive question | +| `--config` | `-c` | JSON string, or path to a JSON file, of CLI configuration | +| `--prompts` | `-p` | JSON string, or path to a JSON file, of prompt answers keyed by prompt ID | +| `--schema` | | Output the prompt schema as JSON and exit | +| `--validate` | | Validate the supplied answers without installing | +| `--build` | `-b` | Run the build after installing, without prompting | +| `--no-cleanup` | | Do not remove the CLI after a successful installation | +| `--agent-help` | | Output instructions for AI agents and exit | + +The `--uri` option accepts a git ref after `#`, which selects what to install: + +```shell title="Choosing what to install" +php vortex.phar install --uri=https://github.com/drevops/vortex.git +php vortex.phar install --uri=https://github.com/drevops/vortex.git#stable +php vortex.phar install --uri=https://github.com/drevops/vortex.git#1.2.3 +``` + +### check-requirements + +Checks for the tools a **Vortex** project needs: Docker, Docker Compose, Ahoy and Pygmy. + +| Option | Short | Description | +|----------------|-------|--------------------------------------------------------| +| `--only` | `-o` | Comma-separated subset of requirements to check | +| `--no-summary` | | Hide the summary listing tool versions | + +### build + +Builds the site by running `ahoy build` in the project directory. + +| Option | Short | Description | +|----------------------------|-------|------------------------------------------------------| +| `--profile` | `-p` | Build from the install profile instead of a database | +| `--skip-requirements-check`| | Skip checking for the required tools | + +## Non-interactive use + +Every question can be answered up front, which is what makes the CLI usable from a script or a pipeline. Ask for the schema, build an answers object from it, optionally validate, then install: + +```shell title="Discover the available prompts" +php vortex.phar install --schema +``` + +```shell title="Validate answers without installing" +php vortex.phar install --validate --prompts='{"name":"My Project","hosting_provider":"lagoon"}' +``` + +```shell title="Install non-interactively" +php vortex.phar install --no-interaction --prompts=prompts.json --destination=./my-project +``` + +`--prompts` keys are the prompt IDs from `--schema`. `--config` is separate: it carries CLI configuration such as the repository and ref, not prompt answers. + +:::tip Using an AI agent + +`--agent-help` prints the whole workflow above as instructions written for an AI coding agent: + +```shell +php vortex.phar install --agent-help +``` + +::: + +## Environment variables + +Variables are scoped by what they configure. Settings that belong to the CLI itself use the `VORTEX_CLI_` prefix; settings that belong to the `install` command use `VORTEX_CLI_INSTALL_`. + +| Variable | Purpose | +|------------------------------------|-----------------------------------------------| +| `VORTEX_CLI_VERSION` | Override the version stamped into the binary | +| `VORTEX_CLI_URL` | Where `ahoy update-vortex` downloads the PHAR | +| `VORTEX_CLI_PATH` | Local PHAR path; overrides the URL | +| `VORTEX_CLI_URL_CACHE_BUST` | Cache-busting parameter for the URL | +| `VORTEX_CLI_INSTALL_TMP_DIR` | Working directory for the downloaded source | +| `VORTEX_CLI_INSTALL_TEMPLATE_REPO` | Template repository to install from | +| `VORTEX_CLI_INSTALL_PROMPT_` | Answer for a single prompt, by prompt ID | + +:::note Superseded variable names + +These variables were previously prefixed with `VORTEX_INSTALLER_`. The old names still work: when the current name is unset, the matching legacy name supplies the value and the run prints a notice naming its replacement. The fallback exists to ease migration and will be removed in a future major version. + +::: + +## Distribution + +The CLI is published to three stable paths, each served with no file extension: + +| Path | Contents | +|---------------------------------------------|-------------------------| +| `https://www.vortextemplate.com/install` | The current major | +| `https://www.vortextemplate.com/v1/install` | The `1.x` line | +| `https://www.vortextemplate.com/v2/install` | The `2.x` line | + +The bare `/install` path always serves the current major. Each per-major path is built from that major's own branch, so pinning to `/v1/install` or `/v2/install` keeps you on that line. + +A build refuses to run against a project from a different major version and points you at the matching path instead, so an accidental cross-major update cannot happen silently. + +## Updating an existing project + +Inside a **Vortex** project, `ahoy update-vortex` downloads the CLI and runs it for you - you do not need to fetch the binary yourself. See [Updating Vortex](./updating-vortex). + +## Maintaining the CLI + +For how the CLI is developed, tested and released, see [Maintenance / CLI](./contributing/maintenance/cli). diff --git a/.vortex/docs/content/contributing/maintenance/cli.mdx b/.vortex/docs/content/contributing/maintenance/cli.mdx index d59d93296..796f4ff5c 100644 --- a/.vortex/docs/content/contributing/maintenance/cli.mdx +++ b/.vortex/docs/content/contributing/maintenance/cli.mdx @@ -93,7 +93,7 @@ Content removed if feature not selected ## Distribution -The PHAR is published to three stable, extensionless paths: +The PHAR is published to three stable paths, each served with no file extension: | Path | Contents | |---------------------------------------------|-------------------------| diff --git a/.vortex/docs/content/installation.mdx b/.vortex/docs/content/installation.mdx index b25826a98..74445706a 100644 --- a/.vortex/docs/content/installation.mdx +++ b/.vortex/docs/content/installation.mdx @@ -12,6 +12,8 @@ These steps take you from an empty directory to a deployed site. The **Vortex** CLI scaffolds your codebase; the remaining steps connect it to your hosting platform and continuous integration provider. Follow them in order. +For the full command, option and environment-variable reference, see [CLI](./cli). + ## Installing Vortex into a new project ### 1. Install Vortex @@ -42,6 +44,8 @@ get instructions for a non-interactive, programmatic installation: curl -SsL https://www.vortextemplate.com/install > vortex.phar && php vortex.phar --agent-help ``` +See [CLI](./cli#non-interactive-use) for the schema, validation and answer-file workflow. + ::: :::tip Choosing a Vortex version diff --git a/.vortex/docs/content/updating-vortex.mdx b/.vortex/docs/content/updating-vortex.mdx index 579de9d4b..e4858355a 100644 --- a/.vortex/docs/content/updating-vortex.mdx +++ b/.vortex/docs/content/updating-vortex.mdx @@ -27,7 +27,7 @@ secure and up-to-date. `1.x` project receives the latest `1.x` release and is never moved to `2.x` automatically. Moving to a new major is a deliberate step: run that major's CLI (for example `https://www.vortextemplate.com/v2/install`) against your -project. +project. See [CLI](./cli#distribution) for the per-major paths. ::: From a56020ac3d19534f14974312ae107589cc756aa4 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Wed, 29 Jul 2026 13:14:55 +1000 Subject: [PATCH 2/4] Cleared the remaining installer naming from the CLI package. --- .vortex/cli/README.md | 6 +++--- .vortex/cli/src/Utils/Normalizer.php | 2 +- .vortex/cli/tests/Functional/Command/InstallCommandTest.php | 6 +++--- .vortex/cli/tests/Functional/FunctionalTestCase.php | 2 +- .../Functional/Handlers/AbstractHandlerProcessTestCase.php | 4 ++-- .vortex/cli/tests/Functional/PharTest.php | 4 ++-- .vortex/cli/tests/Unit/EnvTest.php | 4 +--- .vortex/cli/tests/Unit/ValidatorTest.php | 2 +- 8 files changed, 14 insertions(+), 16 deletions(-) diff --git a/.vortex/cli/README.md b/.vortex/cli/README.md index b6fe46550..7bef40399 100644 --- a/.vortex/cli/README.md +++ b/.vortex/cli/README.md @@ -1,4 +1,4 @@ -# Vortex installer +# Vortex CLI ## Maintenance @@ -8,6 +8,6 @@ ### Releasing -The installer is packaged as a PHAR and deployed to https://www.vortextemplate.com/install +The CLI is packaged as a PHAR and deployed to https://www.vortextemplate.com/install upon each GitHub release or for every branch to a branch containing the -`release-docs` or `release-installer` in the name. +`release-docs` or `release-cli` in the name. diff --git a/.vortex/cli/src/Utils/Normalizer.php b/.vortex/cli/src/Utils/Normalizer.php index ca94d52f2..a958c5414 100644 --- a/.vortex/cli/src/Utils/Normalizer.php +++ b/.vortex/cli/src/Utils/Normalizer.php @@ -5,7 +5,7 @@ namespace DrevOps\VortexCli\Utils; /** - * Installer configuration. + * Install configuration. * * Install config is a config of the install command. * diff --git a/.vortex/cli/tests/Functional/Command/InstallCommandTest.php b/.vortex/cli/tests/Functional/Command/InstallCommandTest.php index a155ac1ab..b584821ea 100644 --- a/.vortex/cli/tests/Functional/Command/InstallCommandTest.php +++ b/.vortex/cli/tests/Functional/Command/InstallCommandTest.php @@ -589,19 +589,19 @@ public function testInstallCommandMajorGate(?string $version, string $composer_j * Test data. */ public static function dataProviderInstallCommandMajorGate(): \Iterator { - yield 'v1 installer refuses v2 project' => [ + yield 'v1 CLI refuses v2 project' => [ '1.40.0', '{"require": {"drevops/vortex-tooling": "^2.0.0"}}', FALSE, 'https://www.vortextemplate.com/v2/install', ]; - yield 'v1 installer accepts v1 project' => [ + yield 'v1 CLI accepts v1 project' => [ '1.40.0', '{"require": {"drevops/vortex-tooling": "^1.1.0"}}', TRUE, 'Failed to download Vortex.', ]; - yield 'unstamped installer skips gate' => [ + yield 'unstamped CLI skips gate' => [ NULL, '{"require": {"drevops/vortex-tooling": "^2.0.0"}}', TRUE, diff --git a/.vortex/cli/tests/Functional/FunctionalTestCase.php b/.vortex/cli/tests/Functional/FunctionalTestCase.php index 58279da7c..233813cb2 100644 --- a/.vortex/cli/tests/Functional/FunctionalTestCase.php +++ b/.vortex/cli/tests/Functional/FunctionalTestCase.php @@ -71,7 +71,7 @@ protected function runNonInteractiveInstall(?string $dst = NULL, array $options } // Skip the database fetch in demo mode as it is not needed for the - // installer's tests. + // CLI's tests. Env::put(Config::IS_DEMO_DB_FETCH_SKIP, '1'); $this->applicationRun($args, [], $expect_fail); diff --git a/.vortex/cli/tests/Functional/Handlers/AbstractHandlerProcessTestCase.php b/.vortex/cli/tests/Functional/Handlers/AbstractHandlerProcessTestCase.php index 4513ef09d..66d9c5000 100644 --- a/.vortex/cli/tests/Functional/Handlers/AbstractHandlerProcessTestCase.php +++ b/.vortex/cli/tests/Functional/Handlers/AbstractHandlerProcessTestCase.php @@ -12,9 +12,9 @@ use PHPUnit\Framework\Attributes\RunInSeparateProcess; /** - * Abstract base class for installer tests. + * Abstract base class for install tests. * - * Provides common test logic for all installer test scenarios. + * Provides common test logic for all install test scenarios. * Run `ahoy update-snapshots` from `.vortex/` to update test snapshots. */ abstract class AbstractHandlerProcessTestCase extends FunctionalTestCase { diff --git a/.vortex/cli/tests/Functional/PharTest.php b/.vortex/cli/tests/Functional/PharTest.php index dd34b57f3..192489d3d 100644 --- a/.vortex/cli/tests/Functional/PharTest.php +++ b/.vortex/cli/tests/Functional/PharTest.php @@ -37,7 +37,7 @@ protected function setUp(): void { parent::setUp(); // We use 'Star Wars' theme for the tests, so setting up SUT directory - // so that the installer can gather the answers from the directory name. + // so that the CLI can gather the answers from the directory name. static::$sut = static::locationsMkdir(static::$workspace . DIRECTORY_SEPARATOR . 'star_wars'); // Copy the PHAR file to the SUT directory. @@ -111,7 +111,7 @@ protected function runInstallationWithPhar(string $phar_path, array $options = [ ]; $options += $defaults; - // The interactive mode is not supported in the tests as installer + // The interactive mode is not supported in the tests as the CLI // uses Laravel\Prompts which require a real TTY or a series of fallback // callbacks to be defined. These callbacks are not implemented yet, so // we enforce the non-interactive mode for the tests. diff --git a/.vortex/cli/tests/Unit/EnvTest.php b/.vortex/cli/tests/Unit/EnvTest.php index c873d1044..0b90add72 100644 --- a/.vortex/cli/tests/Unit/EnvTest.php +++ b/.vortex/cli/tests/Unit/EnvTest.php @@ -11,9 +11,7 @@ use DrevOps\VortexCli\Utils\File; /** - * Class InstallerDotEnvTest. - * - * InstallerDotEnvTest fixture class. + * Tests for the Env class. */ #[CoversClass(Env::class)] #[RunTestsInSeparateProcesses] diff --git a/.vortex/cli/tests/Unit/ValidatorTest.php b/.vortex/cli/tests/Unit/ValidatorTest.php index 1f8dd4e2e..6f7aa8363 100644 --- a/.vortex/cli/tests/Unit/ValidatorTest.php +++ b/.vortex/cli/tests/Unit/ValidatorTest.php @@ -9,7 +9,7 @@ use DrevOps\VortexCli\Utils\Validator; /** - * Class InstallerHelpersTest. + * Tests for the Validator class. */ #[CoversClass(Validator::class)] class ValidatorTest extends UnitTestCase { From c19f92894552e6ca72a5a5af0631a8edb50ed88f Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Wed, 29 Jul 2026 13:33:29 +1000 Subject: [PATCH 3/4] Re-triggered CI to clear a flaky check. From 49f3c68650a7ecf7585eb9b7e11f2ad7f2ff56b6 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Wed, 29 Jul 2026 13:50:01 +1000 Subject: [PATCH 4/4] Named the install command where the text describes installing. --- .docker/cli.dockerfile | 2 +- .vortex/CLAUDE.md | 2 +- .vortex/cli/CLAUDE.md | 2 +- .../Functional/Command/InstallCommandTest.php | 4 ++-- .vortex/cli/tests/Functional/PharTest.php | 3 ++- .../content/contributing/maintenance/cli.mdx | 8 ++++---- .../content/development/visual-regression.mdx | 2 +- .vortex/docs/content/drupal/composer-json.mdx | 2 +- .vortex/docs/content/faqs.mdx | 4 ++-- .vortex/docs/content/installation.mdx | 8 ++++---- .vortex/docs/src/pages/index.js | 6 +++--- .../phpunit/Functional/AhoyWorkflowTest.php | 2 +- .../phpunit/Functional/FunctionalTestCase.php | 4 ++-- .vortex/tests/phpunit/Traits/SutTrait.php | 20 +++++++++---------- .vortex/tests/update-test-assets | 2 +- .vortex/tooling/src/vortex-provision | 4 ++-- scripts/vortex-tooling.sh | 2 +- 17 files changed, 39 insertions(+), 38 deletions(-) diff --git a/.docker/cli.dockerfile b/.docker/cli.dockerfile index f48d66bb8..527c3700a 100644 --- a/.docker/cli.dockerfile +++ b/.docker/cli.dockerfile @@ -83,7 +83,7 @@ COPY composer.json composer.* patches.lock.* .env* auth* /app/ #;< VORTEX_DEV # Copy the in-tree drevops/vortex-tooling package so the path repository # declared in composer.json can resolve during the build. Consumer sites -# get the package from packagist; the Vortex CLI strips this block. +# get the package from packagist; the CLI install command strips this block. COPY .vortex/tooling /app/.vortex/tooling #;> VORTEX_DEV diff --git a/.vortex/CLAUDE.md b/.vortex/CLAUDE.md index 4749f39df..5e4a877fe 100644 --- a/.vortex/CLAUDE.md +++ b/.vortex/CLAUDE.md @@ -97,7 +97,7 @@ subscripts remain Bash. template's root `composer.json` requires `"drevops/vortex-tooling": "^2.0@alpha"` and the path repository pins `"versions": {"drevops/vortex-tooling": "2.0.0-alpha1"}` so the in-repo copy -resolves during development. The CLI strips that path repository from +resolves during development. The CLI install command strips that path repository from consumer sites; until a `2.0` pre-release is published to Packagist, scaffolded sites cannot resolve the tooling - acceptable during 2.x pre-release development. Once a `2.0` release is published, switch the constraint to a plain diff --git a/.vortex/cli/CLAUDE.md b/.vortex/cli/CLAUDE.md index 148235fc6..6fd27bd64 100644 --- a/.vortex/cli/CLAUDE.md +++ b/.vortex/cli/CLAUDE.md @@ -80,7 +80,7 @@ within a file that survives the install regardless of the choice. Use them conditionally while the rest of the file stays. - The choice can flip independently of any other selection. -**Do not** wrap an entire file in fences if the CLI removes the whole +**Do not** wrap an entire file in fences if the install command removes the whole file via `File::remove($t . '/path/to/file')` based on the same selection. The file removal is the conditional behaviour - the fences are dead noise and add visual clutter to the shipped file. Examples: diff --git a/.vortex/cli/tests/Functional/Command/InstallCommandTest.php b/.vortex/cli/tests/Functional/Command/InstallCommandTest.php index b584821ea..06027af69 100644 --- a/.vortex/cli/tests/Functional/Command/InstallCommandTest.php +++ b/.vortex/cli/tests/Functional/Command/InstallCommandTest.php @@ -589,13 +589,13 @@ public function testInstallCommandMajorGate(?string $version, string $composer_j * Test data. */ public static function dataProviderInstallCommandMajorGate(): \Iterator { - yield 'v1 CLI refuses v2 project' => [ + yield 'v1 installer refuses v2 project' => [ '1.40.0', '{"require": {"drevops/vortex-tooling": "^2.0.0"}}', FALSE, 'https://www.vortextemplate.com/v2/install', ]; - yield 'v1 CLI accepts v1 project' => [ + yield 'v1 installer accepts v1 project' => [ '1.40.0', '{"require": {"drevops/vortex-tooling": "^1.1.0"}}', TRUE, diff --git a/.vortex/cli/tests/Functional/PharTest.php b/.vortex/cli/tests/Functional/PharTest.php index 192489d3d..241c1b78a 100644 --- a/.vortex/cli/tests/Functional/PharTest.php +++ b/.vortex/cli/tests/Functional/PharTest.php @@ -37,7 +37,8 @@ protected function setUp(): void { parent::setUp(); // We use 'Star Wars' theme for the tests, so setting up SUT directory - // so that the CLI can gather the answers from the directory name. + // so that the install command can gather the answers from the directory + // name. static::$sut = static::locationsMkdir(static::$workspace . DIRECTORY_SEPARATOR . 'star_wars'); // Copy the PHAR file to the SUT directory. diff --git a/.vortex/docs/content/contributing/maintenance/cli.mdx b/.vortex/docs/content/contributing/maintenance/cli.mdx index 796f4ff5c..19098fde6 100644 --- a/.vortex/docs/content/contributing/maintenance/cli.mdx +++ b/.vortex/docs/content/contributing/maintenance/cli.mdx @@ -68,12 +68,12 @@ The core flow is: ### Conditional token system In addition to string substitution for handling simple replacements and -additions, the CLI uses a token system to conditionally exclude entire +additions, the install command uses a token system to conditionally exclude entire blocks of content from template files. This simplifies the management of optional features — rather than requiring complex logic to surgically remove lines from configuration files, scripts, or documentation, maintainers simply wrap the relevant content in token markers. When a feature is not selected -during installation, the CLI removes everything between the markers. +during installation, the install command removes everything between the markers. **Markdown**: @@ -147,7 +147,7 @@ is tested in isolation with mocks provided by ### Functional testing with snapshots -For every test permutation, the CLI *initiates a fresh project* from the +For every test permutation, the install command *initiates a fresh project* from the Vortex template with a specific combination of user selections and runs assertions against the resulting files. Because a single template change can affect a hundred plus installation permutations, snapshot testing makes it easy to @@ -216,7 +216,7 @@ cd .vortex/cli UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter "testHandlerProcess.*baseline" ``` -When `UPDATE_SNAPSHOTS` is set, the CLI *runs for every permutation*, +When `UPDATE_SNAPSHOTS` is set, the install command *runs for every permutation*, initiates a fresh project for each scenario, and automatically updates the fixture files to match the current output. The resulting changes appear as diffs in version control, making it straightforward to review exactly how a diff --git a/.vortex/docs/content/development/visual-regression.mdx b/.vortex/docs/content/development/visual-regression.mdx index a396d5ab4..2e87a2b6c 100644 --- a/.vortex/docs/content/development/visual-regression.mdx +++ b/.vortex/docs/content/development/visual-regression.mdx @@ -326,5 +326,5 @@ Adjust `VR_DIFFY_PR_LABEL`, `VR_DIFFY_AUTO_BRANCHES`, and Remove `diffy` from `VORTEX_NOTIFY_CHANNELS` and delete the `.github/workflows/test-vr.yml` workflow file. -To remove the integration entirely, re-run the CLI and answer +To remove the integration entirely, re-run the install command and answer "no" to the visual regression prompt. diff --git a/.vortex/docs/content/drupal/composer-json.mdx b/.vortex/docs/content/drupal/composer-json.mdx index 2d5ed1a6d..b7520248a 100644 --- a/.vortex/docs/content/drupal/composer-json.mdx +++ b/.vortex/docs/content/drupal/composer-json.mdx @@ -74,7 +74,7 @@ outside the default Packagist repository. - `drevops/vortex-tooling` (path): A local [path repository](https://getcomposer.org/doc/05-repositories.md#path) pointing at `.vortex/tooling`, used only inside the **Vortex** repository so - the in-tree tooling package resolves during development. The CLI strips + the in-tree tooling package resolves during development. The CLI install command strips this entry during site creation, so your project installs [`drevops/vortex-tooling`](https://github.com/drevops/vortex-tooling) from Packagist instead. diff --git a/.vortex/docs/content/faqs.mdx b/.vortex/docs/content/faqs.mdx index b0bd336f1..0f2264255 100644 --- a/.vortex/docs/content/faqs.mdx +++ b/.vortex/docs/content/faqs.mdx @@ -43,8 +43,8 @@ discuss any of the decisions made in **Vortex**. ## Isn't this overkill for my project? **Vortex** provides a full feature set to all projects, regardless of size. You -can simply opt-out of features you don't need when installing: the CLI -provides an interactive prompt to select only the features you want. +can simply opt-out of features you don't need when installing: the CLI install +command provides an interactive prompt to select only the features you want. If you're sure you don't need certain features, **Vortex** may not be the right fit. That said, many developers have discovered useful tools and diff --git a/.vortex/docs/content/installation.mdx b/.vortex/docs/content/installation.mdx index 74445706a..8b7730e4b 100644 --- a/.vortex/docs/content/installation.mdx +++ b/.vortex/docs/content/installation.mdx @@ -9,8 +9,8 @@ import TabItem from '@theme/TabItem'; # Installation These steps take you from an empty directory to a deployed site. The **Vortex** -CLI scaffolds your codebase; the remaining steps connect it to your hosting -platform and continuous integration provider. Follow them in order. +CLI install command scaffolds your codebase; the remaining steps connect it to +your hosting platform and continuous integration provider. Follow them in order. For the full command, option and environment-variable reference, see [CLI](./cli). @@ -213,7 +213,7 @@ runs the tests, and deploys according to your configuration. ## Installing Vortex into an existing project -The CLI cannot predict the state of your project, so initialize **Vortex** +The CLI install command cannot predict the state of your project, so initialize **Vortex** into a new directory and merge your existing project into it. :::warning @@ -226,7 +226,7 @@ Back up your project before proceeding. 2. In your existing project, create a new branch and remove all files except the `.git` directory. -3. Run the CLI ([step 1](#1-install-vortex)) to produce a clean **Vortex** installation, then commit it. +3. Run the install command ([step 1](#1-install-vortex)) to produce a clean **Vortex** installation, then commit it. 4. Copy your files back from the temporary directory, overriding the installed ones. Review the diff and selectively keep changes - merge `composer.json` by hand (preserving **all** of **Vortex's** entries) and regenerate `composer.lock` with `composer install`. diff --git a/.vortex/docs/src/pages/index.js b/.vortex/docs/src/pages/index.js index 510b274fc..5fdbe2044 100644 --- a/.vortex/docs/src/pages/index.js +++ b/.vortex/docs/src/pages/index.js @@ -316,7 +316,7 @@ export default function Home() { > Animated demo of the Vortex CLI scaffolding a new project from a single command {' '} - The CLI scaffolds your whole project - structure, tooling, - CI, and hosting - in one run. + The install command scaffolds your whole project - + structure, tooling, CI, and hosting - in one run.

diff --git a/.vortex/tests/phpunit/Functional/AhoyWorkflowTest.php b/.vortex/tests/phpunit/Functional/AhoyWorkflowTest.php index 2fcad2015..6c988867f 100644 --- a/.vortex/tests/phpunit/Functional/AhoyWorkflowTest.php +++ b/.vortex/tests/phpunit/Functional/AhoyWorkflowTest.php @@ -407,7 +407,7 @@ public function testAhoyUpdateVortexLatest(): void { $this->assertFileContainsString('web/themes/custom/star_wars/.eslintrc.json', '# Update 2 to Vortex in .eslintrc.json', 'Theme .eslintrc.json should contain update 2 changes'); $this->logSubstep('Assert that legacy scripts/vortex/ was removed'); - $this->assertDirectoryDoesNotExist('scripts/vortex', 'Legacy scripts/vortex/ directory was removed by the CLI.'); + $this->assertDirectoryDoesNotExist('scripts/vortex', 'Legacy scripts/vortex/ directory was removed by the CLI install command.'); $this->logSubstep('Assert that new changes need to be manually resolved'); $this->gitAssertNotClean(static::$sut, 'Git working tree should not be clean after Vortex update'); diff --git a/.vortex/tests/phpunit/Functional/FunctionalTestCase.php b/.vortex/tests/phpunit/Functional/FunctionalTestCase.php index f1bfcb14a..f0e3e4280 100644 --- a/.vortex/tests/phpunit/Functional/FunctionalTestCase.php +++ b/.vortex/tests/phpunit/Functional/FunctionalTestCase.php @@ -34,8 +34,8 @@ protected function setUp(): void { self::locationsInit(File::cwd() . '/../..'); // We use 'Star Wars'-themed test assertions, so we need to create a named - // SUT directory for the CLI to gather the answers from the directory - // name. + // SUT directory for the install command to gather the answers from the + // directory name. static::$sut = static::locationsMkdir(static::$workspace . '/star_wars'); // Export the current codebase to a fixture remote repository. diff --git a/.vortex/tests/phpunit/Traits/SutTrait.php b/.vortex/tests/phpunit/Traits/SutTrait.php index 80bb4dbc7..e7d3ae211 100644 --- a/.vortex/tests/phpunit/Traits/SutTrait.php +++ b/.vortex/tests/phpunit/Traits/SutTrait.php @@ -93,16 +93,16 @@ protected function prepareSut(string $webroot = 'web'): void { /** * Inject a path repository for drevops/vortex-tooling into the SUT. * - * The CLI strips '.vortex/tooling' and the path repository from the - * SUT's composer.json so consumer sites resolve drevops/vortex-tooling - * from packagist. Until the package is published, the SUT cannot resolve - * it, so the workflow tests would fail at the Dockerfile's composer - * install step. This method copies the in-tree tooling into the SUT at - * '.tooling-source' (deliberately outside '.vortex/' so the SUT keeps no - * '.vortex/' directory at runtime), re-injects the path repository into - * composer.json, re-injects the COPY into cli.dockerfile, and adjusts - * '.dockerignore' and '.gitignore.artifact' so the tooling source enters - * the build context but never the deployment artifact. + * The CLI install command strips '.vortex/tooling' and the path repository + * from the SUT's composer.json so consumer sites resolve + * drevops/vortex-tooling from packagist. Until the package is published, the + * SUT cannot resolve it, so the workflow tests would fail at the + * Dockerfile's composer install step. This method copies the in-tree tooling + * into the SUT at '.tooling-source' (deliberately outside '.vortex/' so the + * SUT keeps no '.vortex/' directory at runtime), re-injects the path + * repository into composer.json, re-injects the COPY into cli.dockerfile, + * and adjusts '.dockerignore' and '.gitignore.artifact' so the tooling + * source enters the build context but never the deployment artifact. * * @todo Remove once drevops/vortex-tooling is published to packagist. */ diff --git a/.vortex/tests/update-test-assets b/.vortex/tests/update-test-assets index dfa34e6ce..eb4d61123 100755 --- a/.vortex/tests/update-test-assets +++ b/.vortex/tests/update-test-assets @@ -232,7 +232,7 @@ function reset_sut(string $root_dir, string $cli): void { // (uid 33). When those bind-mounts surface on the host, plain 'rm -rf' // by the current user fails with "Permission denied". Clear the contents // via an ephemeral root-privileged container so file ownership doesn't - // matter, then leave the dir itself in place for the CLI. + // matter, then leave the dir itself in place for the install command. run(sprintf('mkdir -p %s', escapeshellarg(SUT_DIR))); run(sprintf( 'docker run --rm -v %s:/sut alpine find /sut -mindepth 1 -delete', diff --git a/.vortex/tooling/src/vortex-provision b/.vortex/tooling/src/vortex-provision index 89c4a52bf..c7851f2ac 100755 --- a/.vortex/tooling/src/vortex-provision +++ b/.vortex/tooling/src/vortex-provision @@ -691,8 +691,8 @@ echo PHP_EOL; // Enable the deploy_steps runner and the always-on site modules before deploy // hooks, so their deploy step plugins and run-once deploy hooks run on this -// provision. Site module names are project-specific (the Vortex CLI renames -// them), so resolve them by glob. Idempotent in every environment. +// provision. Site module names are project-specific (the CLI install command +// renames them), so resolve them by glob. Idempotent in every environment. TASK('Enabling site modules.', 'Enabled site modules.', function () use ($webroot): void { drush('pm:install deploy_steps'); $module_paths = array_merge((array) glob($webroot . '/modules/custom/*_base', GLOB_ONLYDIR), (array) glob($webroot . '/modules/custom/*_migrate', GLOB_ONLYDIR)); diff --git a/scripts/vortex-tooling.sh b/scripts/vortex-tooling.sh index 37d949b9e..e2362b72e 100755 --- a/scripts/vortex-tooling.sh +++ b/scripts/vortex-tooling.sh @@ -53,7 +53,7 @@ echo "{\"require\":{\"drevops/vortex-tooling\":\"${version}\"}}" >vendor-temp/co #;< VORTEX_DEV # In dev mode the package is not yet on Packagist, so add a path repository -# pointing at the in-tree copy. The Vortex CLI strips this VORTEX_DEV-fenced +# pointing at the in-tree copy. The CLI install command strips this VORTEX_DEV-fenced # block from consumer sites. composer --working-dir=vendor-temp config repositories.vortex-tooling --json '{"type":"path","url":"../.vortex/tooling","options":{"symlink":false,"versions":{"drevops/vortex-tooling":"2.0.0-alpha1"}}}' #;> VORTEX_DEV