Skip to content

docs: update AGENTS.md for Vite+ transition #75

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
torn4dom4n merged 1 commit into from
May 18, 2026
Merged

docs: update AGENTS.md for Vite+ transition #75

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 24 additions & 15 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,39 @@ This file provides context and instructions for AI agents working on the @area44

## Project Overview

This repository contains reusable GitHub Actions workflows and composite actions (Astro, Vite, Lint/Format, Images) for the AREA44 ecosystem.
This repository contains reusable GitHub Actions workflows and composite actions (Astro, Vite, Vite-Plus, Lint-Format, Images) for the AREA44 ecosystem.

## Core Directives

- **ES Modules**: The project is configured as an ES module (`"type": "module"` in `package.json`). Build artifacts in `dist/` are also generated as ESM.
- **Vite+ (vp)**: The project is managed by Vite+, providing unified tooling for package management, build, test, lint, and formatting.
- **ES Modules**: The project is configured as an ES module (`"type": "module"` in `package.json`). Build artifacts in `dist/` are generated as ESM via `vp pack`.
- **Tracked Build Artifacts**: The `dist/` folder is tracked in the repository to allow composite actions to be used directly without a build step in consuming workflows.
- **Clean Distribution**: The `dist/` directory must only contain final bundled JavaScript files. Do not include source files or redundant artifacts.
- **Compatibility**: Preserve original `action.yml` files in root directories (astro/, lint-format/, images/, vite/) and maintain original public inputs/outputs for backward compatibility.
- **No Shared Chunks**: `rolldown.config.mjs` uses separate configurations for each entry point to prevent shared chunks that cause "require" errors in ESM-based GitHub Actions runners.
- **Clean Distribution**: The `dist/` directory must only contain final bundled JavaScript output files. Do not include source files or redundant artifacts.
- **Compatibility**: Preserve original `action.yml` files in root directories and maintain original public inputs/outputs for backward compatibility.
- **Centralized Configuration**: All tool configurations (build, lint, test, format) are consolidated in `vite.config.ts`.

## Development & Build
## Development & Commands

- **Build**: Use `npm run build` to bundle the project using Rolldown.
- **Minification**: Output files are minified (`minify: true` in `rolldown.config.mjs`).
- **Node.js**: The project uses Node 24 and targets the Node platform for bundling.
- **Setup**: Run `vp install` to install dependencies and ensure local binaries are available.
- **Build**: Use `vp pack` to bundle the project. Output files are minified and include an `eslint-disable` banner.
- **Lint & Format**: Use `vp lint` and `vp fmt`. Formatting enforces sorted imports and mandatory curly braces for control flow.
- **Unified Validation**: Use `vp check` (or `vp check --fix`) for pre-commit validation.
- **Node.js**: The project uses Node 24. For GitHub Actions, set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to address Node.js 20 deprecation warnings.
- **Package Management**: Prioritize the `packageManager` field in `package.json`. Bun 1.2+ support favors `bun.lock` and excludes the deprecated `bun.lockb`.

## Testing

- **Unit Tests**: Use Vitest for unit testing. Tests are located in `__tests__/`. Run them with `npm run test`.
- **Integration Tests**: Integration tests are split into separate workflow files (`.github/workflows/`) to ensure isolated runs and avoid artifact name conflicts.
- **Environment Detection**: Core environment detection logic is in `src/detect-env.ts`.
- **Lint/Format Logic**: Core logic for running lint/format scripts is implemented directly in `lint-format/action.yml` using bash.
- **Unit Tests**: Use Vitest (via `vp test`) for unit testing logic in `__tests__/`.
- **Integration Tests**: Split into separate workflow files (e.g., `test-astro.yml`, `test-lint-format.yml`) to ensure isolated runs.
- **Environment Detection**: Logic in `src/detect-env.ts` detects Node.js version (checking `.nvmrc`, `.node-version`, `engines`) and package manager.

## GitHub Actions Logic

- **Dynamic Environment Variables**: The Vite and Vite-Plus actions dynamically set `VITE_SITE_URL` and `BASE` based on the repository context (project site vs. user/org page).
- **Images Action**: Optimizes media using standard tools (`svgo`, `optipng`, etc.) and supports WebP/AVIF conversion with automated system package installation.
- **Autofix CI**: Integration with `autofix-ci/action@v1` requires the workflow name to be `autofix.ci` and the file to be `autofix.yml` or `autofix.ci.yml`.

## Coding Preferences

- Use descriptive names for internal functions (e.g., `setOutputs`, `detectNodeVersion`) rather than generic names.
- Always include an 'eslint-disable' banner in generated files via rolldown config.
- **Naming**: Use descriptive names for internal functions (e.g., `setOutputs`) and variables (e.g., `error` instead of `err`) to satisfy strict linting.
- **Formatting**: Import sorting is enforced by group (type, external, internal, etc.). Mandatory curly braces are required for all control flow statements.