add-ecosystem-ci - SKILL.md Agent Skill

name: add-ecosystem-ci description: Add a new ecosystem-ci test case for testing real-world projects against vite-plus allowed-tools: Bash, Read, Edit, Write, WebFetch, AskUserQuestion

Add Ecosystem-CI Test Case

Add a new ecosystem-ci test case following this process:

Step 1: Get Repository Information

Ask the user for the GitHub repository URL if not provided as argument: $ARGUMENTS

Use GitHub CLI to get repository info:

gh api repos/OWNER/REPO --jq '.default_branch'
gh api repos/OWNER/REPO/commits/BRANCH --jq '.sha'

Step 2: Auto-detect Project Configuration

2.1 Check for Subdirectory

Fetch the repository's root to check if the main package.json is in a subdirectory (like web/, app/, frontend/).

2.2 Check if Project Already Uses Vite-Plus

Check the project's root package.json for vite-plus in dependencies or devDependencies. If the project already uses vite-plus, set forceFreshMigration: true in repo.json. This tells patch-project.ts to set VITE_PLUS_FORCE_MIGRATE=1 so vp migrate forces full dependency rewriting instead of skipping with "already using Vite+".

2.3 Auto-detect Commands from GitHub Workflows

Fetch the project's GitHub workflow files to detect available commands:

# List workflow files
gh api repos/OWNER/REPO/contents/.github/workflows --jq '.[].name'

# Fetch workflow content (for each .yml/.yaml file)
gh api repos/OWNER/REPO/contents/.github/workflows/ci.yml --jq '.content' | base64 -d

Look for common patterns in workflow files:

pnpm run <command> / npm run <command> / yarn <command>
Commands like: lint, build, test, type-check, typecheck, format, format:check
Map detected commands to vp equivalents: vp run lint, vp run build, etc.

2.4 Ask User to Confirm

Present the auto-detected configuration and ask user to confirm or modify:

Which directory contains the main package.json? (auto-detected or manual)
What Node.js version to use? (22 or 24, try to detect from workflow)
Which commands to run? (show detected commands as multi-select options)
Which OS to run on? (both, ubuntu-only, windows-only) - default: both

Step 3: Update Files

Add to ecosystem-ci/repo.json:

{
  "project-name": {
    "repository": "https://github.com/owner/repo.git",
    "branch": "main",
    "hash": "full-commit-sha",
    "directory": "web", // only if subdirectory is needed
    "forceFreshMigration": true // only if project already uses vite-plus
  }
}

Add to .github/workflows/e2e-test.yml matrix:

- name: project-name
  node-version: 24
  directory: web # only if subdirectory is needed
  command: |
    vp run lint
    vp run build

Step 4: Verify

4.1 Build fresh tgz packages

Always rebuild tgz packages from latest source to avoid using stale cached versions:

# Rebuild the global CLI first (includes Rust binary + NAPI binding)
pnpm bootstrap-cli

# Pack fresh tgz files into tmp/tgz/
rm -rf tmp/tgz && mkdir -p tmp/tgz
cd packages/core && pnpm pack --pack-destination ../../tmp/tgz && cd ../..
cd packages/test && pnpm pack --pack-destination ../../tmp/tgz && cd ../..
cd packages/cli && pnpm pack --pack-destination ../../tmp/tgz && cd ../..
ls -la tmp/tgz

4.2 Clone and test locally

node ecosystem-ci/clone.ts project-name

4.3 Patch and run commands

# Run from the ecosystem-ci temp directory
cd $(node -e "const os=require('os'); console.log(os.tmpdir() + '/vite-plus-ecosystem-ci')")

# Migrate the project (uses tgz files from tmp/tgz/)
node /path/to/vite-plus/ecosystem-ci/patch-project.ts project-name

# Run the configured commands
cd project-name
vp run build

Add OS exclusion to .github/workflows/e2e-test.yml (if not running on both):

For ubuntu-only:

exclude:
  - os: windows-latest
    project:
      name: project-name

For windows-only:

exclude:
  - os: ubuntu-latest
    project:
      name: project-name

Important Notes

The directory field is optional - only add it if the package.json is not in the project root
If directory is specified in repo.json, it must also be specified in the workflow matrix
patch-project.ts automatically handles running vp migrate in the correct directory
forceFreshMigration is required for projects that already have vite-plus in their package.json — it sets VITE_PLUS_FORCE_MIGRATE=1 so vp migrate forces full dependency rewriting instead of skipping
OS exclusions are added to the existing exclude section in the workflow matrix