feat: align GitLab and Azure setup features

.github/workflows/test.yml

@@ -854,6 +854,24 @@ jobs:
           fi
           echo "OK: composed sfw blocked lodahs (exit $CODE, block-line found)"
 
+  test-gitlab-cache-snapshot:
+    name: GitLab cache snapshot regression (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.15.0
+      - name: Verify repeated saves with Bun-style directory symlinks
+        run: node --test test/cache-snapshot.test.mjs
+
   test-azure-runtime:
     strategy:
       fail-fast: false
@@ -889,6 +907,21 @@ jobs:
         shell: pwsh
         run: |
           [scriptblock]::Create((Get-Content -Raw azure/bootstrap.ps1)) > $null
+          [scriptblock]::Create((Get-Content -Raw gitlab/bootstrap.ps1)) > $null
+
+  test-portable-process:
+    name: Portable Windows command and cache regressions
+    runs-on: windows-latest
+    env:
+      VP_PR_VERSION: ""
+    steps:
+      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2
+      - name: Setup Vite+ and test dependencies
+        uses: ./
+        with:
+          node-version-file: .node-version
+      - name: Test native Windows executables and cache links
+        run: vp run test src/ci/process.test.ts src/ci/cache-snapshot.test.ts
 
   build:
     runs-on: ubuntu-latest

AGENTS.md

@@ -4,72 +4,70 @@ This file provides guidance to coding agents working in this repository.
 
 ## Guidelines
 
-- Do not commit changes automatically. Wait for an explicit user request to commit.
-- Keep `dist/index.mjs`, `dist/gitlab/index.mjs`, and `dist/azure/index.mjs` in sync with source changes by running `vp run build` before committing.
+- Follow [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and release procedures.
+- Do not commit without an explicit request. A request to push authorizes staging, committing, and pushing the current task changes; exclude unrelated changes.
+- Run `vp run check:fix` and `vp run build` before committing. Commit generated changes to `dist/index.mjs`, `dist/gitlab/index.mjs`, and `dist/azure/index.mjs` with their source changes. Do not edit the bundles by hand.
 
-## Project Overview
+## Documentation
 
-GitHub Action to set up [Vite+](https://viteplus.dev) (`vp`) with dependency caching support. The action installs Vite+ globally, can set up Node.js via `vp env use`, optionally configures registry auth, restores/saves dependency cache, and can run `vp install` with optional Socket Firewall Free (`sfw`) wrapping. GitLab and Azure Pipelines entry points reuse a dependency-light portable runtime under `src/ci/`.
+- Keep [README.md](README.md) focused on user-facing setup, configuration, examples, and behavior.
+- Put development commands, contribution requirements, E2E procedures, dependency maintenance, and release instructions in [CONTRIBUTING.md](CONTRIBUTING.md).
+- Keep detailed design decisions and integration proposals in [`rfcs/`](rfcs/). Link to them from the contributor guide.
+- Keep `AGENTS.md` focused on agent rules, code navigation, and implementation constraints. Link to contributor procedures instead of repeating them.
 
-## Commands
+Keep the README's Contributing section as a link to the contributor guide. Do not duplicate contributor procedures in the README.
 
-```bash
-# Build (required before committing - outputs to dist/)
-vp run build
+## Project Overview
 
-# Type check
-vp run typecheck
+setup-vp provides a GitHub Action, GitLab CI/CD remote templates, and an Azure Pipelines step template to install [Vite+](https://viteplus.dev) (`vp`). The integrations support version resolution, Node.js and package-manager management, registry auth, dependency caching, and `vp install` with optional Socket Firewall Free (`sfw`) wrapping.
 
-# Run tests
-vp run test
+## Architecture
 
-# Run tests in watch mode
-vp run test:watch
+| Integration     | Entry point           | Bundle                  | Phases                                               |
+| --------------- | --------------------- | ----------------------- | ---------------------------------------------------- |
+| GitHub Actions  | `src/index.ts`        | `dist/index.mjs`        | `runMain` / `runPost`, selected through action state |
+| GitLab CI/CD    | `src/gitlab/index.ts` | `dist/gitlab/index.mjs` | `setup` / `save-cache`                               |
+| Azure Pipelines | `src/azure/index.ts`  | `dist/azure/index.mjs`  | `prepare` / `finalize`                               |
 
-# Check (lint + format)
-vp run check
-vp run check:fix
-```
+- GitHub: `runMain` handles setup and installation. `runPost` saves dependency caches through `@actions/cache` when both `cache` and `cache-save` are enabled.
+- GitLab: `setup` installs and configures `vp`, runs dependency installation, and writes shell exports and public dotenv outputs. `.setup-vp-cached` uses native GitLab caching around project-local snapshots; `save-cache` updates the snapshot in `after_script` without restoring stale data first.
+- Azure: `prepare` installs `vp`, configures Node.js and package-manager modes, and exports cache metadata. Native `Cache@2` tasks run before `finalize`, which configures auth, runs installation, and publishes outputs. The finalize tasks use the saved bootstrap Node executable.
 
-**Important:** Always run `vp run check:fix` and `vp run build` before committing. The compiled `dist/index.mjs` must be committed when source changes affect the action bundle.
+### Public Interfaces
 
-## Architecture
+Keep input parsing, templates, bootstrap scripts, and README examples aligned when changing an interface.
 
-The action has main and post execution phases. Both are served by `src/index.ts` / `dist/index.mjs`; the phase is selected from GitHub Actions runtime state.
+- GitHub: `action.yml`, `src/inputs.ts`, and `src/types.ts`. The Zod schemas validate `run-install`; shared parsers validate Node.js and package-manager modes.
+- GitLab: `gitlab/setup-vp.yml`, `gitlab/setup-vp-windows.yml`, and `gitlab/bootstrap.sh` / `gitlab/bootstrap.ps1`. The runtime reads `SETUP_VP_*` variables; Unix and Windows templates must expose matching inputs.
+- Azure: `azure/setup-vp.yml`, `azure/bootstrap.sh` / `azure/bootstrap.ps1`, and `src/azure/inputs.ts`.
 
-- **Main phase** (`runMain`):
-  1. Parse and validate inputs.
-  2. Install Vite+ globally via official bash/PowerShell install scripts.
-  3. Set up Node.js with `vp env use` when requested.
-  4. Configure registry auth from `registry-url`, or propagate auth from the project `.npmrc`.
-  5. Restore dependency cache when enabled.
-  6. Run `vp install` when requested, optionally wrapped with `sfw`.
+### Key Modules
 
-- **Post phase** (`runPost`):
-  1. Save dependency cache when enabled.
+- `src/ci/version-file.ts`, `src/ci/lockfile-version.ts`, and `src/ci/node-version-file.ts` - Shared version resolvers. The matching files under `src/` adapt them to GitHub logging and workspace context.
+- `src/ci/node-manager.ts` / `src/ci/package-manager.ts` - Shared input parsing and version-dependent environment-mode commands.
+- `src/ci/install-viteplus.ts`, `src/ci/install-script-urls.ts`, and `src/ci/vp-dirs.ts` - Portable installer, script selection, and installed-directory detection. `src/install-viteplus.ts` is the GitHub installer adapter.
+- `src/ci/auth.ts` / `src/ci/npmrc.ts` - Portable authentication and shared `.npmrc` analysis. `src/auth.ts` handles GitHub environment exports.
+- `src/ci/run-install.ts` / `src/ci/install-sfw.ts` - Portable dependency installation and SFW setup. `src/run-install.ts` / `src/install-sfw.ts` provide GitHub-specific execution and caching.
+- `src/ci/cache.ts` / `src/ci/cache-snapshot.ts` - Portable cache metadata and GitLab snapshots. `src/cache-restore.ts` / `src/cache-save.ts` use the GitHub cache service; `src/utils.ts` contains GitHub cache-path and lock-file helpers.
+- `src/ci/process.ts`, `src/gitlab/shell.ts`, and `src/azure/commands.ts` - Native process execution and platform-specific environment/output exports.
 
-### Key Modules
+### Implementation Constraints
 
-- `src/index.ts` - Main/post orchestration and action state handling.
-- `src/inputs.ts` - Parse and validate action inputs using Zod schemas.
-- `src/types.ts` - Shared types, enums, and Zod schemas.
-- `src/install-viteplus.ts` - Install Vite+ globally via official install scripts.
-- `src/node-version-file.ts` - Resolve Node.js versions from supported version files.
-- `src/auth.ts` - Configure npm registry authentication from action inputs and repo `.npmrc`.
-- `src/cache-restore.ts` / `src/cache-save.ts` - Dependency caching via `@actions/cache`.
-- `src/run-install.ts` - Execute `vp install` entries with optional cwd/args.
-- `src/install-sfw.ts` - Install or reuse Socket Firewall Free for wrapped installs.
-- `src/utils.ts` - Lock file detection, package-manager cache paths, and shared helpers.
-- `src/ci/*` - Shared dependency-light primitives for GitLab and Azure runtimes.
-- `src/gitlab/*` - GitLab runtime adapters around `src/ci/*`.
-- `src/azure/*` - Azure Pipelines runtime and logging-command adapters.
-- `azure/setup-vp.yml` - Azure step template.
-- `gitlab/setup-vp.yml` - GitLab remote template.
+- Prefer shared logic under `src/ci/` for behavior used by multiple integrations. Keep `@actions/*` dependencies out of the portable runtimes.
+- Preserve the standalone build entries in `vite.config.ts`. GitLab and Azure download one bundle each; they cannot depend on sibling chunks or the repository's `node_modules`.
+- Preserve function and class names in the bundle minification settings. Cache dependencies compare error names with class names.
+- Target native `vp.exe` for Windows execution. Do not add legacy `vp.cmd` compatibility.
 
 ### Lock File Detection
 
-Auto-detects package manager from lock files: `pnpm-lock.yaml`, `bun.lockb`, `bun.lock`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`.
+Keep cache lock-file detection consistent in `src/utils.ts` and `src/ci/cache.ts`: `pnpm-lock.yaml`, `bun.lockb`, `bun.lock`, `package-lock.json`, `npm-shrinkwrap.json`, and `yarn.lock`.
+
+Distinguish cache detection from version extraction: `bun.lockb` can identify a Bun cache, but the version resolver needs the text `bun.lock` to read a pinned Vite+ version.
 
 ## Testing
 
-Tests are colocated with source files (for example, `src/inputs.test.ts`). Run `vp run test` for test coverage, then run `vp run check:fix` and `vp run build` before committing.
+Add regression tests beside the affected source files (`src/**/*.test.ts`). For shared behavior changes, check the GitHub, GitLab, and Azure adapters, including template and bootstrap tests when their interfaces change. Follow the [pre-commit checks](CONTRIBUTING.md#before-committing).
+
+Build before running tests that inspect or execute `dist/`, including `src/bundle.test.ts`, `src/portable-bundles.test.ts`, and `test/cache-snapshot.test.mjs`.
+
+Use [.github/workflows/test.yml](.github/workflows/test.yml) to locate native Windows command/cache regressions and Azure runtime smoke tests. A skipped Windows-only test does not verify Windows behavior; Azure runtime smoke tests on GitHub runners do not verify native Azure Pipelines orchestration. See [GitLab E2E procedures](CONTRIBUTING.md#gitlab-end-to-end-tests) for the external test suite.

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+For setup-vp usage and configuration, see the [README](README.md).
+
+## Development
+
+### Install Vite+ CLI
+
+- Linux / macOS: `curl -fsSL https://viteplus.dev/install.sh | bash`
+- Windows: `irm https://viteplus.dev/install.ps1 | iex`
+
+### Setup
+
+```bash
+git clone https://github.com/voidzero-dev/setup-vp.git
+cd setup-vp
+vp install
+```
+
+### Available Commands
+
+| Command             | Description                  |
+| ------------------- | ---------------------------- |
+| `vp run build`      | Build the bundles in `dist/` |
+| `vp run test`       | Run tests                    |
+| `vp run test:watch` | Run tests in watch mode      |
+| `vp run typecheck`  | Check types                  |
+| `vp run check`      | Check lint and formatting    |
+| `vp run check:fix`  | Fix lint and formatting      |
+
+### Before Committing
+
+Format and build before running the tests, because some tests inspect or execute the bundles in `dist/`:
+
+```bash
+vp run check:fix
+vp run build
+vp run typecheck
+vp run test
+```
+
+Commit generated changes under `dist/` with the source changes. Include `dist/index.mjs` for GitHub Actions, `dist/gitlab/index.mjs` for GitLab, and `dist/azure/index.mjs` for Azure Pipelines.
+
+The [pre-commit hook](.vite-hooks/pre-commit) runs `vp staged`. The staged-file configuration in [vite.config.ts](vite.config.ts) runs `vp check --fix` on staged files. Run the build yourself; the hook does not rebuild the bundles.
+
+## Integration Design
+
+Use the shared primitives under [`src/ci/`](src/ci/) for portable runtime behavior.
+
+- GitLab: edit the TypeScript runtime under [`src/gitlab/`](src/gitlab/). The template downloads and runs the `vp pack` bundle at `dist/gitlab/index.mjs`. See the [GitLab integration notes](rfcs/gitlab-integration.md) for design constraints and follow-up work.
+- Azure Pipelines: edit the runtime under [`src/azure/`](src/azure/). Azure cannot execute the GitHub Action bundle; the template runs `dist/azure/index.mjs` in `prepare` and `finalize` phases around `Cache@2`. See the [Azure integration notes](rfcs/azure-pipelines-integration.md) for the design, parity table, and cache semantics.
+
+## GitLab End-to-End Tests
+
+Use the dedicated [GitLab test project](https://gitlab.com/fengmk2/setup-vp-gitlab-test) to test the remote integration. The [GitLab E2E workflow](.github/workflows/gitlab-e2e.yml) covers same-repository pull requests, approved fork pull requests, merge queue commits, merges, and releases. The pipeline loads the template, bootstrap script, and compiled runtime from the exact setup-vp commit or release tag under test.
+
+### Fork Pull Requests
+
+After reviewing the commit, a maintainer with write access can add `run-e2e` to run the full GitLab suite. Approve the Actions run if prompted.
+
+For each new commit, review the changes and remove and re-add `run-e2e`. Read the PR result comment for the status and GitLab pipeline link after each run.
+
+## Dependency Updates
+
+Renovate opens a PR when SocketDev publishes a new `sfw-free` release. See the custom managers in [`.github/renovate.json`](.github/renovate.json) for the pinned `SFW_VERSION` values in the GitHub and portable runtimes.
+
+## Releasing
+
+Publish releases as Git tags, not as an npm package. Keep `package.json.version` aligned with the release tag. Consumers pin an exact tag such as `voidzero-dev/setup-vp@v1.20.0` or a commit SHA. Do not move the `v1` major tag, which is frozen at `v1.15.0`.
+
+1. Open a release PR. Set the upcoming version in `package.json`; use it as the source of truth for the release version. Update the release examples in `README.md` and this guide. Set these defaults to `v` followed by that version:
+
+   - The `setup-ref` inputs and inline bootstrap fallbacks in `gitlab/setup-vp.yml` and `gitlab/setup-vp-windows.yml`.
+   - The `setupRef` parameter in `azure/setup-vp.yml`.
+   - The `SETUP_VP_SETUP_REF` fallbacks in `gitlab/bootstrap.sh`, `gitlab/bootstrap.ps1`, `azure/bootstrap.sh`, and `azure/bootstrap.ps1`.
+
+   Run `vp run test` before merging the release PR. The bootstrap and template tests compare these defaults with `package.json.version`, so an omitted update fails CI. Merge all version changes before creating the tag; do not resolve `latest` at runtime or reuse the frozen `v1` tag.
+
+2. Update `main` and confirm that all three bundles in `dist/` are in sync. The working tree must stay clean after building:
+
+   ```bash
+   git checkout main
+   git pull --ff-only
+   vp run build
+   git status --short   # must be empty
+   ```
+
+3. Confirm that the release commit on `main` passes the full GitLab E2E workflow.
+
+4. Create the new annotated version tag and push it. For example:
+
+   ```bash
+   git tag -a v1.20.0 -m "v1.20.0"
+   git push origin v1.20.0
+   ```