# AGENTS.md - Yarn Spinner Loader

## Commands
- `npm run build` — Build all entry points (tsup, ESM + CJS)
- `npm run dev` — Watch mode
- `npm run test` — Vitest watch mode
- `npm run test:run` — Run tests once
- `npm run typecheck` — `tsc --noEmit`

## Architecture
- **`src/index.ts`** — Main entry point. Full browser package: parse + compile + run + all types. No Node.js deps.
- **`src/core.ts`** — Mirror of index.ts. Not in package.json exports.
- **`src/runner.ts`** — Minimal runtime export: `YarnRunner` + runtime/IR types only. No parser, no compiler.
- **`src/loader/`** — Filesystem loader: parses `.yarnproject` files, validates against JSON schema (ajv), resolves globs (fast-glob), compiles `.yarn` files.
- **`src/plugins/`** — Build tool plugins: esbuild, rollup, vite, webpack. Each is a separate tsup entry point outputting to `dist/plugins/`.
- **`src/yarn-spinner/`** — Embedded Yarn Spinner implementation: `parse/`, `compile/`, `runtime/`, `markup/`, `model/`.
- **`src/runner/`** — Empty directory. Ignore.

## Package exports
- `yarn-spinner-loader` → `dist/index.js` (full browser package)
- `yarn-spinner-loader/runner` → `dist/runner.js` (runtime only)
- `yarn-spinner-loader/esbuild` → `dist/plugins/esbuild.js`
- `yarn-spinner-loader/rollup` → `dist/plugins/rollup.js`
- `yarn-spinner-loader/vite` → `dist/plugins/vite.js`
- `yarn-spinner-loader/webpack` → `dist/plugins/webpack.js`

## Key conventions
- `src/index.ts` and `src/core.ts` must NOT import from `src/loader/` or any Node.js-specific modules.
- `src/loader/` is the only code that uses `fs`, `path`, `fast-glob`.
- TypeScript: strict mode, ES2022, `moduleResolution: "bundler"`.
- Tests live in `tests/`, not `src/`. Pattern: `tests/**/*.test.ts`.

## Build notes
- tsup config has 6 entry points. Main + runner output to `dist/`, plugins output to `dist/plugins/`.
- `npm run build` cleans `dist/` automatically.
- `core.ts` is NOT exported in package.json — it exists for internal consistency only.
- This package is intended as a `devDependency` alongside bundlers. Dependencies (`ajv`, `fast-glob`) are needed at build time.

## Security
- `.npmrc` contains an npm auth token. Never commit or expose this.