Update Vortex Dev Deps

Update Vortex Dev Dependencies

Refresh Composer and Yarn dependencies across three .vortex/ subsystems, run each subsystem's local lint, generate a major-versions-available report, and open a pull request. Local lint must pass before pushing; local tests are intentionally skipped because CI runs them already and is the source of truth.

When to Use

• User says 'update vortex dev deps', 'refresh .vortex dependencies', 'bump .vortex lock files'.
• A periodic maintenance pass on the Vortex template's test harness.

Do NOT use for:

• The root project's dependencies (those are handled by Renovate and prepare-vortex-release).
• Major version bumps inside .vortex/ manifests. This skill only refreshes lock files within existing constraints; the majors report flags what would need a manual bump.
• .vortex/tooling/. That directory ships as the standalone drevops/vortex-tooling Composer library - it does not commit a composer.lock, its yarn.lock is for BATS only, and its dependencies are resolved by consumer projects via Packagist. Touching it here would produce local-only artefacts that should never land in a PR.

Scope

This skill touches files under exactly three .vortex/ subsystems:

• .vortex/docs/ (Yarn)
• .vortex/installer/ (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.

Manifests (composer.json, package.json) are not edited by hand. Only lock files (composer.lock, yarn.lock, patches.lock.json) change. A composer.json will only change if it has bump-after-update configured; in that case stage and commit it along with its lock file.

Prerequisites

• Composer 2.x available on the host.
• Yarn 1.x available on the host.
• gh CLI authenticated.
• Working tree clean.

Naming Convention

Branch and artifact names use a slug derived from the current month and year. Compute it once:

date +"%B-%Y"

Lowercase the result (e.g. May-2026 becomes may-2026).

• Branch: feature/vortex-dev-deps-{slug}
• Artifact directory: .artifacts/vortex-dev-deps-{slug}/
• Update log: .artifacts/vortex-dev-deps-{slug}/update-log.txt
• Majors report: .artifacts/vortex-dev-deps-{slug}/majors.md

Subsystem Matrix

Process in fixed order. Smallest blast radius first. Lint commands run from the project root; lint-fix commands also run from the project root.

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.

Workflow

Step 1: Prepare

Check the working tree is clean:

git status

If uncommitted changes exist, STOP and ask the user before proceeding.

Determine the slug (e.g. may-2026).

Create the artifact directory:

mkdir -p .artifacts/vortex-dev-deps-{slug}

Step 2: Create feature branch

Detect the default branch:

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

Fall back to main if gh fails.

git checkout {default-branch}

git pull origin {default-branch}

git checkout -b feature/vortex-dev-deps-{slug}

Step 3: Refresh dependencies

Process the matrix in order. For each row, run the applicable commands below from the project root. Append every command's full output to .artifacts/vortex-dev-deps-{slug}/update-log.txt with a clear ### {subsystem} heading per subsystem.

composer update (no package args, no --with-all-dependencies) and yarn upgrade (no --latest) both honour existing version constraints. Manifests should not change unless composer.json has bump-after-update.

3.1 - docs (Yarn only):

yarn --cwd .vortex/docs upgrade

3.2 - installer (Composer, plus sub-composer):

composer --working-dir .vortex/installer update

composer --working-dir .vortex/installer/vendor-bin/box update

3.3 - tests (Composer + Yarn):

composer --working-dir .vortex/tests update

yarn --cwd .vortex/tests upgrade

On command failure (dependency resolution conflict, registry error, etc.): STOP, report which subsystem and which command failed and the relevant error excerpt, leave the working tree as-is so the user can investigate. Do NOT proceed to the next subsystem and do NOT delete the partial diff.

Step 4: Generate majors-available report

For each Composer manifest in the matrix (including the vendor-bin/box one):

composer --working-dir <subsystem> outdated --direct --major-only --format=json

For each Yarn manifest in the matrix:

yarn --cwd <subsystem> outdated --json

yarn outdated exits with status 1 when outdated packages are found. That is expected output, not a failure.

Parse the outputs and write .artifacts/vortex-dev-deps-{slug}/majors.md with one table per subsystem-manager pair that has any major upgrade available. Include only packages whose latest major is strictly greater than the installed major (Composer's --major-only already filters this; for Yarn, compare current and latest semver majors). If a pair has nothing, omit its table.

Format:

# Major versions available

## `.vortex/docs` (Yarn)

| Package | Installed | Latest |
|---------|-----------|--------|
| @docusaurus/core | 3.4.0 | 4.0.1 |

## `.vortex/installer` (Composer)

| Package | Installed | Latest |
|---------|-----------|--------|
| symfony/console | 6.4.0 | 7.0.0 |

If no subsystem has any major available, write a single line:

No major versions available outside current constraints.

Step 5: Lint each updated subsystem (with auto-fix)

Lint MUST pass locally before committing or pushing. Tests do NOT run locally - CI is the source of truth for tests.

Run the lint commands from the matrix in the same order as Step 3, from the project root.

5.1 - docs:

yarn --cwd .vortex/docs run lint

yarn --cwd .vortex/docs run spellcheck

5.2 - installer:

composer --working-dir .vortex/installer lint

5.3 - tests:

composer --working-dir .vortex/tests lint

On lint failure

A dependency refresh frequently surfaces lint violations because a code-style tool (phpcs/Drupal coder, eslint, prettier, rector) was upgraded and a previously-stable rule got stricter, or a new rule was added. The first response is always to attempt the subsystem's auto-fix, not to give up.

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
• 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:

1. Lint now passes. Carry the auto-fixed source changes into the same commit as the dependency refresh in Step 6. They are part of "what this update did" and reviewers should see them together with the lock changes.
2. Lint still fails. STOP. Report which subsystem and which rules are still failing, with the relevant excerpt. Do NOT commit, do NOT push, do NOT open a PR. Leave the working tree as-is so the user can investigate. The remaining failures are real issues that need a manual fix (or an explicit decision to suppress / pin / revert the upgrade).

If the lint failure looks completely unrelated to the dependency refresh (the upgraded packages have nothing to do with linting), surface that to the user before continuing - the dependency refresh PR is not the right place to fix unrelated lint debt.

Step 6: Commit

Stage the dependency files first. Never git add . or git add -A.

git add .vortex/docs/yarn.lock

git add .vortex/installer/composer.json

git add .vortex/installer/composer.lock

git add .vortex/installer/patches.lock.json

git add .vortex/installer/vendor-bin/box/composer.json

git add .vortex/tests/composer.json

git add .vortex/tests/composer.lock

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.