Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
22 changes: 11 additions & 11 deletions .claude/skills/prepare-vortex-release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -193,7 +193,7 @@ Summary paragraph (1-3 sentences).

---

### 🎛 Installer
### 🎛 CLI

(same sub-sections)

Expand Down Expand Up @@ -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:
Expand All @@ -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

Expand Down
8 changes: 4 additions & 4 deletions .claude/skills/propagate-vortex-main-to-2x/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
40 changes: 20 additions & 20 deletions .claude/skills/update-vortex-dev-deps/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
---

Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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):**
Expand Down Expand Up @@ -170,7 +170,7 @@ Format:
|---------|-----------|--------|
| @docusaurus/core | 3.4.0 | 4.0.1 |

## `.vortex/installer` (Composer)
## `.vortex/cli` (Composer)

| Package | Installed | Latest |
|---------|-----------|--------|
Expand Down Expand Up @@ -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:**
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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)

Expand All @@ -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 <path>` 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 <path>` 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

Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion .docker/cli.dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading