Copilot instructions

1# GitHub Copilot Instructions
2 
3The canonical contributor guide for this repo is [`AGENTS.md`](../AGENTS.md). It covers setup, commands, package shape, architecture boundaries, naming, error handling, interceptor order, the request lifecycle, cancellation, common pitfalls, tests, and security-sensitive code.
4 
5The rules below are a Copilot-facing subset of the load-bearing safety guarantees from `AGENTS.md`. If they ever drift, `AGENTS.md` is authoritative — update both.
6 
7## Setup safety
8 
9- Install with `npm ci`; the repo's `.npmrc` sets `ignore-scripts=true`. Do not remove that flag. If husky hooks are needed after a fresh install, run `npm rebuild husky && npx husky` once.
10- Do not add new runtime dependencies without discussion. `package-lock.json` is verified by `lockfile-lint` for npm HTTPS hosts and integrity hashes.
11- Package, lockfile, and GitHub Actions update PRs are maintainer/bot-only; close these PRs from outside collaborators. Keep the 7-day Dependabot delay unless a critical vulnerability requires a maintainer-led manual update.
12 
13## Architecture in one screen
14 
15- `lib/core/` — domain logic: `Axios`, `AxiosError`, `AxiosHeaders`, `InterceptorManager`, config merge, request dispatch.
16- `lib/adapters/` — I/O: `xhr.js`, `http.js`, `fetch.js`. Default preference `['xhr', 'http', 'fetch']`, picked by capability detection in `lib/adapters/adapters.js`. Never branch on environment name.
17- `lib/platform/` — Node by default; browser builds alias to `lib/platform/browser`.
18- `lib/helpers/` — generic, reusable utilities; no axios-specific lifecycle logic here.
19- Source is ESM (`type: module`) with explicit `.js` import extensions. `dist/` is generated by Rollup — never edit it by hand. Keep `index.d.ts` (ESM) and `index.d.cts` (CJS) in sync for any public API change.
20 
21## Error handling
22 
23- Throw `AxiosError(message, code, config, request, response)` for axios-originated failures; never raw `Error`.
24- Wrap third-party errors with `AxiosError.from(error, code, config, request, response)`.
25- Use a code from `lib/core/AxiosError.js` (`ERR_NETWORK`, `ETIMEDOUT`, `ECONNABORTED`, `ERR_CANCELED`, `ERR_BAD_REQUEST`, `ERR_BAD_RESPONSE`, `ERR_FR_TOO_MANY_REDIRECTS`, `ERR_FORM_DATA_DEPTH_EXCEEDED`, `ERR_INVALID_URL`, `ERR_BAD_OPTION`, `ERR_BAD_OPTION_VALUE`, `ERR_NOT_SUPPORT`, `ERR_DEPRECATED`, `ECONNREFUSED`).
26 
27## Interceptor order
28 
29- Request interceptors run **LIFO** (last-registered-first); response interceptors run **FIFO**. Both support `synchronous: true` and `runWhen(config)`.
30 
31## Naming and style
32 
33- PascalCase classes (`Axios`, `AxiosHeaders`), camelCase functions (`buildURL`, `mergeConfig`), UPPER_SNAKE_CASE error codes.
34- Internal slots use `Symbol`-keyed properties (see `$internals` in `lib/core/AxiosHeaders.js`), not underscore-prefixed names.
35- Use `lib/helpers/bind.js`, not `Function.prototype.bind`, when binding library functions — the helper forwards `arguments` via `apply`.
36- `'use strict';` appears at the top of files that already use it; match the surrounding file rather than blanket-adding it.
37 
38## Security guarantees that must not regress
39 
40- For config reads on potentially untrusted input, use own-property checks (`utils.hasOwnProp` / local `own()` helpers); never `in`, destructuring, or direct `config.foo` access.
41- Any merge or object materialization must continue to filter `__proto__`, `constructor`, and `prototype`. Regressions here are security bugs.
42- Changes touching URL construction, redirects, proxy/env handling, XSRF, socket paths, decompression limits, or adapters require consulting `THREATMODEL.md` and adding focused regression tests.
43- `withXSRFToken === true` is the only thing that forces cross-origin XSRF header attachment — keep that behavior explicit.
44- Do not weaken `beforeRedirect`, proxy, or `socketPath` safeguards without tests covering credential leakage and SSRF-style cases.
45 
46## Common pitfalls
47 
48- Do not mutate config objects in place; return new ones from merges/transforms.
49- Do not assume browser- or Node-only globals exist; capability-check first.
50- Validate options through the existing `validator` helper rather than inventing ad-hoc validation paths.
51 
52## Pre-release tracking
53 
54- Add user-visible unreleased changes to `PRE_RELEASE_CHANGELOG.md`, not `CHANGELOG.md`.
55- Track deferred README, docs site, examples, migration guide, and translated docs updates in `PRE_RELEASE_DOCS.md`; do not update release docs for unreleased runtime/API changes unless explicitly doing release preparation.
56