Skip to content

docs: streamline repository agent instructions #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fengmk2 merged 2 commits into from
Sep 21, 2026
Merged

docs: streamline repository agent instructions #170

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
328342a
docs: streamline repository agent instructions
fengmk2 Sep 21, 2026
e46ae13
Merge branch 'main' into streamline-agent-instructions
fengmk2 Sep 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 21 additions & 57 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,37 @@
# AGENTS.md

This file provides guidance to coding agents working in this repository.
setup-vp installs [Vite+](https://viteplus.dev) (`vp`) through GitHub Actions, GitLab CI/CD, and Azure Pipelines.

## Guidelines
## Context by Task

- 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.

## Documentation

- 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.

Keep the README's Contributing section as a link to the contributor guide. Do not duplicate contributor procedures in the README.

## Project Overview

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.

## Architecture

| 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` |

- 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.
- For development setup, commands, and releases, follow [CONTRIBUTING.md](CONTRIBUTING.md).
- For GitHub Actions behavior, start with `action.yml` and `src/index.ts`; input parsing and schemas live in `src/inputs.ts` and `src/types.ts`.
- For GitLab or Azure behavior, start with `src/gitlab/index.ts` or `src/azure/index.ts` and the corresponding templates and bootstrap scripts in `gitlab/` or `azure/`. See [Integration Design](CONTRIBUTING.md#integration-design) for the design references.
- For behavior shared across integrations, start with `src/ci/` and the corresponding adapters under `src/`, `src/gitlab/`, and `src/azure/`.

### Public Interfaces

Keep input parsing, templates, bootstrap scripts, and README examples aligned when changing an interface.

- 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`.

### Key Modules

- `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.

### Implementation Constraints
## Implementation Constraints

- Prefer shared logic under `src/ci/` for behavior used by multiple integrations. Keep `@actions/*` dependencies out of the portable runtimes.
- Keep input parsing, templates, bootstrap scripts, and README examples aligned when changing an interface. GitLab Unix and Windows templates must expose matching inputs.
- 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.
- When changing lock-file detection, keep `src/utils.ts` and `src/ci/cache.ts` consistent: `pnpm-lock.yaml`, `bun.lockb`, `bun.lock`, `package-lock.json`, `npm-shrinkwrap.json`, and `yarn.lock`. `bun.lockb` identifies a Bun cache; version extraction requires the text `bun.lock`.

### Lock File Detection

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`.
## Testing

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.
- Add regression tests beside the affected source files (`src/**/*.test.ts`). For shared behavior changes, check all three integrations, including template and bootstrap tests when interfaces change.
- 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) for native Windows command/cache regressions and Azure runtime smoke tests. A skipped Windows-only test does not verify Windows behavior; Azure smoke tests on GitHub runners do not verify native Azure Pipelines orchestration.
- Follow the [GitLab E2E procedures](CONTRIBUTING.md#gitlab-end-to-end-tests) for the external suite.

## Testing
## Commits

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).
- Do not commit without an explicit request. A request to push authorizes staging, committing, and pushing the current task changes; exclude unrelated changes.
- Before committing, run the [required checks](CONTRIBUTING.md#before-committing). Regenerate and commit affected `dist/` bundles with their source changes; do not edit bundles by hand.

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`.
## Documentation

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.
- Keep `README.md` focused on user-facing setup, configuration, examples, and behavior. Its Contributing section must link to `CONTRIBUTING.md`.
- Put development commands, contribution requirements, E2E procedures, dependency maintenance, and release instructions in `CONTRIBUTING.md`. Keep detailed designs and integration proposals in `rfcs/`, linked from that guide.
- Keep `AGENTS.md` focused on agent rules, navigation, and implementation constraints. Link to contributor procedures instead of repeating them in `AGENTS.md` or `README.md`.
Loading