diff --git a/.claude/skills/prepare-vortex-release/SKILL.md b/.claude/skills/prepare-vortex-release/SKILL.md index 5d8b849037..34e19fdb1a 100644 --- a/.claude/skills/prepare-vortex-release/SKILL.md +++ b/.claude/skills/prepare-vortex-release/SKILL.md @@ -114,10 +114,10 @@ Work through each checklist item from the release process doc: otherwise it runs silently so the remaining commands have a built project to work against. - To re-record a subset, pass the names: - `ahoy update-videos installer build lint`. Allowed names: `installer`, + `ahoy update-videos cli-install build lint`. Allowed names: `cli-install`, `build`, `provision`, `lint`, `test`, `test-bdd`. Default is all six. - Heavy step: ~15-20 minutes wall-clock when running all six; requires - Docker. `ahoy update-videos installer` is fast (no Docker). + Docker. `ahoy update-videos cli-install` is fast (no Docker). - The command does NOT auto-commit; review the artifact diff under `.vortex/docs/static/img/` and stage manually. @@ -193,7 +193,7 @@ Summary paragraph (1-3 sentences). --- -### 🎛 Installer +### 🎛 CLI (same sub-sections) @@ -269,17 +269,17 @@ The `## 🔍 Highlights` section is the part most readers will actually read. It 7. **Runtime / platform bumps** when they are breaking (PHP major.minor, container major bumps). DO NOT highlight: -- Installer-only conveniences (e.g. installer flags) unless they unblock a category of users. +- CLI-only conveniences (e.g. CLI flags) unless they unblock a category of users. - Internal CI tweaks that have no consumer-facing effect. - Pure refactors. - Single-vendor integrations that most users won't reach for (e.g. an optional Codecov prompt). -If you are tempted to put an installer flag or an optional integration in highlights, ask: "Does the average Vortex consumer project benefit from this on day 1?". If no, move it down to its respective category section. +If you are tempted to put a CLI flag or an optional integration in highlights, ask: "Does the average Vortex consumer project benefit from this on day 1?". If no, move it down to its respective category section. ### Categorisation - **Template**: Changes to the project template files (scripts, configs, CI, modules, theme) -- **Installer**: Changes to `.vortex/installer/src/` code and installer-specific tests +- **CLI**: Changes to `.vortex/cli/src/` code and CLI-specific tests - **Documentation**: Changes to `.vortex/docs/` content Within each category: @@ -290,11 +290,11 @@ Within each category: ### Important -- Many commits touch installer **fixtures** because template changes cascade into them. - Only list changes in the Installer section if they modify actual installer **source code** - (`.vortex/installer/src/`) or installer-specific test logic. -- Check for commits that touch both template and installer source - list the template - change under Template and the installer-specific change under Installer. +- Many commits touch CLI **fixtures** because template changes cascade into them. + Only list changes in the CLI section if they modify actual CLI **source code** + (`.vortex/cli/src/`) or CLI-specific test logic. +- Check for commits that touch both template and CLI source - list the template + change under Template and the CLI-specific change under CLI. ## Command rules - CRITICAL diff --git a/.claude/skills/propagate-vortex-main-to-2x/SKILL.md b/.claude/skills/propagate-vortex-main-to-2x/SKILL.md index f127189498..6962a51f4f 100644 --- a/.claude/skills/propagate-vortex-main-to-2x/SKILL.md +++ b/.claude/skills/propagate-vortex-main-to-2x/SKILL.md @@ -216,7 +216,7 @@ git cherry-pick -x C Make the edits, then commit in the project's style (past-tense, ends with a period, code refs in single quotes), with a body line naming the source commit, e.g. `Forward-ported from main C.` -**Fixture-heavy commits** - any commit that also touches `.vortex/installer/tests/Fixtures/` (most template changes do). `2.x` has already regenerated those fixtures for its own work, so the commit's fixture hunks conflict on a cherry-pick even when the source applies cleanly. Never hand-merge fixture hunks - apply the **source files only** and let Step 8 regenerate the fixtures: +**Fixture-heavy commits** - any commit that also touches `.vortex/cli/tests/Fixtures/` (most template changes do). `2.x` has already regenerated those fixtures for its own work, so the commit's fixture hunks conflict on a cherry-pick even when the source applies cleanly. Never hand-merge fixture hunks - apply the **source files only** and let Step 8 regenerate the fixtures: - For a clean (un-diverged) source file, take it straight from the source commit instead of cherry-picking the whole thing: @@ -228,7 +228,7 @@ git cherry-pick -x C - If a `git cherry-pick` is already in progress and halted on fixture conflicts, discard the fixture changes (keeping the applied source), then continue: ```bash - git checkout HEAD -- .vortex/installer/tests/Fixtures + git checkout HEAD -- .vortex/cli/tests/Fixtures ``` The port commit must carry **source only**; Step 8's `update-snapshots` rebuilds every cascaded fixture in one pass, so any fixture delta inside a port commit is wrong and will fight the regeneration. @@ -241,7 +241,7 @@ git show --stat HEAD ### Step 8: Regenerate snapshots (foreground only) -If any applied commit touched **template** files (anything outside `.vortex/`), the installer fixtures must be regenerated or CI will fail. Run from `.vortex/`: +If any applied commit touched **template** files (anything outside `.vortex/`), the CLI fixtures must be regenerated or CI will fail. Run from `.vortex/`: ```bash cd .vortex @@ -333,7 +333,7 @@ Decision values: `applied`, `skipped`, `deferred-revisit` (re-surface next run), - About to background `ahoy update-snapshots`: stop. Foreground only - backgrounding leaves a partial branch. - About to skip snapshot regeneration after touching template files: stop. CI will fail on stale fixtures. - About to squash several ported commits into one: stop. Keep 1:1 with the source for traceability. -- About to bring a commit's `.vortex/installer/tests/Fixtures/` hunks into a port commit: stop. Apply source only; Step 8's `update-snapshots` regenerates fixtures. +- About to bring a commit's `.vortex/cli/tests/Fixtures/` hunks into a port commit: stop. Apply source only; Step 8's `update-snapshots` regenerates fixtures. - About to re-surface a commit the ledger marks `skipped` or `applied`: stop. Read the ledger in Step 3 first. - About to stage anything under `.artifacts/`: stop. The ledger and analysis are local-only. - About to cherry-pick a merge commit: stop. Vortex squash-merges PRs, so candidates should be single non-merge commits; a merge commit in the list means something is off - investigate before applying. diff --git a/.claude/skills/update-vortex-dev-deps/SKILL.md b/.claude/skills/update-vortex-dev-deps/SKILL.md index da58debc19..6ffd76ef55 100644 --- a/.claude/skills/update-vortex-dev-deps/SKILL.md +++ b/.claude/skills/update-vortex-dev-deps/SKILL.md @@ -1,6 +1,6 @@ --- name: update-vortex-dev-deps -description: Use when refreshing Composer and Yarn dev dependencies across the three '.vortex/' subsystems (docs, installer, tests). Runs in-range lock-file refreshes, lints each updated subsystem locally (with auto-fix where the subsystem supports it), produces a 'majors-available' report, makes a single bulk commit covering both lock and lint-fix fallout, and opens a PR. Triggers on phrases like 'update vortex dev deps', 'refresh .vortex dependencies', 'bump .vortex lock files', '/update-vortex-dev-deps'. +description: Use when refreshing Composer and Yarn dev dependencies across the three '.vortex/' subsystems (docs, cli, tests). Runs in-range lock-file refreshes, lints each updated subsystem locally (with auto-fix where the subsystem supports it), produces a 'majors-available' report, makes a single bulk commit covering both lock and lint-fix fallout, and opens a PR. Triggers on phrases like 'update vortex dev deps', 'refresh .vortex dependencies', 'bump .vortex lock files', '/update-vortex-dev-deps'. user-invocable: true --- @@ -24,7 +24,7 @@ Do NOT use for: This skill touches files under exactly three `.vortex/` subsystems: - `.vortex/docs/` (Yarn) -- `.vortex/installer/` (Composer, plus `vendor-bin/box/` sub-composer) +- `.vortex/cli/` (Composer, plus `vendor-bin/box/` sub-composer) - `.vortex/tests/` (Composer + Yarn) `.vortex/tooling/` is explicitly out of scope - see the "Do NOT use for" list above. @@ -60,10 +60,10 @@ Process in fixed order. Smallest blast radius first. Lint commands run from the | # | Subsystem (`.vortex/...`) | Composer manifest(s) | Yarn manifest | `patches.lock.json` | Lint commands | Lint-fix command | |---|---------------------------|---------------------------------------------------|------------------|---------------------|----------------------------------------------------------------------------------------|-----------------------------------------------------------| | 1 | `docs` | - | `package.json` | - | `yarn --cwd .vortex/docs run lint` + `yarn --cwd .vortex/docs run spellcheck` | `yarn --cwd .vortex/docs run lint-fix` | -| 2 | `installer` | `composer.json` + `vendor-bin/box/composer.json` | - | yes | `composer --working-dir .vortex/installer lint` | `composer --working-dir .vortex/installer lint-fix` | +| 2 | `cli` | `composer.json` + `vendor-bin/box/composer.json` | - | yes | `composer --working-dir .vortex/cli lint` | `composer --working-dir .vortex/cli lint-fix` | | 3 | `tests` | `composer.json` | `package.json` | yes | `composer --working-dir .vortex/tests lint` | `composer --working-dir .vortex/tests lint-fix` | -Confirm the lint and lint-fix command names against `.vortex/.ahoy.yml` (search for `lint-installer`, `lint-tests`, `lint-docs` and their `-fix` counterparts) before relying on the matrix. If a subsystem's lint or lint-fix command name changes upstream, this matrix is stale. +Confirm the lint and lint-fix command names against `.vortex/.ahoy.yml` (search for `lint-cli`, `lint-tests`, `lint-docs` and their `-fix` counterparts) before relying on the matrix. If a subsystem's lint or lint-fix command name changes upstream, this matrix is stale. ## Workflow @@ -119,14 +119,14 @@ Process the matrix in order. For each row, run the applicable commands below fro yarn --cwd .vortex/docs upgrade ``` -**3.2 - installer (Composer, plus sub-composer):** +**3.2 - cli (Composer, plus sub-composer):** ```bash -composer --working-dir .vortex/installer update +composer --working-dir .vortex/cli update ``` ```bash -composer --working-dir .vortex/installer/vendor-bin/box update +composer --working-dir .vortex/cli/vendor-bin/box update ``` **3.3 - tests (Composer + Yarn):** @@ -170,7 +170,7 @@ Format: |---------|-----------|--------| | @docusaurus/core | 3.4.0 | 4.0.1 | -## `.vortex/installer` (Composer) +## `.vortex/cli` (Composer) | Package | Installed | Latest | |---------|-----------|--------| @@ -199,10 +199,10 @@ yarn --cwd .vortex/docs run lint yarn --cwd .vortex/docs run spellcheck ``` -**5.2 - installer:** +**5.2 - cli:** ```bash -composer --working-dir .vortex/installer lint +composer --working-dir .vortex/cli lint ``` **5.3 - tests:** @@ -218,7 +218,7 @@ A dependency refresh frequently surfaces lint violations because a code-style to For the failing subsystem, run its lint-fix command from the matrix: - **docs**: `yarn --cwd .vortex/docs run lint-fix` -- **installer**: `composer --working-dir .vortex/installer lint-fix` +- **cli**: `composer --working-dir .vortex/cli lint-fix` - **tests**: `composer --working-dir .vortex/tests lint-fix` Then re-run the lint command(s) from the matrix for that subsystem (Step 5.1 / 5.2 / 5.3). Expected outcomes: @@ -237,19 +237,19 @@ git add .vortex/docs/yarn.lock ``` ```bash -git add .vortex/installer/composer.json +git add .vortex/cli/composer.json ``` ```bash -git add .vortex/installer/composer.lock +git add .vortex/cli/composer.lock ``` ```bash -git add .vortex/installer/patches.lock.json +git add .vortex/cli/patches.lock.json ``` ```bash -git add .vortex/installer/vendor-bin/box/composer.json +git add .vortex/cli/vendor-bin/box/composer.json ``` ```bash @@ -268,7 +268,7 @@ git add .vortex/tests/patches.lock.json git add .vortex/tests/yarn.lock ``` -Note that `.vortex/installer/vendor-bin/box/composer.lock` is gitignored (the whole `vendor-bin/` directory is excluded). Do not try to force-add it. +Note that `.vortex/cli/vendor-bin/box/composer.lock` is gitignored (the whole `vendor-bin/` directory is excluded). Do not try to force-add it. #### Stage auto-fix changes (if any) @@ -279,14 +279,14 @@ git diff --name-only .vortex/docs/src .vortex/docs/tests ``` ```bash -git diff --name-only .vortex/installer/src .vortex/installer/tests +git diff --name-only .vortex/cli/src .vortex/cli/tests ``` ```bash git diff --name-only .vortex/tests ``` -Stage each path the diff prints (one `git add ` per file - do not glob `.` or use `-A`). Restrict the discovery to in-scope subsystems (`.vortex/docs/`, `.vortex/installer/`, `.vortex/tests/`); anything under `.vortex/tooling/` MUST stay unstaged. +Stage each path the diff prints (one `git add ` per file - do not glob `.` or use `-A`). Restrict the discovery to in-scope subsystems (`.vortex/docs/`, `.vortex/cli/`, `.vortex/tests/`); anything under `.vortex/tooling/` MUST stay unstaged. #### Verify staging @@ -308,9 +308,9 @@ git commit -m "Refreshed '.vortex/' dev dependencies and lint-fix fallout for {S Invoke the `/open-pr` skill. The PR description must include: -1. **Scope statement** - one sentence: "Refreshes lock files under `.vortex/` for `docs` / `installer` / `tests`. No manifest constraint changes. `.vortex/tooling/` is out of scope." +1. **Scope statement** - one sentence: "Refreshes lock files under `.vortex/` for `docs` / `cli` / `tests`. No manifest constraint changes. `.vortex/tooling/` is out of scope." 2. **Subsystems touched** - bullet list of the three subsystems with a yes/no marker for Composer and Yarn changes (read from `git diff --stat`). -3. **Lint status** - one sentence confirming local lint passed for each updated subsystem (this is the gate for opening the PR at all). If Step 5 needed auto-fix, list briefly which subsystem(s) the lint-fix touched and roughly what was fixed (e.g. "phpcs array-indentation in installer, applied by `composer lint-fix`") so reviewers see source-code changes are deliberate. +3. **Lint status** - one sentence confirming local lint passed for each updated subsystem (this is the gate for opening the PR at all). If Step 5 needed auto-fix, list briefly which subsystem(s) the lint-fix touched and roughly what was fixed (e.g. "phpcs array-indentation in cli, applied by `composer lint-fix`") so reviewers see source-code changes are deliberate. 4. **Majors report** - paste the report content generated in Step 4 inline (the body of `majors.md` or the "No major versions available" line), so reviewers see what is available outside the constraints in the same place as the diff. Do NOT reference the `.artifacts/` path - those files are not staged and will not exist in the PR branch. The full Composer / Yarn output stays in `.artifacts/vortex-dev-deps-{slug}/update-log.txt` for local debugging only. Do not reference this path from the PR description and do not paste the log into the PR body. diff --git a/.docker/cli.dockerfile b/.docker/cli.dockerfile index bada8f9188..f48d66bb88 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 installer strips this block. +# get the package from packagist; the Vortex CLI strips this block. COPY .vortex/tooling /app/.vortex/tooling #;> VORTEX_DEV diff --git a/.gitattributes b/.gitattributes index 0baddba63c..640d3d9a96 100644 --- a/.gitattributes +++ b/.gitattributes @@ -8,6 +8,6 @@ /.vortex/.ahoy.yml export-ignore /.vortex/CLAUDE.md export-ignore /.vortex/README.md export-ignore +/.vortex/cli export-ignore /.vortex/docs export-ignore -/.vortex/installer export-ignore /.vortex/tests export-ignore diff --git a/.github/workflows/vortex-release.yml b/.github/workflows/vortex-release.yml index 45c94d1a5b..251d9a507d 100644 --- a/.github/workflows/vortex-release.yml +++ b/.github/workflows/vortex-release.yml @@ -7,6 +7,7 @@ on: - '*' branches: - '**release-docs**' + - '**release-cli**' - '**release-installer**' workflow_dispatch: inputs: @@ -21,7 +22,7 @@ concurrency: jobs: - vortex-release-installer: + vortex-release-cli: runs-on: ubuntu-latest permissions: @@ -56,7 +57,7 @@ jobs: - name: Install dependencies run: composer install - working-directory: .vortex/installer + working-directory: .vortex/cli - name: Set release version id: version @@ -73,7 +74,7 @@ jobs: echo "RELEASE_VERSION=$version" >> "$GITHUB_ENV" echo "value=$version" >> "$GITHUB_OUTPUT" echo "Release version: $version" - working-directory: .vortex/installer + working-directory: .vortex/cli env: INPUTS_VERSION: ${{ inputs.version }} REF_TYPE: ${{ github.ref_type }} @@ -82,27 +83,28 @@ jobs: - name: Build PHAR run: | - sed -i "s/\"vortex-installer-version\": \"development\"/\"vortex-installer-version\": \"${RELEASE_VERSION}\"/g" box.json + sed -i "s/\"vortex-cli-version\": \"development\"/\"vortex-cli-version\": \"${RELEASE_VERSION}\"/g" box.json composer build - working-directory: .vortex/installer + working-directory: .vortex/cli - name: Test PHAR run: | - ./build/installer.phar --version - ./build/installer.phar --no-interaction --no-cleanup --destination=test || exit 1 - working-directory: .vortex/installer + ./.build/vortex.phar --version + ./.build/vortex.phar install --no-interaction --no-cleanup --destination=test || exit 1 + working-directory: .vortex/cli - - name: Upload v${{ env.CURRENT_MAJOR }} installer artifact + - name: Upload v${{ env.CURRENT_MAJOR }} artifact uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: vortex-installer-v${{ env.CURRENT_MAJOR }} - path: .vortex/installer/build/installer.phar + path: .vortex/cli/.build/vortex.phar if-no-files-found: error - # Build the other major's installer from its '{N}.x' branch so it is - # published alongside the current one. Checked out into a separate path so - # the current installer build above is untouched. Mirrors how the docs job - # pulls the other major's branch content. + # Build the other major from its '{N}.x' branch so it is published + # alongside the current one. Checked out into a separate path so the + # build above is untouched. Mirrors how the docs job pulls the other + # major's branch content. Each major builds whatever it ships - the + # installer on '1.x', the CLI here - so this leg keeps its own paths. - name: Checkout v${{ env.OTHER_MAJOR }} branch uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 with: @@ -126,7 +128,7 @@ jobs: if-no-files-found: error vortex-release-docs: - needs: vortex-release-installer + needs: vortex-release-cli permissions: contents: read # Checkout the repository and build the documentation site. @@ -155,11 +157,11 @@ jobs: - name: Set version run: | - version="${NEEDS_VORTEX_RELEASE_INSTALLER_OUTPUTS_RELEASE_VERSION}" + version="${NEEDS_VORTEX_RELEASE_CLI_OUTPUTS_RELEASE_VERSION}" echo "RELEASE_VERSION=$version" >> "$GITHUB_ENV" echo "Release version: $version" env: - NEEDS_VORTEX_RELEASE_INSTALLER_OUTPUTS_RELEASE_VERSION: ${{ needs.vortex-release-installer.outputs.release-version }} + NEEDS_VORTEX_RELEASE_CLI_OUTPUTS_RELEASE_VERSION: ${{ needs.vortex-release-cli.outputs.release-version }} - name: Setup Node.js uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 @@ -183,20 +185,22 @@ jobs: name: vortex-installer-v2 path: installer-v2 - # Publish both installers. '/v1/install' and '/v2/install' are the stable + # Publish both majors. '/v1/install' and '/v2/install' are the stable # per-major pins, always built from each major's own source. The bare # '/install' is a copy of the current major's pin, selected by the # 'VORTEX_CURRENT_MAJOR' repository variable (default 1) - bumping that one # variable is the only action needed to promote a new major. - - name: Copy installers to docs + - name: Copy binaries to docs run: | case "${CURRENT_MAJOR}" in 1|2) ;; *) echo "Invalid VORTEX_CURRENT_MAJOR='${CURRENT_MAJOR}'. Expected 1 or 2."; exit 1 ;; esac mkdir -p ../.vortex/docs/static/v1 ../.vortex/docs/static/v2 - cp ../installer-v1/installer.phar ../.vortex/docs/static/v1/install - cp ../installer-v2/installer.phar ../.vortex/docs/static/v2/install + # Each artifact holds exactly one PHAR, but its filename depends on + # what that major ships, so it is matched rather than named. + cp ../installer-v1/*.phar ../.vortex/docs/static/v1/install + cp ../installer-v2/*.phar ../.vortex/docs/static/v2/install cp "../.vortex/docs/static/v${CURRENT_MAJOR}/install" ../.vortex/docs/static/install php ../.vortex/docs/static/install --version @@ -230,14 +234,14 @@ jobs: env: VORTEX_CURRENT_MAJOR: ${{ env.CURRENT_MAJOR }} - - name: Generate video for installer (not used in the final artifact) + - name: Generate video for the install demo (not used in the final artifact) run: | sudo apt-get update sudo apt install expect sudo curl -sSL https://github.com/asciinema/asciinema/releases/latest/download/asciinema-x86_64-unknown-linux-gnu -o /usr/local/bin/asciinema && sudo chmod +x /usr/local/bin/asciinema npm i -g sharp-cli yarn install --frozen-lockfile - php .utils/update-videos.php installer + php .utils/update-videos.php cli-install working-directory: .vortex/docs - name: Upload documentation site diff --git a/.github/workflows/vortex-test-installer.yml b/.github/workflows/vortex-test-cli.yml similarity index 80% rename from .github/workflows/vortex-test-installer.yml rename to .github/workflows/vortex-test-cli.yml index f5a5e3adca..b7aa4d49a1 100644 --- a/.github/workflows/vortex-test-installer.yml +++ b/.github/workflows/vortex-test-cli.yml @@ -1,5 +1,5 @@ # This action is used for Vortex maintenance. It will not be used in the scaffolded project. -name: Vortex - Test installer +name: Vortex - Test CLI on: push: @@ -22,7 +22,7 @@ concurrency: cancel-in-progress: true jobs: - vortex-test-installer: + vortex-test-cli: runs-on: ubuntu-latest permissions: @@ -59,23 +59,23 @@ jobs: - name: Install dependencies run: composer install - working-directory: .vortex/installer + working-directory: .vortex/cli - name: Validate Composer configuration is normalized run: composer normalize --dry-run - working-directory: .vortex/installer + working-directory: .vortex/cli - name: Check coding standards run: composer lint - working-directory: .vortex/installer + working-directory: .vortex/cli - name: Run tests run: composer test-coverage - working-directory: .vortex/installer + working-directory: .vortex/cli env: GITHUB_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }} - - name: Generate video for installer (not used in the final artifact) + - name: Generate video for the install demo (not used in the final artifact) if: matrix.php-versions == '8.2' run: | sudo apt-get update @@ -83,14 +83,14 @@ jobs: sudo curl -sSL https://github.com/asciinema/asciinema/releases/latest/download/asciinema-x86_64-unknown-linux-gnu -o /usr/local/bin/asciinema && sudo chmod +x /usr/local/bin/asciinema npm i -g sharp-cli yarn install --frozen-lockfile - php .utils/update-videos.php installer + php .utils/update-videos.php cli-install working-directory: .vortex/docs - name: Upload coverage reports as an artifact uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: ${{github.job}}-code-coverage-report-${{ matrix.php-versions }} - path: .vortex/installer/.logs + path: .vortex/cli/.logs include-hidden-files: true if-no-files-found: error @@ -98,27 +98,27 @@ jobs: uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7 continue-on-error: true with: - files: .vortex/installer/.logs/cobertura.xml + files: .vortex/cli/.logs/cobertura.xml fail_ci_if_error: true token: ${{ secrets.CODECOV_TOKEN }} # Smoke test for PHAR. - name: Build PHAR run: composer build - working-directory: .vortex/installer + working-directory: .vortex/cli - name: Test PHAR run: | - ./build/installer.phar --version - ./build/installer.phar --no-interaction --no-cleanup --destination=test || exit 1 - working-directory: .vortex/installer + ./.build/vortex.phar --version + ./.build/vortex.phar install --no-interaction --no-cleanup --destination=test || exit 1 + working-directory: .vortex/cli env: GITHUB_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }} - - name: Upload installer artifact + - name: Upload CLI artifact if: matrix.php-versions == '8.2' uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: - name: vortex-installer - path: .vortex/installer/build/installer.phar + name: vortex-cli + path: .vortex/cli/.build/vortex.phar if-no-files-found: error diff --git a/.github/workflows/vortex-test-common.yml b/.github/workflows/vortex-test-common.yml index 6f01e13b6f..a697ca4d39 100644 --- a/.github/workflows/vortex-test-common.yml +++ b/.github/workflows/vortex-test-common.yml @@ -261,7 +261,7 @@ jobs: - name: Check GitHub Actions security with Zizmor uses: zizmorcore/zizmor-action@6fc4b006235f201fdab3722e17240ab420d580e5 # v0.6.1 with: - # Audit only the template's own workflows. The installer test fixtures + # Audit only the template's own workflows. The CLI test fixtures # carry generated workflow snapshots whose action SHAs are normalized # to placeholders, which are not real pin targets. inputs: .github/workflows/ diff --git a/.github/workflows/vortex-test-docs.yml b/.github/workflows/vortex-test-docs.yml index be39e07c56..50e559cf25 100644 --- a/.github/workflows/vortex-test-docs.yml +++ b/.github/workflows/vortex-test-docs.yml @@ -3,19 +3,19 @@ name: Vortex - Test docs on: workflow_run: - workflows: ['Vortex - Test installer'] + workflows: ['Vortex - Test CLI'] types: - completed jobs: vortex-test-docs: runs-on: ubuntu-latest - # Only run if installer workflow succeeded + # Only run if the CLI workflow succeeded if: github.event.workflow_run.conclusion == 'success' permissions: contents: read # Checkout the repository at the triggering commit. - actions: read # Download the installer artifact from the test-installer workflow run. + actions: read # Download the CLI artifact from the test-cli workflow run. statuses: write # Post pending/final commit statuses via 'gh api repos/.../statuses/...'. pull-requests: write # Post the Netlify preview link comment on the originating PR. @@ -55,18 +55,18 @@ jobs: with: php-version: 8.3 - - name: Download installer artifact + - name: Download CLI artifact uses: dawidd6/action-download-artifact@b6e2e70617bc3265edd6dab6c906732b2f1ae151 # v21 with: - workflow: vortex-test-installer.yml - name: vortex-installer + workflow: vortex-test-cli.yml + name: vortex-cli path: .vortex/docs/static if_no_artifact_found: fail allow_forks: true - - name: Copy installer to docs + - name: Copy the CLI to docs run: | - mv .vortex/docs/static/installer.phar .vortex/docs/static/install + mv .vortex/docs/static/vortex.phar .vortex/docs/static/install php .vortex/docs/static/install --version - name: Check docs up-to-date @@ -107,12 +107,13 @@ jobs: git -C "${{ github.workspace }}" checkout "origin/${OTHER_MAJOR}.x" -- .vortex/docs/content || { echo "Failed to check out content from ${OTHER_MAJOR}.x."; exit 1; } working-directory: '${{ github.workspace }}/.vortex/docs' - # On the main deploy, publish both installers to match the multi-version + # On the main deploy, publish both majors to match the multi-version # docs: '/v1/install' and '/v2/install' are the stable per-major pins and # the bare '/install' is a copy of the current major's pin (the - # 'VORTEX_CURRENT_MAJOR' repository variable, default 1). The downloaded - # installer above is the current major (built from 'main'); the other - # major is built from its '{N}.x' branch. Mirrors 'vortex-release.yml'. + # 'VORTEX_CURRENT_MAJOR' repository variable, default 1). The artifact + # downloaded above is the current major (built from 'main'); the other + # major is built from its '{N}.x' branch, where it still ships the + # installer rather than the CLI. Mirrors 'vortex-release.yml'. - name: Checkout v${{ env.OTHER_MAJOR }} branch if: github.event.workflow_run.head_branch == 'main' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 diff --git a/.vortex/.ahoy.yml b/.vortex/.ahoy.yml index c206294f72..55e5dc7c2b 100644 --- a/.vortex/.ahoy.yml +++ b/.vortex/.ahoy.yml @@ -12,8 +12,8 @@ commands: yarn --cwd=tests install --frozen-lockfile [ -d ./tooling/vendor ] && rm -rf ./tooling/vendor composer --working-dir tooling install - [ -d ./installer/vendor ] && rm -rf ./installer/vendor - composer --working-dir installer install + [ -d ./cli/vendor ] && rm -rf ./cli/vendor + composer --working-dir cli install [ -d ./docs/node_modules ] && rm -rf ./docs/node_modules yarn --cwd=docs install --frozen-lockfile @@ -35,16 +35,16 @@ commands: [ ! -d ./docs/node_modules ] && yarn --cwd=docs install --frozen-lockfile yarn --cwd=docs run build - build-installer: - name: Build documentation. + build-cli: + name: Build the Vortex CLI PHAR. cmd: | - [ ! -d ./installer/vendor ] && composer --working-dir installer install - composer --working-dir installer build + [ ! -d ./cli/vendor ] && composer --working-dir cli install + composer --working-dir cli build lint: name: Lint Vortex project. cmd: | - ahoy lint-installer + ahoy lint-cli ahoy lint-tests ahoy lint-tooling ahoy lint-scripts @@ -56,7 +56,7 @@ commands: lint-fix: name: Fix linting issues in Vortex project. cmd: | - ahoy lint-installer-fix + ahoy lint-cli-fix ahoy lint-tests-fix ahoy lint-tooling-fix ahoy lint-docs-fix @@ -69,11 +69,11 @@ commands: lint-ci-fix: cmd: ./tests/lint.ci.sh --fix - lint-installer: - cmd: composer --working-dir installer lint + lint-cli: + cmd: composer --working-dir cli lint - lint-installer-fix: - cmd: composer --working-dir installer lint-fix + lint-cli-fix: + cmd: composer --working-dir cli lint-fix lint-tests: cmd: composer --working-dir tests lint @@ -130,7 +130,7 @@ commands: cmd: | export XDEBUG_MODE=off composer --working-dir=tests update-snapshots - composer --working-dir=installer update-snapshots -- --jobs=8 + composer --working-dir=cli update-snapshots -- --jobs=8 update-snapshots-install: aliases: [usi] @@ -143,7 +143,7 @@ commands: cmd: yarn --cwd=docs run update-variables update-videos: - usage: Update documentation videos. Pass names to record a subset (installer, build, provision, lint, test, test-bdd); default is all six. + usage: Update documentation videos. Pass names to record a subset (cli-install, build, provision, lint, test, test-bdd); default is all six. cmd: php docs/.utils/update-videos.php "$@" entrypoint: diff --git a/.vortex/CLAUDE.md b/.vortex/CLAUDE.md index a38c6dc221..4749f39dfe 100644 --- a/.vortex/CLAUDE.md +++ b/.vortex/CLAUDE.md @@ -9,7 +9,7 @@ vortex/ ├── .vortex/ # Test harness (removed on install) │ ├── docs/ # Documentation website -│ ├── installer/ # Template installer +│ ├── cli/ # Template CLI │ ├── tests/ # Template tests (PHPUnit) │ └── tooling/ # 'drevops/vortex-tooling' Composer package │ ├── src/ # Shipped PHP scripts @@ -26,14 +26,14 @@ test harness. | System | Technology | Purpose | |--------------|--------------------------|-------------------------------| | `docs/` | Docusaurus, Jest | vortextemplate.com | -| `installer/` | Symfony Console, PHPUnit | Template customization | +| `cli/` | Symfony Console, PHPUnit | Template customization | | `tests/` | PHPUnit | Template integration testing | | `tooling/` | PHP, PHPUnit | 'drevops/vortex-tooling' pkg | Each subsystem has its own CLAUDE.md - read it when working there: - `.vortex/docs/CLAUDE.md` - Documentation system, videos -- `.vortex/installer/CLAUDE.md` - Installer, fixtures, tokens +- `.vortex/cli/CLAUDE.md` - CLI, fixtures, tokens - `.vortex/tests/CLAUDE.md` - PHPUnit integration tests `tooling/` has no CLAUDE.md - it is published to consumer projects, so any notes @@ -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 installer strips that path repository from +resolves during development. The CLI 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 @@ -119,7 +119,7 @@ ahoy lint-markdown # Lint markdown files ## Snapshots `ahoy update-snapshots` (run from `.vortex/`) is the **only** way to regenerate -fixtures. It wraps the `tests/` and `installer/` snapshot runs together with the +fixtures. It wraps the `tests/` and `cli/` snapshot runs together with the required `XDEBUG_MODE=off` and parallel jobs. Never call `composer update-snapshots` directly and never set `UPDATE_SNAPSHOTS` by hand - both bypass part of the workflow and produce partial, inconsistent fixtures. @@ -153,21 +153,21 @@ When updating template files (settings, configs, Dockerfiles, etc.): 2. **Commit.** 3. Run `ahoy update-snapshots` and commit the regenerated fixtures. -When the installer prompt flow changes (any change under -`.vortex/installer/src/Prompts/` - new or removed handler, reordered or reworded -prompt, `TOTAL_RESPONSES` bump), also run `ahoy update-videos installer` to +When the prompt flow changes (any change under +`.vortex/cli/src/Prompts/` - new or removed handler, reordered or reworded +prompt, `TOTAL_RESPONSES` bump), also run `ahoy update-videos cli-install` to re-record the demo, since the video records the live prompt flow. `update-snapshots` commits automatically; `update-videos` does not - stage and commit its output manually. Run both after the code change is committed. ## Documentation videos -Six terminal demo videos live in `.vortex/docs/static/img/` (`installer.*`, +Six terminal demo videos live in `.vortex/docs/static/img/` (`cli-install.*`, `build.*`, `provision.*`, `lint.*`, `test.*`, `test-bdd.*`). Regenerate from `.vortex/` with `ahoy update-videos [names]`. A video goes stale when the command it records changes behavior: -- `installer` - any prompt flow change. +- `cli-install` - any prompt flow change. - `build`, `provision` - changes to `.ahoy.yml` build/provision targets or `scripts/vortex/provision*`. - `lint`, `test`, `test-bdd` - changes to the linter or test-runner setup. @@ -185,7 +185,7 @@ and commit manually. See `.vortex/docs/CLAUDE.md` for the pipeline internals ## AI Assistant Guidelines -- **NEVER** modify `.vortex/installer/tests/Fixtures/` directly - change the root +- **NEVER** modify `.vortex/cli/tests/Fixtures/` directly - change the root template files, then run `ahoy update-snapshots`. - American English spelling in documentation; sentence case for headings (capitalize proper nouns only). diff --git a/.vortex/README.md b/.vortex/README.md index a992f669e8..fc4d7986b5 100644 --- a/.vortex/README.md +++ b/.vortex/README.md @@ -1,10 +1,10 @@ # Vortex development This directory contains development files for Vortex itself. -This directory is removed by the installer or can be deleted manually. +This directory is removed by the Vortex CLI or can be deleted manually. - [`docs`](docs) - documentation for Vortex published to https://www.vortextemplate.com -- [`installer`](installer) - self-contained Symfony console application used to install Vortex +- [`cli`](cli) - self-contained Symfony console application used to install Vortex - [`tests`](tests) - unit and functional tests for Vortex - [`tooling`](tooling) - scripts that ship with Vortex, deployed as the `drevops/vortex-tooling` package to https://github.com/drevops/vortex-tooling diff --git a/.vortex/installer/.gitignore b/.vortex/cli/.gitignore similarity index 88% rename from .vortex/installer/.gitignore rename to .vortex/cli/.gitignore index d1e9f04891..fb851358da 100644 --- a/.vortex/installer/.gitignore +++ b/.vortex/cli/.gitignore @@ -1,6 +1,6 @@ !/composer.lock +/.build /.logs /.phpunit.cache -/build /vendor /vendor-bin diff --git a/.vortex/installer/CLAUDE.md b/.vortex/cli/CLAUDE.md similarity index 86% rename from .vortex/installer/CLAUDE.md rename to .vortex/cli/CLAUDE.md index 06d6e0bebf..148235fc62 100644 --- a/.vortex/installer/CLAUDE.md +++ b/.vortex/cli/CLAUDE.md @@ -1,4 +1,4 @@ -# Installer System Guide +# CLI System Guide ## Overview @@ -10,7 +10,7 @@ selections. ## Commands ```bash -cd .vortex/installer +cd .vortex/cli composer install # Install dependencies composer lint # Run phpcs, phpstan, rector --dry-run @@ -46,20 +46,20 @@ template files, then regenerate the fixtures. See `.vortex/CLAUDE.md` for the snapshot update process (always `ahoy update-snapshots` from `.vortex/`, never composer directly). -### Updating the Installer Video +### Updating the install demo video -**Whenever the installer prompt flow changes** (new handler added, prompt -renamed, section reordered, prompt removed), the installer video shown in the -documentation goes stale and must be regenerated. +**Whenever the prompt flow changes** (new handler added, prompt +renamed, section reordered, prompt removed), the install demo video shown in +the documentation goes stale and must be regenerated. ```bash # From .vortex/ directory -ahoy update-videos installer +ahoy update-videos cli-install ``` Requires `asciinema`, `expect`, `php`, `composer`, `npx` on PATH. Produces -`installer.json` (asciicast), `installer.svg`, `installer.png`, and -`installer.gif` under `.vortex/docs/static/img/`. Requires explicit user +`cli-install.json` (asciicast), `cli-install.svg`, `cli-install.png`, and +`cli-install.gif` under `.vortex/docs/static/img/`. Requires explicit user permission before running. Triggers that require re-recording: @@ -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 installer removes the whole +**Do not** wrap an entire file in fences if the CLI 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: @@ -125,7 +125,7 @@ Content removed if feature not selected ### Handler Locations -`.vortex/installer/src/Prompts/Handlers/`: +`.vortex/cli/src/Prompts/Handlers/`: - `CiProvider.php`, `HostingProvider.php`, `Services.php`, `Theme.php` @@ -164,7 +164,7 @@ Structure: Test methods → Data providers → Helper methods ## Patches -The installer applies a single patch to `laravel/prompts` via +The CLI applies a single patch to `laravel/prompts` via `cweagans/composer-patches` v2 to add three behaviors it depends on. ### Patch location @@ -192,7 +192,7 @@ The installer applies a single patch to `laravel/prompts` via The patch also includes a small `Concerns/TypedValue.php` tweak (`strlen($default) > 0` → truthy check); not exercised directly by the -installer. +CLI. ### Re-roll procedure @@ -202,13 +202,13 @@ description trait touches renderers that frequently change between releases. ```bash -# 1. After bumping the version in .vortex/installer/composer.json, try the +# 1. After bumping the version in .vortex/cli/composer.json, try the # existing patch first. -composer --working-dir .vortex/installer update laravel/prompts --with-dependencies +composer --working-dir .vortex/cli update laravel/prompts --with-dependencies rm -f ~/Library/Caches/composer/patches/*.patch # macOS cache path rm -f ~/.cache/composer/patches/*.patch # Linux cache path -composer --working-dir .vortex/installer patches-relock -composer --working-dir .vortex/installer patches-repatch +composer --working-dir .vortex/cli patches-relock +composer --working-dir .vortex/cli patches-repatch ``` If `patches-repatch` succeeds, jump to the verify step. @@ -223,7 +223,7 @@ git -C /tmp/prompts-upstream checkout v cp -R /tmp/prompts-upstream/src /tmp/upstream-pristine-src # 3. Apply the three changes to /tmp/prompts-upstream/src using -# .vortex/installer/patches/laravel-prompts.patch as reference: +# .vortex/cli/patches/laravel-prompts.patch as reference: # a) Re-introduce the RendersDescription trait and thread `description` # through every Prompt constructor + matching renderer. # b) Update Prompt::validateUsing() signature to `?Closure $callback`. @@ -235,22 +235,22 @@ diff -ruN /tmp/upstream-pristine-src /tmp/prompts-upstream/src > /tmp/raw.patch # 5. Re-root paths to `a/src/...` / `b/src/...` and strip timestamps using # the committed helper. -php .vortex/installer/patches/reroot-patch.php \ +php .vortex/cli/patches/reroot-patch.php \ /tmp/raw.patch \ - .vortex/installer/patches/laravel-prompts.patch \ + .vortex/cli/patches/laravel-prompts.patch \ /tmp/upstream-pristine-src/ \ /tmp/prompts-upstream/src/ # 6. Refresh the lockfile and re-apply. rm -f ~/Library/Caches/composer/patches/*.patch rm -f ~/.cache/composer/patches/*.patch -composer --working-dir .vortex/installer patches-relock -composer --working-dir .vortex/installer patches-repatch +composer --working-dir .vortex/cli patches-relock +composer --working-dir .vortex/cli patches-repatch ``` Verify: ```bash -composer --working-dir .vortex/installer test -composer --working-dir .vortex/installer lint +composer --working-dir .vortex/cli test +composer --working-dir .vortex/cli lint ``` diff --git a/.vortex/installer/README.md b/.vortex/cli/README.md similarity index 100% rename from .vortex/installer/README.md rename to .vortex/cli/README.md diff --git a/.vortex/installer/box.json b/.vortex/cli/box.json similarity index 69% rename from .vortex/installer/box.json rename to .vortex/cli/box.json index e35b6501fb..35918f7fdf 100644 --- a/.vortex/installer/box.json +++ b/.vortex/cli/box.json @@ -1,13 +1,13 @@ { - "output": "build/installer.phar", + "output": ".build/vortex.phar", "banner": [ "@file", - "Vortex CLI Installer.", + "Vortex CLI.", "", "", - "CLI Installer for Vortex project.
", + "CLI for Vortex project.
", "Run in your terminal:
", - "curl -SsL https://www.vortextemplate.com/install > installer.php && php installer.php
", + "curl -SsL https://www.vortextemplate.com/install > vortex.phar && php vortex.phar
", "More details: https://www.vortextemplate.com", "