convoy: scope bump-next-js (P0 #8 — unblock Vercel deploys) #3
7 changed files with 1681 additions and 664 deletions
370
.convoys/bump-next-js.md
Normal file
370
.convoys/bump-next-js.md
Normal file
|
|
@ -0,0 +1,370 @@
|
||||||
|
---
|
||||||
|
name: bump-next-js
|
||||||
|
classification: feature
|
||||||
|
success_metric: "npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build."
|
||||||
|
skip:
|
||||||
|
- ia
|
||||||
|
- ux
|
||||||
|
- flag
|
||||||
|
status: open
|
||||||
|
created: 2026-05-22
|
||||||
|
---
|
||||||
|
|
||||||
|
# Convoy: bump-next-js
|
||||||
|
|
||||||
|
Closes P0 ship-blocker **#8** from `.convoys/ship-readiness.md`. Highest-priority convoy in the launch sequence — promoted to slot 0 because Vercel is currently refusing to deploy any branch (including `main`) until Next.js is bumped, which makes every downstream `preview-smoke` / `visual-diff` gate non-functional.
|
||||||
|
|
||||||
|
## Why
|
||||||
|
|
||||||
|
Vercel's platform-level security gate is blocking every deployment with `"Vulnerable version of Next.js detected, please update immediately"`. The lockfile currently resolves `next@15.4.3`; latest is `16.2.6`. The build itself completes (Vercel CLI confirms `Build Completed in /vercel/output [29s]`), but the deployment is rejected before going live.
|
||||||
|
|
||||||
|
Concrete impact, as of 2026-05-22:
|
||||||
|
|
||||||
|
- **The last successful deploy on `main` was 2025-08-01.** Production is stale.
|
||||||
|
- **Preview deployments are unavailable** on every PR. `preview-smoke.yml` and `visual-diff.yml` have nothing to point at, so they fail-quiet on every PR.
|
||||||
|
- **PR #1 (the bootstrap PR) cannot validate its own L3 visual gates** because of this.
|
||||||
|
|
||||||
|
This convoy unblocks the entire launch sequence. Until it ships, the other 13 convoys are running half-blind. Success looks like:
|
||||||
|
|
||||||
|
1. `package.json` declares `"next": "^16.2.6"` (or whatever the architect picks — see scope).
|
||||||
|
2. `package-lock.json` regenerated.
|
||||||
|
3. `npm run dev` boots without warnings about deprecated APIs.
|
||||||
|
4. `npm run build` exits 0 with no breaking-change errors.
|
||||||
|
5. A PR opened from a feature branch produces a **successful** Vercel preview deploy.
|
||||||
|
6. `preview-smoke` and `visual-diff` workflows have a live URL to hit (they'll still fail on missing `@playwright/test` until `adopt-vitest` lands, but the Vercel half is no longer broken).
|
||||||
|
7. CI green: lint passes (wrapper is in place from bootstrap), aggregate gate passes.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
**In:**
|
||||||
|
|
||||||
|
- Bump `next` from `15.4.3` to `16.2.6` in `package.json` + `package-lock.json`.
|
||||||
|
- Bump `eslint-config-next` from `15.4.2` to a matching `16.x` release to keep the lint config aligned with the framework.
|
||||||
|
- Audit Next.js 15 → 16 migration guide ([blog](https://nextjs.org/blog/next-16), [upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading)) and identify which surfaces in `tcg-vault` are affected. Educated guess at affected paths (validate during architect):
|
||||||
|
- `next.config.js` — the `images.domains` field has been deprecated for several major versions; if Next 16 drops it, migrate to `images.remotePatterns`.
|
||||||
|
- `next/image` usage across `pages/cards.js`, `pages/card/[id].js`, `components/CollectionSelectionModal.js`, `components/ManaSymbols.js`, `components/UploadImageModal.js` — verify props are still supported.
|
||||||
|
- Pages Router specifics — Pages Router is intentionally more stable than App Router across major bumps, but `getServerSideProps` / `getStaticProps` semantics may have edge-case changes.
|
||||||
|
- API routes — `req` / `res` API stays stable in Pages Router; should be a no-op surface.
|
||||||
|
- Middleware — `tcg-vault` has no `middleware.js` currently; nothing to migrate.
|
||||||
|
- Update `AGENTS.md` "Tech stack quick reference" to bump the Next.js version string.
|
||||||
|
- Validate via local `npm run build`, then push to confirm Vercel preview deploys successfully.
|
||||||
|
|
||||||
|
**Out (deferred to their own convoys):**
|
||||||
|
|
||||||
|
- **React 18 → 19 upgrade.** `next@16` peer-deps accept `react@^18.2.0 || ^19.0.0`. Current `react@18.3.1` is in range. A React 19 bump is its own convoy (`bump-react`) because of compiler / Suspense / `use()` API changes.
|
||||||
|
- **App Router migration.** `tcg-vault` is on Pages Router. Migrating to App Router is a multi-month effort and outside this convoy.
|
||||||
|
- **Test runner adoption** (`adopt-vitest` / `adopt-playwright-smoke`) — those convoys remain queued.
|
||||||
|
- **`.eslintrc.json` rule tuning** — the bootstrap added a stub extending `next/core-web-vitals`. If `eslint-config-next@16` ships new rules that surface additional errors, defer the cleanup to `fix-lint-baseline`.
|
||||||
|
|
||||||
|
**Hard "do not touch" in this convoy:**
|
||||||
|
|
||||||
|
- No auth code (`lib/permission-middleware.js`, `pages/api/auth/`, `pages/api/auth-utils.js`) — that's `fix-auth-bypass`.
|
||||||
|
- No DB code.
|
||||||
|
- No new features or UI changes beyond what's strictly required to keep existing pages rendering after the bump.
|
||||||
|
- No CODEOWNERS / workflow / convoy file edits.
|
||||||
|
- No feature flags. The bump ships unflagged.
|
||||||
|
|
||||||
|
## Roles invoked
|
||||||
|
|
||||||
|
Per `feature` classification with custom skips (`ia, ux, flag`):
|
||||||
|
|
||||||
|
1. **role-architect** — produces a slice plan. Reads the Next 16 migration guide, lists every breaking change that touches `tcg-vault`, decides which need code changes vs. configuration changes vs. no-ops. Output: 1–3 briefs under `.convoys/bump-next-js/brief-N-*.md`. Likely shape:
|
||||||
|
- Brief 1: the bump itself (package.json + lockfile + any required `next.config.js` migration).
|
||||||
|
- Brief 2 (if needed): code changes for any deprecated APIs (e.g. `<Image>` prop rename).
|
||||||
|
- Brief 3 (if needed): visual-diff baseline refresh if rendering changed.
|
||||||
|
2. **role-implementer** — single-writer flow. The bump itself is one file change + lockfile; can't be meaningfully parallelized.
|
||||||
|
3. **Audit fan-out** (`/multitask`, group id `audit-bump-next-js-<pr>`) — runs in parallel after the PR is drafted:
|
||||||
|
- **role-reviewer** — correctness, regression risk
|
||||||
|
- **role-design-system-auditor** — verify CSS / theming / token usage still renders correctly
|
||||||
|
- **role-a11y-auditor** — verify accessibility didn't regress (Next.js 16 may change focus-management defaults)
|
||||||
|
4. **role-doc-writer** — last. Updates `AGENTS.md` "Tech stack" section. Adds an entry to a CHANGELOG if one is started here (it'll be backfilled separately in `launch-polish`).
|
||||||
|
|
||||||
|
## Todos
|
||||||
|
|
||||||
|
High-level checklist for the architect to refine into briefs:
|
||||||
|
|
||||||
|
- [ ] **Brief 1 — Migration audit.** Read the [Next.js 16 release notes](https://nextjs.org/blog/next-16) and [upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading). Produce a short table: deprecated API → file(s) that use it → migration step. Specifically check: `images.domains` deprecation, `next/font` changes, `next/image` prop changes, any default-runtime changes (edge vs node).
|
||||||
|
- [ ] **Brief 2 — Bump + lockfile.** `npm install next@16.2.6 eslint-config-next@^16`. Commit `package.json` + `package-lock.json`. Verify `npm ls next` shows the new version.
|
||||||
|
- [ ] **Brief 3 — Verify build + dev locally.** `npm run build` must exit 0 with no breaking-change errors. `npm run dev` must boot without deprecation warnings on the routes we ship today. If errors surface, this is where they get fixed.
|
||||||
|
- [ ] **Brief 4 — Vercel preview deploy.** Push the branch and confirm the Vercel deploy completes successfully (status moves from `pending` → `success`, not `Error`). Capture the preview URL in the PR description.
|
||||||
|
- [ ] **Brief 5 — Visual diff baseline.** If `preview-smoke.yml` / `visual-diff.yml` aren't installed yet (they need `@playwright/test`), this brief is informational — flag any obvious visual changes to the reviewer + design-system-auditor. Once `adopt-playwright-smoke` lands, this becomes a real verification step.
|
||||||
|
- [ ] **Doc-writer pass.** Update `AGENTS.md` tech-stack line. Note the bump in the bootstrap PR's "Notes for reviewer" or, if PR #1 has merged by then, open a small standalone docs PR.
|
||||||
|
|
||||||
|
## Hand-off
|
||||||
|
|
||||||
|
**Next role: `role-architect`** (IA + UX are skipped; routing straight to Architect).
|
||||||
|
|
||||||
|
To run it in a new chat, paste:
|
||||||
|
|
||||||
|
> *"Run role-architect on convoy `bump-next-js`. Read `.convoys/bump-next-js.md` for scope and todos, then read the Next.js 15 → 16 upgrade guide and produce a slice plan. Output briefs to `.convoys/bump-next-js/brief-N-*.md`. Mark any briefs that are parallel-safe (probably none — this is mostly a single-writer flow except the audit fan-out). Be conservative about scope creep: if the migration guide flags an API not used in `tcg-vault`, note it in the brief but don't add a 'while we're here' fix."*
|
||||||
|
|
||||||
|
After architect publishes the brief(s), the user runs `role-implementer` serially. Once the PR is drafted, the user uses Cursor 3.2 `/multitask` to dispatch the audit cohort (`reviewer + design-system-auditor + a11y-auditor`) in parallel under group id `audit-bump-next-js-<pr>`.
|
||||||
|
|
||||||
|
Conductor exits here.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
_Produced by `role-architect` on 2026-05-22 against Next.js 16.2.6 (latest stable; verified via `npm view next version`). Updated 2026-05-23 after four gate-1 scope changes (A, B, C, D — see Decisions log below):_
|
||||||
|
|
||||||
|
- _A: scope expanded to include the ESLint v8 → v9 + flat-config migration so `eslint-config-next` can move to `^16` matching `next`._
|
||||||
|
- _B: pivoted from ESLint v9 to v10 (then-`latest`) after gate-1 re-review of risk R14._
|
||||||
|
- _C: added `typescript@^5.9.3` as a devDep after an implementer escalation surfaced that `eslint-config-next@16`'s `peerDependenciesMeta.typescript.optional: true` annotation does not make `typescript` runtime-optional._
|
||||||
|
- _D: reverted the v10 pivot back to v9.39.4 after a pass-2 implementer escalation showed Risk R15 firing empirically (`TypeError: scopeManager.addGlobals is not a function` from `@typescript-eslint/scope-manager@8.59.4` predating v10 GA). v10 deferred to the upstream-blocked `bump-eslint-10` follow-up convoy._
|
||||||
|
|
||||||
|
### File plan
|
||||||
|
|
||||||
|
| File | Action | Purpose |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `package.json` | modified | Bump `dependencies.next` from `^15.4.2` to `^16.2.6`. Bump `devDependencies.eslint` from `^8` to `^9.39.4` (npm's `maintenance` dist-tag; per Decisions log entry D, reverted from the v10 pin set under entry B after R15 fired empirically). Bump `devDependencies.eslint-config-next` from `15.4.2` to `^16.2.6` to match `next` — peer-dep `eslint: >=9.0.0` accepts v9.39.4 trivially. **Add `devDependencies.typescript: "^5.9.3"`** (per Decisions log entry C — `eslint-config-next@16` bundles `typescript-eslint`, which hard-requires `typescript` at module load under both v9 and v10; the `peerDependenciesMeta.typescript.optional: true` flag only suppresses npm's install-time warning, not the runtime require). Replace `scripts.lint` from `next lint` to `eslint .` (Next 16 removed the `next lint` command). React, react-dom, and all other packages stay unchanged. |
|
||||||
|
| `package-lock.json` | modified | Regenerated by `npm install`. Reflects the new `next@16.2.6`, `eslint@^9.39.4`, `eslint-config-next@^16.2.6`, and `typescript@^5.9.3` resolutions. Under Decision D the lockfile stays on the v9 dep-tree (`@eslint/eslintrc` is still a v9 transitive dep; the v10 dep-tree changes that would have removed it are deferred to the queued `bump-eslint-10` follow-up convoy). The new `typescript` subtree is small — `typescript` itself has no `dependencies` and no `peerDependencies`. Do not hand-edit. |
|
||||||
|
| `next.config.js` | modified | Migrate `images.domains: [...]` (deprecated in 16, deprecation warning at startup) to `images.remotePatterns: [...]`. Three patterns, one per CDN currently in `images.domains`. |
|
||||||
|
| `.eslintrc.json` | **deleted** | The 40-byte legacy stub (`{"extends": "next/core-web-vitals"}`) is replaced by `eslint.config.mjs` because `eslint-config-next@16` only supports flat config. Leaving both files in place would be a footgun. |
|
||||||
|
| `eslint.config.mjs` | **new** | Flat-config replacement for `.eslintrc.json`. Reproduces the prior `next/core-web-vitals` extends behavior using the verbatim shape from the official Next.js docs (`defineConfig([...nextVitals, globalIgnores([...])])`). `globalIgnores` covers the no-go-zone paths the user specified at gate 1 plus `eslint-config-next`'s documented defaults. |
|
||||||
|
|
||||||
|
Doc-writer's `AGENTS.md` "Tech stack" string update is a separate PR by `role-doc-writer` after this one merges (per the convoy's Roles list).
|
||||||
|
|
||||||
|
### API surface
|
||||||
|
|
||||||
|
**No API changes.** This convoy does not touch `pages/api/**`. The Next.js 16 upgrade guide does not change the Pages-Router `req`/`res` handler signature; `tcg-vault`'s ~30 API handlers all use the legacy `(req, res) => { ... }` shape and continue to work unchanged.
|
||||||
|
|
||||||
|
### Schema diff
|
||||||
|
|
||||||
|
**No schema changes.** This convoy does not touch the database. Neon Postgres + `scripts/setup-neon-db.js` are out of scope.
|
||||||
|
|
||||||
|
### Test plan
|
||||||
|
|
||||||
|
`tcg-vault` has no automated test runner installed yet (vitest + Playwright adoption is tracked under `adopt-vitest` and `adopt-playwright-smoke` convoys). For this convoy:
|
||||||
|
|
||||||
|
- **Manual smoke per `TESTING_GUIDE.md`** is the verification mechanism. Specifically: home (`/`), login (`/login`), signup (`/signup`), browse (`/cards`), and `/collections` must render without runtime errors after the bump.
|
||||||
|
- **`npm run build` exiting 0** is the integration test for the Turbopack default-bundler change. No custom webpack config exists in `next.config.js`, so Turbopack should "just work."
|
||||||
|
- **`npm run lint` running to completion** (regardless of the error count) is the integration test for the ESLint v8 → v9 + flat-config migration (per Decision D — Decision B's pivot to v10 was reverted after R15 fired empirically). The pre-existing baseline of ~100 errors is expected to shift modestly under v9 due to plugin major bumps (`eslint-plugin-react-hooks` v5 → v7, `@next/eslint-plugin-next` 15 → 16) but **not** to shift the way v10 would have (no new `eslint:recommended` rules, no JSX reference tracking, no `no-shadow-restricted-names.reportGlobalThis: true` default — those land later under `bump-eslint-10`). CI's `|| true` wrapper continues to tolerate any non-zero exit. **Counting baseline drift is `fix-lint-baseline`'s job, not this convoy's.** **If `npm run lint` does not run to completion under v9.39.4** — e.g. it crashes with a `TypeError` — see Brief 1's failure-mode classifier under "Local verification." Decision D's expectation is that R15's empirical signature (`scopeManager.addGlobals is not a function`) does NOT recur on v9 because v9 doesn't call `addGlobals`. If a different `TypeError` fires on v9, escalate rather than patching transitive deps.
|
||||||
|
- **Vercel preview deploy reaching Success state** is the end-to-end integration test. The convoy's `success_metric` ("npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build") is exactly this.
|
||||||
|
- **Audit fan-out (`/multitask`, group id `audit-bump-next-js-<pr>`)** is the qualitative gate: `role-reviewer` for correctness, `role-design-system-auditor` for token rendering, `role-a11y-auditor` for focus / scroll-behavior regression. They run AFTER the PR is drafted, not as part of this brief.
|
||||||
|
- Once `adopt-vitest` lands, retrofit a smoke test for `next.config.js` parsing and one for `<img>` (or future `<Image>`) rendering against a fixture page.
|
||||||
|
|
||||||
|
### Risk list
|
||||||
|
|
||||||
|
- **R1: Turbopack-by-default may surface unexpected build/runtime differences vs webpack.** Per gate-1 decision: accept the default. tcg-vault has no `webpack:` block in `next.config.js`, no custom loaders/aliases, no Sass tilde imports, no `resolve.fallback` workarounds. Likelihood of regression: low. **Fallback per command:** `next build --webpack` and `next dev --webpack`. **If a regression appears, the implementer should reproduce on both bundlers** (run the failing flow once with the default, once with `--webpack`) **before deciding whether to revert the bump or pin the script to webpack.** Capture the reproduction in the PR description for `role-reviewer` to triage. Do not pre-emptively add `--webpack` to the scripts.
|
||||||
|
- **R2 — RESOLVED at gate 1, via the A → B → D path.** Originally: "`eslint-config-next` cannot be bumped to `^16` in this convoy." Gate-1 decision A expanded scope to include the ESLint v8 → v9 + flat-config migration. Decision B pivoted from v9 to v10. Decision D reverted v10 → v9.39.4 after R15 fired empirically on the implementer's pass-2 lint run. **Final pins:** `eslint@^9.39.4`, `eslint-config-next@^16.2.6`, `typescript@^5.9.3`, `.eslintrc.json` deleted, `eslint.config.mjs` created. See R12, R13, R14, R15 below for the residual + reinstated risks. The deferred `migrate-to-eslint-flat-config` convoy is **closed before opening** — its work has been folded in. The `bump-eslint-10` follow-up convoy is **queued as upstream-blocked** — see "Follow-up convoys queued" section.
|
||||||
|
- **R3: `next lint` removal hard-breaks `npm run lint`.** Without the `scripts.lint` change, both local devs and CI's `npm run lint --if-present` job would invoke a removed command. Mitigation: change script to `eslint .`. CI's existing `|| true` wrapper continues to tolerate the pre-existing lint baseline (~100 errors, tracked under `fix-lint-baseline`).
|
||||||
|
- **R4: `images.domains` is in `next.config.js` but `next/image` isn't actually used.** Strictly speaking, the migration is preemptive — silences the deprecation warning but adds no functional change. Acceptable: keeps the config valid for the eventual `next/image` adoption. Don't delete the block; that would force re-adding it later.
|
||||||
|
- **R5: `images.minimumCacheTTL` default changed from 60s to 4h.** Behavior change. Not impactful in `tcg-vault` because `next/image` isn't used. No mitigation required; flag here only so future readers don't re-investigate.
|
||||||
|
- **R6: Vercel deploy might fail for an unrelated reason.** The convoy's premise is that the platform-level "Vulnerable version" gate is the sole blocker. If the build itself fails on 16 (e.g. an undocumented Turbopack edge case), the fix lands in this brief. If the failure is environmental (env vars, build settings), escalate — that's a different convoy.
|
||||||
|
- **R7: React 18 stays — intentional.** `next@16` peer-dep accepts `react ^18.2.0 || ^19.0.0`. Current `18.3.1` is in range. **Do not bump React in this convoy.** React 19 has compiler / Suspense / `use()` API changes and is its own convoy (`bump-react`).
|
||||||
|
- **R8: TypeScript >=5.1.0 required by Next 16.** Partially applicable. **`tcg-vault` source code remains plain JavaScript** — no `tsconfig.json`, no `.ts`/`.tsx` files, no source migration in this convoy. **However, per Decision C (2026-05-23), `typescript@^5.9.3` is now installed as a devDep** because `eslint-config-next@16`'s bundled `typescript-eslint` chain hard-`require`s it at module load. The original parenthetical claim — "`eslint-config-next@16` lists `typescript` as an optional peer (`peerDependenciesMeta.typescript.optional: true`) so JS-only consumers are fine" — was wrong: that flag only suppresses npm's install-time warning; the transitive `@typescript-eslint/typescript-estree@8.59.4` (a regular `dependency`, not a peer) does an unconditional `require('typescript')` at module load. See R16 for the full devDep impact analysis.
|
||||||
|
- **R9: Node.js floor — DEFANGED under Decision D.** Originally elevated under Decision B because ESLint v10 raised the floor to `^20.19.0 || ^22.13.0 || >=24`. **Under Decision D's v9.39.4 pin**, the ESLint floor reverts to `^18.18.0 || ^20.9.0 || >=21.1.0` (Next 16 also requires `>=20.9.0` — the same floor). CI's `setup-node@v4` `node-version: '20'`, local `node@22.14.0`, and Vercel's default Node 22 all satisfy with margin to spare. The "moving target on `node-version: '20'`" concern from Decision B is inert under v9. **The constraint will reactivate when `bump-eslint-10` lands**; the queued follow-up convoy should pick up the CI pin question (`node-version: '20.19'` or `'lts/iron'`) at that point.
|
||||||
|
- **R10: `next dev` and `next build` now use separate output dirs (`.next/dev/` vs `.next/`).** `.gitignore` line 28 has `/.next/`, which is a directory rule that covers both subdirs. No `.gitignore` change needed.
|
||||||
|
- **R11: Convoy file's audit list (line 45) is wrong about `next/image` usage.** Pages listed (`pages/cards.js`, `pages/card/[id].js`, etc.) use plain `<img>` tags, not `<Image>`. Architect verified via `rg "from ['\"]next/image['\"]"` — zero hits in `pages/`, `components/`, `lib/`. Surface this to the convoy author so future planning is not based on the same assumption.
|
||||||
|
- **R12 (post-gate-1 expansion; revised under Decision D): ESLint flat-config migration + plugin major bumps will shift the lint baseline modestly.** Drivers under v9.39.4: `eslint-config-next@16.2.6` bundles `eslint-plugin-react-hooks@^7` (vs v5) and `@next/eslint-plugin-next@16` (vs 15.4.2). **The v10-specific drivers from Decision B's wording are deferred to the queued `bump-eslint-10` follow-up** (the three new `eslint:recommended` rules, JSX reference tracking, `no-shadow-restricted-names.reportGlobalThis: true` default). `eslint-env` comments would be errors under v10 — we have zero (`rg "eslint-env"` returned zero hits, ✓), so the `bump-eslint-10` follow-up will not snag here either. **The ~100-error baseline is approximate and will move modestly under v9, more substantially when v10 lands.** CI's `|| true` wrapper tolerates any non-zero exit, so this is non-blocking either way. **Do not "fix while we're here."** `fix-lint-baseline` will reconcile against whichever baseline is current.
|
||||||
|
- **R13: Native flat-config import path is verbatim from Next.js docs — no `FlatCompat` shim added.** Boot-the-brief verified by extracting the published tarball that `eslint-config-next/core-web-vitals` exports a flat-config array (`module.exports = config`). Under Decision D's v9 pin, `@eslint/eslintrc` is still part of v9's own dep tree (v10 dropped it), so the lockfile retains it as a transitive dep — but we still don't import `FlatCompat` from it. If for any reason the native flat-config export resolution fails at install time (e.g. a transitive dep mismatch), the implementer should NOT swap in `@eslint/eslintrc`'s `FlatCompat` — instead, raise it in the PR description and the architect will revisit.
|
||||||
|
- **R14 — REINSTATED under Decision D (2026-05-23).** ESLint v10.4.0 is the current `latest` dist-tag; this convoy pins `eslint@^9.39.4` (the `maintenance` dist-tag) per Decision D until upstream `eslint-config-next` ships a release that bundles a v10-tested `typescript-eslint`. **Tracked under follow-up convoy `bump-eslint-10` (currently upstream-blocked)** — see "Follow-up convoys queued" section. The previous "RESOLVED at gate 1 (Decision B)" framing was correct given Boot-the-brief evidence at the time; Decision D reverses it specifically because empirical lint runs surfaced R15 firing. **Cost of pinning to maintenance:** small. v9.39.4 still receives security backports if any are needed during the window before `bump-eslint-10` lands; the v9 → v10 jump is a single-line `package.json` edit when prerequisites are met (no flat-config edits required — same `defineConfig` + `globalIgnores` shape works on both majors).
|
||||||
|
- **R15 — FIRED EMPIRICALLY (pass-2 implementer run, 2026-05-23); RESOLVED BY DECISION D.** Originally framed as: "`eslint-config-next@16.2.6`'s bundled plugin set was published before ESLint v10 (Oct 2025 vs Feb 2026); v10 runtime compatibility is statically unprovable." **What actually fired** was a different (and worse) failure mode than the originally feared `context.getCwd()` / `SourceCode#getJSDocComment()` deprecated-API removals:
|
||||||
|
- **Crash signature:** `TypeError: scopeManager.addGlobals is not a function`
|
||||||
|
- **Call site:** ESLint v10's `lib/source-code/source-code.js:221` calls `scopeManager.addGlobals(...)` as part of v10's redesigned global-ingestion path.
|
||||||
|
- **Missing-method site:** `@typescript-eslint/scope-manager@8.59.4` (transitive dep of `typescript-eslint@8.59.4`, which `eslint-config-next@16.2.6` bundles as a regular `dependency`) does not implement `addGlobals` on its `ScopeManager` class. The method is a v10-introduced extension; v9 used a different ingestion path that `typescript-eslint@8.x` was authored against.
|
||||||
|
- **Why bundled-plugin set didn't help:** `@typescript-eslint/scope-manager@8.x` was published Oct/Nov 2025; v10 GA was 2026-02-06. `typescript-eslint` has not yet shipped a v10-tested release. The peer-dep range `eslint: >=9.0.0` is technically satisfied by v10, but the runtime compatibility was not.
|
||||||
|
- **Resolution (Decision D):** revert `eslint` to `^9.39.4`. The same `typescript-eslint@8.59.4` works correctly on v9 because v9 doesn't call `addGlobals`. `typescript@^5.9.3` (Decision C) is retained — that install was confirmed correct on pass 2 and is required under both v9 and v10.
|
||||||
|
- **R15 stays in the convoy's risk list as FIRED-RESOLVED** so the historical record is preserved and so the queued `bump-eslint-10` follow-up convoy inherits the diagnostic verbatim. The originally feared deprecated-API removals (`context.getCwd()`, etc.) are still live risks for the eventual v10 cutover, but they did not fire on pass 2 — `addGlobals` fired first.
|
||||||
|
- **R16 (new, post-gate-1 Decision C; status unchanged under Decision D): Adding `typescript` as a devDep brings `typescript@^5.x` and its tooling into the dep tree.** This is universally how JS-only Next.js projects handle `eslint-config-next@16` — the package's `typescript-eslint` transitive dep (specifically `@typescript-eslint/typescript-estree@8.59.4`'s `dist/convert.js:40`) hard-requires `typescript` at runtime despite being flagged `peerDependenciesMeta.optional: true` at the `eslint-config-next` wrapper level (the `optional` annotation only suppresses npm's install-time warning, not the runtime require). **Confirmed correct under Decision D's v9 pin** — pass-2 implementer evidence shows the `typescript` install resolved the original `Cannot find module 'typescript'` crash; the residual `addGlobals` crash was a different failure mode (R15) and is the reason for the v9 revert. No downstream impact expected: `typescript` only runs when lint runs (the JS source code is unchanged, no `tsconfig.json` is created, no `.js` files are renamed); `fix-lint-baseline` and `adopt-vitest` convoys will not be affected. **Engines:** `typescript@5.9.3` requires `node >= 14.17`, well below ESLint v9's `^18.18.0` floor (and v10's `^20.19.0` floor when `bump-eslint-10` lands) — no new Node constraint introduced. **Lockfile impact:** small — `typescript` has no `dependencies` and no `peerDependencies`. **Verified runtime require evidence:** see Brief 1's Boot-the-brief finding #17 for the verbatim 9-site grep of `require('typescript')` in the published `typescript-estree@8.59.4` tarball, all unconditional (no `try/catch`, no dynamic import, no `require.resolve` guard).
|
||||||
|
### Decomposition
|
||||||
|
|
||||||
|
| Brief # | Title | Files | Depends on | Estimated PR size |
|
||||||
|
| --- | --- | --- | --- | --- |
|
||||||
|
| 1 | Bump Next.js to 16.2.6 + migrate `next.config.js`, ESLint flat config, and lint script | `package.json` (mod — `next`, `eslint`, `eslint-config-next` bumps + new `typescript` devDep per Decision C), `package-lock.json` (mod), `next.config.js` (mod), `eslint.config.mjs` (new), `.eslintrc.json` (deleted) | _(none)_ | 5 files touched (3 mod, 1 new, 1 deleted), lockfile regen (large auto-diff). True non-lockfile diff: ~31 LOC (~12 of which is the new `eslint.config.mjs`; +1 LOC for the `typescript` devDep line in `package.json`). |
|
||||||
|
|
||||||
|
**Still one brief, even after four gate-1 scope changes (A, B, C, D).** Both the Next bump and the ESLint migration touch `package.json`, so they cannot run in parallel anyway — keeping them in one brief gives reviewers one PR, one Vercel preview, and one revert boundary if anything regresses. The cumulative expansion adds ~21 LOC (delete a 40-byte file, add a ~12-LOC `eslint.config.mjs`, three devDep changes in `package.json` — two version bumps for `eslint`/`eslint-config-next` and one new line for `typescript@^5.9.3`). Decision D does not change the LOC count — it re-pins an existing line (`devDependencies.eslint`) from `^10.4.0` back to `^9.39.4`, no addition or deletion. Total non-lockfile diff stays well under the 400-LOC guideline. Decisions C and D do not change the brief count, the brief's `files:` set, or the `slice_dependencies` graph — `package.json` and `package-lock.json` were already in scope from the start. Doc-writer's `AGENTS.md` pass remains a separate PR by `role-doc-writer` per the convoy's Roles list.
|
||||||
|
|
||||||
|
The audit fan-out (`role-reviewer` + `role-design-system-auditor` + `role-a11y-auditor`) is **parallel via `/multitask`**, but that's a downstream concern triggered by the conductor after the PR is drafted — not part of the implementer decomposition.
|
||||||
|
|
||||||
|
### Slice dependencies (multitask-ready)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
slice_dependencies:
|
||||||
|
- brief: 1
|
||||||
|
depends_on: []
|
||||||
|
files:
|
||||||
|
- package.json
|
||||||
|
- package-lock.json
|
||||||
|
- next.config.js
|
||||||
|
- eslint.config.mjs
|
||||||
|
deletes:
|
||||||
|
- .eslintrc.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Single brief, no parallelization opportunity at the implementer stage. The conductor should dispatch `role-implementer` serially (no `/multitask` fan-out for the implementer phase). The audit-cohort fan-out happens later, after PR draft, under group id `audit-bump-next-js-<pr>`.
|
||||||
|
|
||||||
|
## Decisions (post-IA round)
|
||||||
|
|
||||||
|
### A — 2026-05-23: Expand convoy scope to include ESLint v8 → v9 + flat-config migration
|
||||||
|
|
||||||
|
**Context.** During the architect's initial Boot-the-brief check, two findings landed at human gate 1:
|
||||||
|
|
||||||
|
1. `eslint-config-next@16.2.6` requires `eslint >= 9.0.0` (flat config). The convoy file (line 42) prescribed bumping `eslint-config-next` to `^16` "matching next" but didn't account for this peer-dep cliff. The architect's first-pass plan pinned `eslint-config-next@15.4.2` and flagged the deviation.
|
||||||
|
2. `next lint` was removed in Next 16. `package.json`'s `lint` script and CI's `npm run lint` both invoke a removed command in 16.
|
||||||
|
|
||||||
|
**Decision.** Expand this convoy to include the ESLint v9 + flat-config migration, rather than spinning out a separate `migrate-to-eslint-flat-config` convoy. Rationale: both the Next bump and the ESLint migration touch `package.json`, so they cannot ship in parallel anyway; one PR gives reviewers a single revert boundary; the expansion adds only ~20 LOC of non-lockfile diff (delete `.eslintrc.json`, add `eslint.config.mjs`, two devDep version bumps); and `eslint-config-next@16` ships native flat-config exports so no `FlatCompat` shim or `@eslint/eslintrc` install is needed.
|
||||||
|
|
||||||
|
**Specific changes baked into Brief 1:**
|
||||||
|
|
||||||
|
- Bump `devDependencies.eslint` from `^8` to `^9.39.4` (latest 9.x; ESLint v10 was released between convoy authoring and now — see Boot-the-brief #5 — but per this decision we stay on 9.x).
|
||||||
|
- Bump `devDependencies.eslint-config-next` from `15.4.2` to `^16.2.6`.
|
||||||
|
- Change `scripts.lint` from `"next lint"` to `"eslint ."`.
|
||||||
|
- Delete `.eslintrc.json` (40-byte stub: `{"extends": "next/core-web-vitals"}`).
|
||||||
|
- Add `eslint.config.mjs` using the verbatim shape from the [official Next.js docs](https://nextjs.org/docs/app/api-reference/config/eslint): `defineConfig([...nextVitals, globalIgnores([...])])`. Imports come from `eslint/config` (built-in helpers since 9.21.0) and `eslint-config-next/core-web-vitals`.
|
||||||
|
- `globalIgnores` covers `.next/**`, `node_modules/**`, `out/**`, `build/**`, `next-env.d.ts`, and `scripts/migrations/**` per gate-1 instruction.
|
||||||
|
|
||||||
|
**Out-of-scope (still deferred):**
|
||||||
|
|
||||||
|
- Fixing the ~100-error pre-existing lint baseline. Stays under `fix-lint-baseline`. CI's `npm run lint || true` wrapper continues to tolerate non-zero exit; the baseline number will shift with the v9 plugin upgrades but counting that drift is `fix-lint-baseline`'s job.
|
||||||
|
- Bumping ESLint to v10. Surfaced as Risk R14; revisit in a later `bump-eslint-10` convoy if desired.
|
||||||
|
- Bumping React 18 → 19. Stays under `bump-react`.
|
||||||
|
- App Router migration, test-runner adoption, auth fixes, schema migrations — all unchanged from the original convoy scope.
|
||||||
|
|
||||||
|
**Canonical authority.** `tcg-vault` does not maintain `docs/04-architecture/*.md` files, so this Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`. Boot-the-brief recheck performed against this decision before publishing the revised Brief 1.
|
||||||
|
|
||||||
|
**Consequences for downstream roles.**
|
||||||
|
|
||||||
|
- `role-implementer`: must run `npm install next@^16.2.6 eslint@^9.39.4 eslint-config-next@^16.2.6` (the three explicit version pins), then delete `.eslintrc.json`, write `eslint.config.mjs` per the verbatim shape in Brief 1, and update `package.json`'s `scripts.lint`. No mid-flight scope decisions.
|
||||||
|
- `role-reviewer`: includes the ESLint config change in correctness review. Verify `npm run lint` runs (regardless of error count); verify the lockfile diff is consistent with the three version pins.
|
||||||
|
- `role-design-system-auditor` and `role-a11y-auditor`: unchanged. The lint config doesn't affect render output.
|
||||||
|
- `role-doc-writer`: still updates `AGENTS.md` "Tech stack" string (Next.js 15 → 16) in a separate PR. May optionally also update the line that says "JavaScript (not TypeScript)" remains accurate; no change needed there.
|
||||||
|
|
||||||
|
> **Superseded by Decision B (2026-05-23, same day).** The implementer command above changed from `eslint@^9.39.4` to `eslint@^10.4.0`. See entry B below for details.
|
||||||
|
|
||||||
|
### B — 2026-05-23: Pivot ESLint pin from v9.x to v10.x
|
||||||
|
|
||||||
|
**Context.** Decision A (above, same day) expanded scope to include the ESLint v8 → v9 + flat-config migration, with `eslint` pinned to `^9.39.4`. During the architect's Boot-the-brief recheck of A, finding #5 surfaced that **ESLint v10.4.0 had been released to the `latest` dist-tag on 2026-02-06** — between when this convoy was authored (2026-05-22) and when gate 1 was reached (2026-05-23). v9.39.4 had moved to the `maintenance` tag. The architect surfaced this as Risk R14 with a "stay conservative on v9" recommendation. On gate-1 re-review, the user pivoted to v10 to avoid a back-to-back `bump-eslint-10` convoy.
|
||||||
|
|
||||||
|
**Decision.** Pin `devDependencies.eslint` to `^10.4.0` (current `latest`) instead of `^9.39.4`. All other pins from Decision A stand: `next@^16.2.6`, `eslint-config-next@^16.2.6`, `.eslintrc.json` deleted, `eslint.config.mjs` created with the same verbatim shape (no v10-specific signature change in `defineConfig` or `globalIgnores`).
|
||||||
|
|
||||||
|
**Boot-the-brief recheck against v10 (no blocker found):**
|
||||||
|
|
||||||
|
1. **Peer-dep compatibility.** `npm view eslint-config-next@16.2.6 peerDependencies` returns `{"eslint": ">=9.0.0", ...}` with **no `<10` upper bound**. v10 is accepted.
|
||||||
|
2. **Node engine compatibility.** `eslint@10.4.0` engines: `node ^20.19.0 || ^22.13.0 || >=24` (tighter floor than v9's `^18.18.0 || ^20.9.0 || >=21.1.0`). CI's `setup-node@v4` with `node-version: '20'` resolves to latest 20.x ≥ 20.19; local `node@22.14.0` is in `^22.13.0`; Vercel default Node 22 is ≥ 22.13. All ✓. Residual concern (CI's "latest 20.x" is a moving target) is documented as Risk R9; pinning CI to `node-version: '20.19'` would eliminate it but is out of scope per the convoy's "Hard do not touch" list.
|
||||||
|
3. **`eslint/config` exports retained.** Extracted `eslint@10.4.0` tarball, opened `lib/config-api.js`: still re-exports `defineConfig` and `globalIgnores` from `@eslint/config-helpers`. The brief's verbatim shape is unchanged.
|
||||||
|
4. **`eslint-env` comments are errors in v10.** `rg "eslint-env"` returned zero hits in `tcg-vault` source. ✓
|
||||||
|
5. **No App-Router-only or Cache-Components surfaces affected.** v10's `eslint:recommended` updates, JSX reference tracking, and `no-shadow-restricted-names.reportGlobalThis: true` will shift the lint baseline more than v9 would have, but that's `fix-lint-baseline`'s problem (Risk R12, expanded).
|
||||||
|
|
||||||
|
**The one new risk v10 surfaces (R15 in the convoy file's Risk list):** `eslint-config-next@16.2.6` was published before ESLint v10. Its bundled plugin set (`@next/eslint-plugin-next@16.2.6`, `eslint-plugin-react@^7.37.0`, `eslint-plugin-react-hooks@^7.0.0`, `eslint-plugin-import@^2.32.0`, `eslint-plugin-jsx-a11y@^6.10.0`, `typescript-eslint@^8.46.0`) was not statically vetted against v10. If any plugin uses a v9-deprecated API that v10 removed (`context.getCwd()`, `SourceCode#getJSDocComment()`, etc.), `npm run lint` will throw `TypeError`. **Acceptance criterion: `npm run lint` runs to completion.** If it crashes, the implementer escalates and we revert to v9 (one-line change). Cost of being wrong: small.
|
||||||
|
|
||||||
|
**Out-of-scope (still deferred):**
|
||||||
|
|
||||||
|
- All items deferred under Decision A remain deferred.
|
||||||
|
- CI workflow changes (e.g. pinning `node-version: '20.19'` for ESLint v10's stricter floor) — see Risk R9 residual concern. Pickup point: next CI-touching convoy (`adopt-vitest`).
|
||||||
|
- Any `bump-eslint-10` convoy is now **closed before opening** — its work is folded into this one.
|
||||||
|
|
||||||
|
**Canonical authority.** Same as Decision A — this Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`, immediately after Decision A's gate-1 review surfaced finding R14.
|
||||||
|
|
||||||
|
**Updated consequences for downstream roles** (delta from Decision A):
|
||||||
|
|
||||||
|
- `role-implementer`: command becomes `npm install next@^16.2.6 eslint@^10.4.0 eslint-config-next@^16.2.6`. The `eslint.config.mjs` shape is unchanged. New explicit acceptance check: `npm run lint` running to completion (escalate on `TypeError`, do not patch transitive deps).
|
||||||
|
- `role-reviewer`: lockfile diff will additionally show `@eslint/eslintrc` being removed from the dep tree (v10 dropped it). Lint baseline will shift more than under v9; `|| true` wrapper still tolerates.
|
||||||
|
- `role-design-system-auditor`, `role-a11y-auditor`, `role-doc-writer`: unchanged from Decision A.
|
||||||
|
|
||||||
|
### C — 2026-05-23: Add `typescript` as a devDep (narrow scope expansion in response to implementer escalation)
|
||||||
|
|
||||||
|
**Context.** After Decisions A and B were applied, `role-implementer` ran the migration locally and `npm run lint` immediately crashed with `Cannot find module 'typescript'` during config load — before any rule executed. The implementer escalated. Root-cause diagnosis: `eslint-config-next/core-web-vitals` → `typescript-eslint@^8.46.0` → `@typescript-eslint/typescript-estree@8.59.4` does an unconditional `require('typescript')` at module load (verified after the fact by extracting the published `typescript-estree` tarball — `dist/convert.js:40` and 8 other sites are top-level `require('typescript')` calls, none gated on `try/catch` or `require.resolve`). The `peerDependenciesMeta.typescript.optional: true` annotation in `eslint-config-next@16.2.6`'s `package.json` only suppresses npm's install-time peer-dep warning; it does NOT make `typescript` runtime-optional. **The architect's Boot-the-brief finding #8 misread this annotation** and stated "tcg-vault is JS-only, no `typescript` install needed." That assumption was wrong, and the implementer caught it on first run.
|
||||||
|
|
||||||
|
This is **NOT** a manifestation of Risk R15 (no `TypeError` on a deprecated v9 API; the crash happened before any rule loaded). Reverting to ESLint v9 would not have fixed it — the same `typescript-eslint` chain ships with `eslint-config-next@16` regardless of the ESLint major version.
|
||||||
|
|
||||||
|
**The decision.** User chose **option (a) — add `typescript` as a devDep** at the gate. One-line scope expansion, ~minimal-risk:
|
||||||
|
|
||||||
|
- `package.json` adds `devDependencies.typescript: "^5.9.3"`.
|
||||||
|
- `package-lock.json` regenerates accordingly. The new `typescript` subtree is small (TypeScript itself has no `dependencies` and no `peerDependencies`).
|
||||||
|
- Pin choice: `^5.9.3`. **Note:** `npm view typescript@latest version` returns `6.0.3` (TypeScript 6 is the current `latest` major, contrary to the gate's parenthetical claim that 5 was latest). Latest 5.x is `5.9.3`. Two reasons to pin `^5.9.3` and defer v6: (1) honor the literal gate-1 instruction (`^5`); (2) `typescript-eslint@8.59.4`'s peer range is `>=4.8.4 <6.1.0` — strictly, `typescript@6.0.3` is in range, but `typescript-eslint@8.x` was published before TS 6 GA and has not advertised explicit v6 support, so staying inside the well-trodden 5.x range is safer until a future convoy bumps `typescript-eslint`. `^5.9.3` resolves to the latest 5.x patch.
|
||||||
|
- Pin range scope: full SemVer caret (`^5.9.3`), matching the convention used by `next` (`^15.4.2` → `^16.2.6`) and `react` (`^18.3.1`) elsewhere in `package.json`.
|
||||||
|
- No new files. No `tsconfig.json`. No `.js` → `.ts` migration. The brief's `files:` set is unchanged (`package.json` and `package-lock.json` were already in scope as modifications). The `slice_dependencies` graph is unchanged.
|
||||||
|
- No `eslint.config.mjs` change. The flat-config shape is independent of whether `typescript` is installed.
|
||||||
|
|
||||||
|
**Why option b (replace `eslint-config-next` with a JS-only ESLint preset) was dismissed.** `eslint-config-next@16` does not ship a JS-only entry point. Its `core-web-vitals` export bundles `typescript-eslint` as a regular dependency (not a peer), so consumers cannot opt out without forking the package or reimplementing the rule set. Maintaining a fork is a much larger scope expansion than adding `typescript` as a devDep, and gives up the upstream guarantee that the rule set tracks Next.js best practices.
|
||||||
|
|
||||||
|
**Why option c (keep things broken; CI's `|| true` wrapper tolerates lint failures) was dismissed.** CI's `|| true` wrapper tolerates a non-zero exit code from `eslint`, but it does NOT tolerate a `MODULE_NOT_FOUND` thrown during config load — the crash happens before ESLint emits any structured output, and the wrapper still passes the exit code to the shell, but **lint stops being a useful signal entirely**. Every CI lint run would be a no-op pass. That regresses the lint surface to "always green, regardless of code quality" and silently invalidates the `fix-lint-baseline` convoy's premise (which assumes lint at least executes). Unacceptable.
|
||||||
|
|
||||||
|
**Out-of-scope (still deferred):**
|
||||||
|
|
||||||
|
- All items deferred under Decisions A and B remain deferred.
|
||||||
|
- TypeScript adoption as a project language (no `tsconfig.json`, no `.ts`/`.tsx` source files, no `// @ts-check` directives, no `.d.ts` declaration files). `typescript` is installed purely so `eslint-config-next`'s lint chain can load. If the team later decides to migrate to TypeScript, that's an explicit, separate convoy — not a "while we're here."
|
||||||
|
- Adding `@typescript-eslint/parser` or `@typescript-eslint/eslint-plugin` directly. They're already pulled in transitively by `eslint-config-next@16`; no direct dep needed.
|
||||||
|
- CI workflow changes (still per Decision B's deferral note — pickup point is `adopt-vitest`).
|
||||||
|
|
||||||
|
**Canonical authority.** This Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`, immediately after the implementer's escalation on first lint run. Boot-the-brief #8's misreading of `peerDependenciesMeta.optional` is corrected in place in `brief-1-bump-next-and-migrate-config.md` (finding #8 marked "🔴 SUPERSEDED by Decision C"; new findings #16–#18 added under "Decision C narrow recheck").
|
||||||
|
|
||||||
|
**Updated consequences for downstream roles** (delta from Decision B):
|
||||||
|
|
||||||
|
- `role-implementer`: command becomes `npm install next@^16.2.6 eslint@^10.4.0 eslint-config-next@^16.2.6 typescript@^5.9.3` (or equivalently, run the previous three-package install, then run `npm install --save-dev typescript@^5.9.3` as a follow-up — order doesn't matter; the lockfile is regenerated either way). Re-run `npm run lint` after the install; expectation is now that lint completes with the pre-existing baseline of errors (no `Cannot find module 'typescript'` crash). Failure-mode classification: see Brief 1's "Local verification" section — `Cannot find module 'typescript'` post-install means the install didn't take and is not R15; a `TypeError: context.getCwd is not a function` (or similar v9-deprecated-API error) is R15 and triggers a v9 fallback (keeping the `typescript` install).
|
||||||
|
- `role-reviewer`: lockfile diff will now additionally show the `typescript` package being added. The diff is small (TypeScript has no transitive deps). Verify the brief's no-scope-expansion guardrails were respected — specifically that no `tsconfig.json` was created and no `.js` files were renamed to `.ts`/`.tsx`.
|
||||||
|
- `role-design-system-auditor`, `role-a11y-auditor`, `role-doc-writer`: unchanged from Decisions A and B.
|
||||||
|
|
||||||
|
### D — 2026-05-23: Revert ESLint v10 → v9.39.4 after R15 fired empirically; queue `bump-eslint-10` as upstream-blocked follow-up
|
||||||
|
|
||||||
|
**Context.** After Decisions A, B, and C were applied, `role-implementer` ran the migration locally a second time (pass 2). The Decision-C `typescript` install resolved the original `Cannot find module 'typescript'` crash from pass 1 — but the lint run then surfaced a different `TypeError`:
|
||||||
|
|
||||||
|
- **Crash signature:** `TypeError: scopeManager.addGlobals is not a function`
|
||||||
|
- **Call site:** ESLint v10's `lib/source-code/source-code.js:221` calls `scopeManager.addGlobals(...)` as part of v10's redesigned global-ingestion path.
|
||||||
|
- **Missing-method site:** `@typescript-eslint/scope-manager@8.59.4` (transitive dep of `typescript-eslint@8.59.4`, which `eslint-config-next@16.2.6` bundles as a regular `dependency`) does not implement `addGlobals` on its `ScopeManager` class.
|
||||||
|
- **Why:** `@typescript-eslint/scope-manager@8.x` was published Oct/Nov 2025; ESLint v10 GA was 2026-02-06. The `addGlobals` method is a v10-introduced extension of the `ScopeManager` interface; v9 used a different ingestion path. `typescript-eslint` has not yet shipped a v10-tested release that adds the method.
|
||||||
|
|
||||||
|
This is **the empirical firing of Risk R15**, in a different shape than originally feared. The principal failure mode anticipated at Decision B was a v9-deprecated-API removal (`context.getCwd()`, `SourceCode#getJSDocComment()`, etc.); the actual failure was a v10-introduced-method gap on the typescript-eslint side. Either way, the diagnosis is the same: `eslint-config-next@16.2.6`'s pre-v10-GA bundled plugin set is not runtime-compatible with v10. Reverting `eslint` to v9 is the only working option until upstream catches up.
|
||||||
|
|
||||||
|
**The decision.** User chose **option (a) — execute the brief's documented v9 fallback path AND formally queue a follow-up `bump-eslint-10` convoy** at the gate. This partially reverses Decision B's "avoid back-to-back convoys" rationale, but **Decision B was correct given Boot-the-brief evidence at the time** — the v10 incompat was statically unprovable until a real lint run hit `addGlobals`. Empirical evidence from pass 2 reverses the call.
|
||||||
|
|
||||||
|
Specific changes:
|
||||||
|
|
||||||
|
- `package.json`: re-pin `devDependencies.eslint` from `"^10.4.0"` back to `"^9.39.4"` (npm's `maintenance` dist-tag).
|
||||||
|
- **`devDependencies.typescript: "^5.9.3"` (Decision C) is RETAINED.** Boot-the-brief recheck #17 confirmed at Decision C, and the implementer's pass-2 evidence reconfirmed, that the same `typescript-eslint@8.59.4` chain hard-`require`s `typescript` under v9 too. The typescript install is correct independent of the eslint pin.
|
||||||
|
- **`eslint-config-next@^16.2.6` is unchanged** — its peer-dep `eslint: ">=9.0.0"` accepts v9.39.4 trivially; no `<10` upper bound shift since Decision B's verification.
|
||||||
|
- **`next@^16.2.6` is unchanged.**
|
||||||
|
- **`eslint.config.mjs` shape is unchanged.** `defineConfig` and `globalIgnores` from `eslint/config` were introduced in 9.21.0 and retained in v10.4.0; the same import line resolves correctly on both v9.39.4 and v10.4.0. **This is the load-bearing reason Decision D is a one-line `package.json` re-pin and not a multi-file rollback.** When `bump-eslint-10` lands, this file should not need to change.
|
||||||
|
- Install command for the implementer: `npm install --save-dev eslint@^9.39.4 eslint-config-next@^16.2.6 typescript@^5.9.3` (single atomic command preferred; running them separately is equivalent — the lockfile regenerates either way).
|
||||||
|
|
||||||
|
**Why option b (npm overrides to force a v10-compat `@typescript-eslint/scope-manager`) was dismissed.** The brief explicitly forbids transitive patching ("do NOT patch the plugin or pin transitive deps mid-flight"). There's no guarantee that any released version of `@typescript-eslint/scope-manager` exists with the v10 fix at a version `eslint-config-next@16.2.6` will resolve to under its bundled `typescript-eslint@^8.46.0` constraint. Even if such a version existed, npm overrides bypass the upstream maintainer's compatibility testing entirely — we'd be hand-rolling a custom dep tree that no other project uses, which moves the maintenance burden to us.
|
||||||
|
|
||||||
|
**Why option c (wait for upstream) was dismissed.** Doesn't unblock the Vercel deploys gate that's the convoy's success metric ("npm install next@16.2.6 ships, Vercel deploys complete, no runtime regressions in dev or build"). The convoy's premise is that Vercel was rejecting `next@^15.4.2` as a "Vulnerable version of Next.js"; we have to ship `next@^16.2.6` now. Pinning `eslint` to v9 lets us do that today; v10 can land later when prerequisites are met.
|
||||||
|
|
||||||
|
**Why option d (ship with the lint crash) was dismissed.** Same reasoning as Decision C's option-c dismissal: CI's `|| true` wrapper tolerates a non-zero exit code, but a `TypeError` crash before any rule executes means lint emits no useful signal at all — every CI lint run becomes a no-op pass, and `fix-lint-baseline`'s premise (lint at least executes) collapses. Unacceptable.
|
||||||
|
|
||||||
|
**Reversal of Decision B's "avoid back-to-back `bump-eslint-10` convoy" rationale.** Acknowledged. Decision B's argument was: pivot to v10 now to avoid a follow-up convoy. That argument was correct given the static evidence available at the time of Decision B (peer-dep ranges accepted v10; Boot-the-brief found no obvious incompatibilities). Decision D's empirical evidence — a `TypeError` from a real lint run — supersedes the static evidence. The follow-up `bump-eslint-10` convoy is now formally queued (see "Follow-up convoys queued" section below); it will land as a single-brief mechanical bump once upstream prerequisites are met.
|
||||||
|
|
||||||
|
**Out-of-scope (still deferred):**
|
||||||
|
|
||||||
|
- All items deferred under Decisions A, B, and C remain deferred.
|
||||||
|
- The `bump-eslint-10` follow-up is queued, not authored. The conductor will materialize a convoy file when a human authors one (likely after `typescript-eslint` ships a v10-tested release and `eslint-config-next` bundles it).
|
||||||
|
- npm `overrides` field manipulation, transitive-dep pinning, plugin forking — all forbidden as scope expansion under both this convoy and the future `bump-eslint-10`.
|
||||||
|
|
||||||
|
**Canonical authority.** This Decisions entry IS the canonical authority. Decision recorded in chat on 2026-05-23 between user and `role-architect`, immediately after the pass-2 implementer escalation surfaced R15's `addGlobals` firing.
|
||||||
|
|
||||||
|
**Updated consequences for downstream roles** (delta from Decision C):
|
||||||
|
|
||||||
|
- `role-implementer`: re-run `npm install --save-dev eslint@^9.39.4` (the other three packages — `next@^16.2.6`, `eslint-config-next@^16.2.6`, `typescript@^5.9.3` — are already at correct versions from Decision C's run); re-run `npm run lint`. **Expectation:** exit code 1 or 2 (baseline lint errors present) is fine; exit code 0 is improbable until `fix-lint-baseline`. **NOT expected:** a `TypeError` crash. R15's `scopeManager.addGlobals` signature should not recur on v9 because v9 doesn't call `addGlobals`. If a different `TypeError` fires on v9, escalate via the brief's failure-mode classifier.
|
||||||
|
- `role-reviewer`: lockfile diff under Decision D stays on the v9 dep-tree; `@eslint/eslintrc` (a v9 transitive) remains present. Verify that `package.json` has `eslint: "^9.39.4"` (not `^10.x`), `typescript: "^5.9.3"`, `eslint-config-next: "^16.2.6"`, and `next: "^16.2.6"`.
|
||||||
|
- `role-design-system-auditor`, `role-a11y-auditor`, `role-doc-writer`: unchanged from Decisions A, B, C. Doc-writer's `AGENTS.md` pass should mention the `bump-eslint-10` queued convoy if the doc-writer pass surfaces lint-toolchain documentation.
|
||||||
|
- **Future `bump-eslint-10` implementer:** inherits R15's diagnostic verbatim. The convoy will become a single-brief mechanical bump once `typescript-eslint` ships v10 support and `eslint-config-next` bundles it; until then, the convoy is upstream-blocked and not authored.
|
||||||
|
|
||||||
|
## Follow-up convoys queued
|
||||||
|
|
||||||
|
The following convoys are formally queued by `role-architect` as upstream-blocked follow-ups to this convoy. They are NOT authored as convoy files yet — they exist in this list only. The conductor will materialize a convoy file when a human authors one and the upstream prerequisites are met.
|
||||||
|
|
||||||
|
### `bump-eslint-10` — upstream-blocked
|
||||||
|
|
||||||
|
- **Origin.** Queued under Decision D (2026-05-23) after R15 fired empirically. Decision B's pivot to v10 was reverted; v10 is still the supported `latest` and we want to land it eventually.
|
||||||
|
- **Prerequisites (both must be met before the convoy can run):**
|
||||||
|
1. `typescript-eslint` ships a v10-tested release. Likely shape: `@typescript-eslint/scope-manager` adds the `addGlobals` method (and any other v10-introduced `ScopeManager` interface members) on the v8.x line as a backport, OR the typescript-eslint v9 line ships and adds them. Either way, the release notes will explicitly mention ESLint v10 compatibility.
|
||||||
|
2. `eslint-config-next` bundles a v10-tested `typescript-eslint`. Likely shape: a `16.3+` release that bumps the `typescript-eslint` direct dependency. Confirmed by reading the `eslint-config-next` `package.json` `dependencies.typescript-eslint` range and cross-referencing typescript-eslint's release notes.
|
||||||
|
- **Convoy shape (when materialized):** single-brief mechanical bump matching this convoy's Brief 1 shape. Files: `package.json` (re-pin `eslint` from `^9.39.4` to `^10.x.y`; re-pin `eslint-config-next` if a new minor bundles the v10-tested typescript-eslint), `package-lock.json` (regenerate). No code-shape changes expected — `eslint.config.mjs` is verified compatible on both v9 and v10. No CI workflow changes unless the Node-version pin question (originally raised under R9) bites at v10's stricter floor.
|
||||||
|
- **Risks inherited from this convoy:** R12's "lint baseline shifts more under v10" warning resurfaces; the three new `eslint:recommended` rules, JSX reference tracking, `no-shadow-restricted-names.reportGlobalThis: true` default, and `eslint-env`-comments-as-errors transition all happen at this convoy. CI's `|| true` wrapper still tolerates. R9's CI moving-target concern (`node-version: '20'` resolution) reactivates under v10's `^20.19.0` floor; the `bump-eslint-10` brief should pin CI to `node-version: '20.19'` or `'lts/iron'` if the target convoy permits CI workflow changes.
|
||||||
|
- **Cost of being wrong about prerequisites:** small. If `typescript-eslint` ships a v10-tested release and `eslint-config-next` bundles it but `bump-eslint-10` still surfaces a different incompat at runtime, the convoy itself documents another decision letter and re-pins back to v9 again. The cost is one extra Boot-the-brief recheck and one extra Decisions entry.
|
||||||
|
|
||||||
|
### `bump-typescript-6` — upstream-blocked
|
||||||
|
|
||||||
|
- **Origin.** Queued under Decision D (2026-05-23). Surfaced during Decision C's Boot-the-brief recheck (#16): `npm view typescript@latest` returned `6.0.3` (latest major), but `^5.9.3` was pinned because `typescript-eslint@8.59.4`'s peer range `>=4.8.4 <6.1.0` accepts but doesn't certify v6.
|
||||||
|
- **Prerequisites:**
|
||||||
|
1. `typescript-eslint` advertises explicit v6 support in a release. Currently the peer range accepts `<6.1.0` (so `typescript@6.0.x` is technically in range) but typescript-eslint has not announced v6 testing. Likely shape: a release-notes entry titled "TypeScript 6 support" or a peer-range bump to `<7.0.0` once they're confident.
|
||||||
|
2. (Optional) `eslint-config-next` bundles a `typescript-eslint` version that advertises v6 support. Not strictly required — `typescript@^5.x` in `bump-eslint-10` and `typescript@^6.x` here can be re-pins on different days.
|
||||||
|
- **Convoy shape (when materialized):** single-brief mechanical bump. Files: `package.json` (re-pin `typescript` from `^5.9.3` to `^6.x.y`), `package-lock.json` (regenerate). No code-shape changes — TypeScript is only used by ESLint's lint chain, not by source files (no `tsconfig.json`, no `.ts` files; the `bump-typescript-6` convoy must preserve those guardrails).
|
||||||
|
- **Risks inherited from this convoy:** none specific. The verified runtime require evidence in Brief 1 #17 stays valid (typescript-estree's `require('typescript')` sites are unconditional regardless of TS major).
|
||||||
|
- **Cost of being wrong about prerequisites:** small. Same fallback shape as `bump-eslint-10`.
|
||||||
|
|
||||||
|
### Notes on materialization
|
||||||
|
|
||||||
|
These two convoys can land independently, in either order. Neither blocks the other. The conductor should expect a human to author the convoy file (frontmatter + IA + UX) when they decide to land the upgrade; `role-architect` does not pre-author convoy files for upstream-blocked follow-ups (no Boot-the-brief evidence exists yet to verify against).
|
||||||
|
|
||||||
216
.convoys/bump-next-js/brief-1-bump-next-and-migrate-config.md
Normal file
216
.convoys/bump-next-js/brief-1-bump-next-and-migrate-config.md
Normal file
|
|
@ -0,0 +1,216 @@
|
||||||
|
---
|
||||||
|
convoy: bump-next-js
|
||||||
|
brief_number: 1
|
||||||
|
depends_on: []
|
||||||
|
files:
|
||||||
|
- package.json
|
||||||
|
- package-lock.json
|
||||||
|
- next.config.js
|
||||||
|
- eslint.config.mjs
|
||||||
|
deletes:
|
||||||
|
- .eslintrc.json
|
||||||
|
---
|
||||||
|
|
||||||
|
# Brief 1: Bump Next.js to 16.2.6 + migrate `next.config.js`, ESLint flat config, and lint script
|
||||||
|
|
||||||
|
## Goal (1 sentence)
|
||||||
|
|
||||||
|
Replace `next@15.4.3` with `next@16.2.6` so Vercel's platform-level security gate stops blocking every deploy, while paying off the three blockers the upgrade actually introduces in `tcg-vault`: the deprecated `images.domains` config, the **removed** `next lint` command (which forces a `package.json` script change AND an ESLint v8 → **v10** + flat-config migration so `eslint-config-next` can be bumped to `^16` to match `next`), and Turbopack-by-default (no code change required, just informed acceptance).
|
||||||
|
|
||||||
|
## Files in scope (do not edit anything else)
|
||||||
|
|
||||||
|
- `package.json` — modified
|
||||||
|
- `package-lock.json` — modified (regenerated)
|
||||||
|
- `next.config.js` — modified
|
||||||
|
- `eslint.config.mjs` — **new**
|
||||||
|
- `.eslintrc.json` — **deleted**
|
||||||
|
|
||||||
|
## Conventions to follow
|
||||||
|
|
||||||
|
- `AGENTS.md` § "Tech stack quick reference": Next.js 15 (Pages router) → bump the framework version string only as part of the doc-writer pass, not in this brief. **Do not edit `AGENTS.md` here.** That's a separate role-doc-writer PR.
|
||||||
|
- `.cursor/rules/no-go-zones.mdc`: do not touch anything outside `files:` above. In particular: no edits to `pages/`, `components/`, `lib/`, `scripts/`, `styles/`, or any workflow file.
|
||||||
|
- `package.json` formatting: 2-space indent, double-quoted keys/values, trailing newline. Match existing style.
|
||||||
|
- `next.config.js` formatting: ESM (`export default nextConfig`), 2-space indent, JSDoc `@type` comment preserved.
|
||||||
|
- `eslint.config.mjs` formatting: ESM, 2-space indent, no semicolons-only-when-needed convention (match the verbatim shape from the official Next.js docs cited below).
|
||||||
|
- The lock file must be regenerated by `npm install`, not hand-edited.
|
||||||
|
|
||||||
|
## Acceptance criteria
|
||||||
|
|
||||||
|
### `package.json` changes
|
||||||
|
|
||||||
|
- [ ] `dependencies.next` is `"^16.2.6"` (from `"^15.4.2"`).
|
||||||
|
- [ ] `dependencies.react` and `dependencies.react-dom` stay at `"^18.3.1"`. Next 16 peer-deps accept `react ^18.2.0 || ^19.0.0`; current `18.3.1` is in range. React 19 is its own convoy.
|
||||||
|
- [ ] `devDependencies.eslint` is `"^9.39.4"` (from `"^8"`). **Per gate-1 Decision D (2026-05-23), reverted from `^10.4.0` back to `^9.39.4` after R15 fired empirically on the implementer's pass-2 run** (`TypeError: scopeManager.addGlobals is not a function` from ESLint v10's `source-code.js:221` calling a method that `@typescript-eslint/scope-manager@8.59.4` — bundled by `eslint-config-next@16.2.6`, published before v10 GA — does not implement). v10 will be picked up under the queued follow-up convoy `bump-eslint-10` once `typescript-eslint` ships a v10-tested release and `eslint-config-next` bundles it. v9.39.4 is on npm's `maintenance` dist-tag (current `latest` is 10.4.0). See Boot-the-brief findings #5–#10 below for the v10-pivot verification (now historical) and the Decision D recheck below for v9 sanity.
|
||||||
|
- [ ] `devDependencies.eslint-config-next` is `"^16.2.6"` (from `"15.4.2"`). `eslint-config-next@16.2.6`'s peer dep `eslint: ">=9.0.0"` accepts v9.39.4 (re-verified via `npm view eslint-config-next@16.2.6 peerDependencies`).
|
||||||
|
- [ ] `devDependencies.typescript` is `"^5.9.3"` (newly added). **Per gate-1 Decision C (2026-05-23), `typescript` is a hard runtime requirement** of `eslint-config-next@16.2.6` despite its package.json's `peerDependenciesMeta.typescript.optional: true` annotation. The annotation only suppresses npm's install-time warning; it does NOT mean the runtime path is optional. `eslint-config-next` bundles `typescript-eslint@^8.46.0`, whose `@typescript-eslint/typescript-estree@8.59.4` dependency does an unconditional `require('typescript')` at module load (verified at `dist/convert.js:40` of the published tarball). Without `typescript` installed, `npm run lint` crashes with `Cannot find module 'typescript'` before any rule runs. See Boot-the-brief findings #8 (superseded) and #16–#17 below.
|
||||||
|
- [ ] `scripts.lint` is `"eslint ."` (from `"next lint"`). The `next lint` command was removed in Next.js 16; it would throw at runtime if left in place.
|
||||||
|
- [ ] No new direct dependencies are added beyond the four already listed (`next` bumped, `eslint` bumped, `eslint-config-next` bumped, `typescript` newly added). **In particular, do NOT add `@eslint/eslintrc`** — `eslint-config-next@16.2.6` ships native flat-config exports, so no `FlatCompat` shim is needed (see Boot-the-brief finding #1). Do NOT add `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin`, `tsx`, `ts-node`, or any other TS toolchain — `typescript` alone resolves the lint crash.
|
||||||
|
- [ ] No new `engines` block is added to `package.json`. Node 20.19+ is required by `eslint@10` (`next@16` requires 20.9+), but the existing `setup-node@v4` step in `.github/workflows/ci.yml` (`node-version: '20'`, which resolves to latest 20.x ≥ 20.19) and Vercel's default Node 22 runtime both satisfy this. Adding an `engines` block is out of scope (see Risk R9 for the residual CI-pin concern).
|
||||||
|
|
||||||
|
### `package-lock.json` changes
|
||||||
|
|
||||||
|
- [ ] Regenerated via `npm install` (no hand edits).
|
||||||
|
- [ ] `npm ls next` reports `next@16.2.6`.
|
||||||
|
- [ ] `npm ls eslint` reports `eslint@9.39.x` (or whatever 9.x patch `^9.39.4` resolves to). **Not `10.x`** — see Decision D below.
|
||||||
|
- [ ] `npm ls eslint-config-next` reports `eslint-config-next@16.2.x`.
|
||||||
|
- [ ] `npm ls typescript` reports `typescript@5.9.x` (latest 5.x; per Decision C — see Boot-the-brief #16 for the v6 deferral rationale).
|
||||||
|
- [ ] `npm install` exits cleanly with no `ERESOLVE` peer-dep failures and no `npm warn deprecated` for any of the four packages above. (Note: under Decision D the lockfile diff stays on the v9 dep-tree — `@eslint/eslintrc` is still present as a v9 transitive dep; the v10 dep-tree changes that would have removed it are deferred to the queued `bump-eslint-10` follow-up convoy. The new `typescript` subtree should still be small — TypeScript itself has no `dependencies`.)
|
||||||
|
|
||||||
|
### `next.config.js` changes
|
||||||
|
|
||||||
|
- [ ] Migrates `images.domains` → `images.remotePatterns`. Verbatim shape (from the [official Next 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16) § "`images.domains` Configuration (deprecated)"):
|
||||||
|
|
||||||
|
```js
|
||||||
|
/** @type {import('next').NextConfig} */
|
||||||
|
const nextConfig = {
|
||||||
|
images: {
|
||||||
|
remotePatterns: [
|
||||||
|
{ protocol: 'https', hostname: 'api.scryfall.com' },
|
||||||
|
{ protocol: 'https', hostname: 'images.pokemontcg.io' },
|
||||||
|
{ protocol: 'https', hostname: 'lorcana-api.com' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
export default nextConfig;
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] No other keys are added to `next.config.js`. In particular: do **not** add `cacheComponents`, `reactCompiler`, `turbopack`, or `experimental.*` flags. Those are opt-in features for follow-up convoys. **Do not** add `--webpack` opt-out — see Risk R1.
|
||||||
|
|
||||||
|
### `.eslintrc.json` deletion + `eslint.config.mjs` creation
|
||||||
|
|
||||||
|
- [ ] `.eslintrc.json` is deleted. (It currently contains exactly `{"extends": "next/core-web-vitals"}`. ESLint v9 still tolerates legacy `.eslintrc.*` if `ESLINT_USE_FLAT_CONFIG=false` is set, but the codebase is moving to flat config; leaving both files would be a footgun.)
|
||||||
|
- [ ] `eslint.config.mjs` is created with the verbatim shape below. **This shape comes directly from the [official Next.js docs for `eslint-config-next` v16+](https://nextjs.org/docs/app/api-reference/config/eslint)** — do not improvise, do not add new rules, do not "while we're here" any plugin disables. The only deviation from the docs example is one extra path (`scripts/migrations/**`) added to `globalIgnores` per the user's gate-1 instruction.
|
||||||
|
|
||||||
|
```js
|
||||||
|
import { defineConfig, globalIgnores } from 'eslint/config';
|
||||||
|
import nextVitals from 'eslint-config-next/core-web-vitals';
|
||||||
|
|
||||||
|
const eslintConfig = defineConfig([
|
||||||
|
...nextVitals,
|
||||||
|
globalIgnores([
|
||||||
|
'.next/**',
|
||||||
|
'node_modules/**',
|
||||||
|
'out/**',
|
||||||
|
'build/**',
|
||||||
|
'next-env.d.ts',
|
||||||
|
'scripts/migrations/**',
|
||||||
|
]),
|
||||||
|
]);
|
||||||
|
|
||||||
|
export default eslintConfig;
|
||||||
|
```
|
||||||
|
|
||||||
|
Notes for the implementer (do not include these as comments in the file — they're for the PR description):
|
||||||
|
|
||||||
|
- **The verbatim shape is unchanged across the v8 → v9 (Decision A) → v10 (Decision B) → v9 (Decision D) ping-pong.** `defineConfig` and `globalIgnores` from `eslint/config` exist in both v9.39.4 (added 9.21.0) and v10.4.0 (retained); the import line works identically on both majors. Decision D rolls back only the `package.json` pin — no flat-config edit required. When the queued `bump-eslint-10` follow-up convoy lands, this file should not need to change.
|
||||||
|
- `defineConfig` and `globalIgnores` are built-in helpers exported from `eslint/config` (added in ESLint 9.21.0, retained in v10). `eslint@9.39.4` has them; `eslint@10.4.0` would also have them, but Decision D pins v9.39.4.
|
||||||
|
- `eslint-config-next/core-web-vitals` is a CommonJS array re-exported as the default — spreadable with `...nextVitals` (verified by extracting the `eslint-config-next@16.2.6` tarball; see Boot-the-brief finding #1).
|
||||||
|
- `eslint-config-next` already includes default ignores for `.next/**`, `out/**`, `build/**`, and `next-env.d.ts`. We restate them here to match the docs example exactly and to be explicit about what's ignored.
|
||||||
|
- `node_modules/**` is added explicitly even though ESLint default-ignores it; user's gate-1 instruction lists it as a minimum-cover ignore.
|
||||||
|
- `scripts/migrations/**` is preemptive — the folder doesn't exist yet (`.cursor/rules/no-go-zones.mdc` calls it "TBD"), but we ignore it now so the eventual migration script convoy doesn't have to remember to.
|
||||||
|
- `next-env.d.ts` doesn't exist in `tcg-vault` (JS-only project, no TS). Including it is harmless and matches the docs example verbatim.
|
||||||
|
- **No `parserOptions`, no `rules:` overrides, no `settings:` block.** This brief preserves the exact lint behavior of the previous `.eslintrc.json` extends. Any rule tuning belongs in `fix-lint-baseline`.
|
||||||
|
|
||||||
|
### Local verification (run before pushing)
|
||||||
|
|
||||||
|
- [ ] `npm install` resolves cleanly with no `ERESOLVE` peer-dep failures.
|
||||||
|
- [ ] `npm ls next eslint eslint-config-next` prints the three expected versions (16.2.6, 10.4.x, 16.2.x).
|
||||||
|
- [ ] `npm run dev` boots, prints something like `▲ Next.js 16.2.6 (Turbopack)`, and serves `/` without runtime errors. **No deprecation warning about `images.domains`** is logged at startup.
|
||||||
|
- [ ] `npm run build` exits with code 0. (Turbopack is the default bundler in 16; tcg-vault has no `webpack:` block in `next.config.js`, so no `--webpack` opt-out is needed.)
|
||||||
|
- [ ] Manually smoke the routes `TESTING_GUIDE.md` calls out: `/`, `/login`, `/signup`, `/cards`, `/collections`. They render the same as before — no React hydration errors, no 500s.
|
||||||
|
- [ ] **`npm run lint` runs ESLint v9.39.4 to completion without a `TypeError` crash, emitting the pre-existing baseline of ~100 errors.** This is the integration test for the v8 → v9 + flat-config + `typescript`-devDep migration. Exit code 1 (lint errors present) is **expected**; exit code 0 is improbable until `fix-lint-baseline` runs; CI's `|| true` wrapper tolerates either. **Do not fix lint errors in this brief.** Counting the exact baseline is `fix-lint-baseline`'s job.
|
||||||
|
- [ ] **If `npm run lint` crashes after `typescript@^5.9.3` is installed AND `eslint@^9.39.4` is pinned**, classify the failure mode:
|
||||||
|
- `Cannot find module 'typescript'` or similar module-resolution error → **`typescript` install didn't take.** Re-run `npm install`; verify `node_modules/typescript/package.json` exists; verify `package.json` `devDependencies.typescript` is `"^5.9.3"`. Do not investigate further — this should be deterministic now that Decision C is in place.
|
||||||
|
- `TypeError: scopeManager.addGlobals is not a function` (or any other `scopeManager.*` / `SourceCode.*` `is not a function` error) → **`eslint` pin didn't take, you're still on v10.** Re-run `npm install`; verify `node_modules/eslint/package.json` reports `9.39.x`; verify `package.json` `devDependencies.eslint` is `"^9.39.4"`. This was Risk R15's empirical signature on the pass-2 implementer run; it should NOT recur once v9 is pinned. If it does recur on v9 with a different `is not a function` shape (hypothetically — no evidence this happens), escalate to `role-architect` rather than patching transitive deps.
|
||||||
|
- `TypeError: context.getCwd is not a function` / `SourceCode.prototype.getJSDocComment is not a function` (the v9-deprecated-API signatures originally feared at Decision B) — **not expected on v9** because these APIs are still present in v9 (only removed in v10). If this fires anyway, escalate; do not patch.
|
||||||
|
- Anything else (parse error in a source file, unhandled exception in a rule) → **Lint baseline drift.** This is `fix-lint-baseline`'s problem, not this convoy's. CI's `|| true` wrapper tolerates it.
|
||||||
|
|
||||||
|
### Vercel preview verification (after pushing the PR)
|
||||||
|
|
||||||
|
- [ ] Vercel produces a Preview deployment whose status moves to **Success** (not "Error" / "Vulnerable version of Next.js detected").
|
||||||
|
- [ ] The Preview URL renders `/` end-to-end (not just the build page).
|
||||||
|
- [ ] Capture the Preview URL in the PR description so reviewers (`role-reviewer`, `role-design-system-auditor`, `role-a11y-auditor`) can hit it during the audit fan-out.
|
||||||
|
|
||||||
|
### No-scope-expansion guardrails
|
||||||
|
|
||||||
|
- [ ] No file outside the `files:` / `deletes:` lists is modified.
|
||||||
|
- [ ] No new dependencies beyond the four already specified (two devDep version bumps — `eslint`, `eslint-config-next`; one new devDep — `typescript`; one regular dep bump — `next`). In particular: no `@eslint/eslintrc`, no `@eslint/js`, no `@typescript-eslint/parser`, no `@typescript-eslint/eslint-plugin`, no `tsx`, no `ts-node`, no `babel-plugin-react-compiler`, no `@playwright/test`, no `vitest`. Those belong to other convoys.
|
||||||
|
- [ ] No `eslint.config.mjs` rule tuning beyond the documented `globalIgnores` list. If `eslint-config-next@16` + `eslint@10` surfaces additional warnings/errors, defer to `fix-lint-baseline`.
|
||||||
|
- [ ] **No `tsconfig.json` is created.** Decision C adds `typescript` as a devDep purely so `eslint-config-next@16`'s bundled `typescript-eslint` chain can `require('typescript')` at module load — `tcg-vault` remains a JavaScript project and no source files are migrated to `.ts` / `.tsx`. If a future convoy adopts TypeScript, that's a separate, explicit decision.
|
||||||
|
- [ ] No `.js` / `.jsx` files are renamed to `.ts` / `.tsx`. No `// @ts-check` directives are added. No `.d.ts` declaration files are created.
|
||||||
|
- [ ] No `AGENTS.md` edits. Doc-writer pass happens in a separate PR via `role-doc-writer`.
|
||||||
|
- [ ] No `<Image>` or `<img>` migrations. Audit confirmed `tcg-vault` does not import `next/image` anywhere; pages use plain `<img>`. The `images.remotePatterns` config is being kept (rather than deleted) because it's pre-staged for the eventual `next/image` adoption.
|
||||||
|
- [ ] No `tests added` checkbox: tcg-vault has no test runner installed yet. Adoption is tracked under `adopt-vitest`. Manual smoke per `TESTING_GUIDE.md` is the verification mechanism.
|
||||||
|
- [ ] No `--webpack` flag added to `npm run dev` or `npm run build`. Turbopack-by-default is accepted per gate-1 decision; fallback procedure is documented in Risk R1 (in the convoy file) and in this brief's Rationale.
|
||||||
|
|
||||||
|
## Rationale (≤3 sentences)
|
||||||
|
|
||||||
|
The Next 15 → 16 jump in tcg-vault is unusually narrow at the framework layer (no App Router, no `middleware.js`, no `next/cache`, no `next/image`, no `getServerSideProps`/`getStaticProps`, no `unstable_*`), but the lint toolchain has to move in lockstep: `next lint` was removed, `eslint-config-next@16` requires `eslint >= 9.0.0` (flat config) AND a present `typescript` install (despite its `peerDependenciesMeta.typescript.optional: true` annotation — the bundled `typescript-eslint` chain hard-`require`s `typescript` at module load), and the existing `.eslintrc.json` legacy stub can't extend it — so this single PR bumps `next`, bumps `eslint` to **v9.39.4** (per gate-1 Decision D, after Decision B's earlier v10 pivot was empirically reversed by Risk R15 firing on the implementer's pass-2 run with `TypeError: scopeManager.addGlobals is not a function`; v10 will be picked up under the queued upstream-blocked `bump-eslint-10` follow-up), bumps `eslint-config-next` to `^16` matching `next`, **adds `typescript@^5.9.3` as a devDep** (per gate-1 Decision C), replaces `.eslintrc.json` with `eslint.config.mjs` (same shape works on both v9 and v10, so no further edit needed when `bump-eslint-10` lands), and changes the `package.json` lint script. Both the Next bump and the ESLint migration touch `package.json`, so they cannot run in parallel anyway — keeping them in one brief gives reviewers one PR, one Vercel preview, and one revert boundary if anything regresses. React stays at 18.3.1 (16's peer-deps accept it; React 19 is `bump-react`), Turbopack-by-default is accepted as-is (no `webpack:` config exists; fallback per Risk R1), no `tsconfig.json` is created (tcg-vault remains a JS-only project), and the ~100-error lint baseline stays untouched per `fix-lint-baseline`'s charter. Decision B's pivot to v10 was the right call given Boot-the-brief evidence at the time; Decision D rolls it back specifically because empirical lint runs surfaced the R15 incompatibility with `eslint-config-next@16.2.6`'s pre-v10-GA bundled plugins.
|
||||||
|
|
||||||
|
## Boot-the-brief findings (Architect verified 2026-05-22; re-verified 2026-05-23 after gate-1 scope expansion to ESLint v9; re-verified again 2026-05-23 after gate-1 Decision B pivoted to ESLint v10; re-verified narrowly 2026-05-23 after gate-1 Decision C added `typescript` devDep in response to implementer escalation; re-verified narrowly again 2026-05-23 after gate-1 Decision D reverted the v10 pivot back to v9.39.4 in response to pass-2 implementer escalation showing R15 fired empirically with `TypeError: scopeManager.addGlobals is not a function`)
|
||||||
|
|
||||||
|
**Note on findings #5–#10:** These document the v10-pivot Boot-the-brief from Decision B. They are kept as historical record (the conclusions about v10's engines, peer deps, and `eslint/config` exports are still factually correct) but are **superseded for the active pin** by Decision D. The active `eslint` pin is `^9.39.4` per Decision D's recheck below; v10 is queued under the upstream-blocked `bump-eslint-10` follow-up convoy.
|
||||||
|
|
||||||
|
These were verified before publishing the brief:
|
||||||
|
|
||||||
|
1. **`eslint-config-next@16.2.6` ships native flat-config exports — `FlatCompat` is NOT needed.** Verified two ways: (a) `npm view eslint-config-next@16.2.6 exports` returned `"./core-web-vitals": { "default": "./dist/core-web-vitals.js" }`; (b) extracted the published tarball (`npm pack eslint-config-next@16.2.6`, then `tar -xzf`), opened `package/dist/core-web-vitals.js`, and confirmed it ends with `module.exports = config` where `config` is a flat-config array (line 37: `var config = _to_consumable_array(_index.default).concat([...])`, then `module.exports = config`). Original user instruction at gate 1: "Use `FlatCompat` from `@eslint/eslintrc` if `eslint-config-next@16` doesn't ship a native flat-config export." Result: native is shipped, **FlatCompat dropped**, no `@eslint/eslintrc` dep added. (And ESLint v10 dropped `@eslint/eslintrc` from its own dependency tree entirely, so this is doubly the right call.)
|
||||||
|
2. **Verbatim shape comes directly from the [official Next.js docs](https://nextjs.org/docs/app/api-reference/config/eslint).** That page's "Setup ESLint" section uses exactly the `defineConfig([...nextVitals, globalIgnores([...])])` pattern this brief replicates. The only deviation: this brief adds `'node_modules/**'` and `'scripts/migrations/**'` to the ignores per gate-1 instruction.
|
||||||
|
3. **`next/core-web-vitals` is still a valid extends in `eslint-config-next@16` — but only via the full subpath `eslint-config-next/core-web-vitals` in flat config.** The legacy `extends: 'next/core-web-vitals'` shorthand was an `.eslintrc.json` (legacy-config) sugar; flat config requires the explicit subpath import. Confirmed both via the Next.js docs and the package's `exports` field (`"./core-web-vitals": ...`).
|
||||||
|
4. **`defineConfig` + `globalIgnores` are ESLint built-ins from `eslint/config`.** Introduced in ESLint 9.21.0 (Feb 2025); retained in v10.0.0 (Feb 2026). Confirmed by extracting `eslint@10.4.0`'s tarball: `package/lib/config-api.js` re-exports `{ defineConfig, globalIgnores, includeIgnoreFile }` from `@eslint/config-helpers`. Same shape as v9 — no signature change. v10 also adds `includeIgnoreFile` to that module (not used here).
|
||||||
|
5. **ESLint v10.4.0 is the current `latest` on npm.** `npm view eslint dist-tags` returns `{"latest": "10.4.0", "maintenance": "9.39.4", "next": "10.0.0-rc.2", ...}`. v10.0.0 was released 2026-02-06 per the [release blog post](https://eslint.org/blog/2026/02/eslint-v10.0.0-released/). v9.39.4 is on the `maintenance` tag. Per gate-1 Decision B, this brief pins `^10.4.0`.
|
||||||
|
6. **`eslint@10.4.0` peer deps:** `jiti: *` with `peerDependenciesMeta.jiti.optional: true`. Optional peer; only required if you author your config in TypeScript (`eslint.config.ts`). This brief uses `eslint.config.mjs` (plain JavaScript ESM), so `jiti` is **not** installed. Note: v10 explicitly requires `jiti >= 2.2.0` if used (per migration guide § "Jiti < v2.2.0 are no longer supported"); not a concern for us.
|
||||||
|
7. **`eslint@10.4.0` engines: `node ^20.19.0 || ^22.13.0 || >=24`.** This is a tighter floor than v9's `^18.18.0 || ^20.9.0 || >=21.1.0` (Node 18, 21, and 23 are all dropped; Node 20.x floor raised from 20.9.0 to 20.19.0). **CI satisfies:** `setup-node@v4` with `node-version: '20'` resolves to the latest 20.x at install time; latest 20.x as of 2026-05 is well above 20.19.0 (Node 20.19.0 was released 2025-03; many patches since). **Local satisfies:** `node@22.14.0` is in the `^22.13.0` range. **Vercel satisfies:** default Node 22 runtime (22.x ≥ 22.13). All three environments ✓. See Risk R9 for the residual concern (CI's `node-version: '20'` is a moving target — if it ever resolves to a stale < 20.19.0 patch, ESLint v10 will refuse to start; that's a CI-pin question, out of scope here).
|
||||||
|
8. **`eslint-config-next@16.2.6` peer deps:** `eslint >= 9.0.0` (required), `typescript >= 3.3.1` (declared optional via `peerDependenciesMeta.typescript.optional: true`). **No `<10` upper bound** — re-verified via `npm view eslint-config-next@16.2.6 peerDependencies`. v10 is accepted. **🔴 SUPERSEDED by Decision C (2026-05-23):** the original claim "tcg-vault is JS-only, no `typescript` install needed" was **wrong**. `peerDependenciesMeta.typescript.optional: true` only suppresses npm's install-time peer-dep warning; it does NOT make `typescript` runtime-optional. `eslint-config-next` bundles `typescript-eslint@^8.46.0` as a regular `dependency` (not as a peer), and `@typescript-eslint/typescript-estree@8.59.4` does an unconditional `require('typescript')` at module load (verified via tarball extraction — see finding #17 below). The implementer's first lint run crashed with `Cannot find module 'typescript'` before any rule executed. **Corrected:** `typescript@^5.9.3` is now installed as a devDep. See findings #16 and #17 for the v6-vs-v5 pin choice and the verified runtime-require evidence.
|
||||||
|
9. **`eslint-config-next@16.2.6` was published before ESLint v10 (Oct 2025 vs Feb 2026), so its bundled plugins were not tested against v10.** Bundled plugin set: `@next/eslint-plugin-next@16.2.6`, `eslint-plugin-react@^7.37.0` (latest published `7.37.5`), `eslint-plugin-react-hooks@^7.0.0` (latest `7.1.1`), `eslint-plugin-import@^2.32.0` (latest `2.32.0`, released 2025-06), `eslint-plugin-jsx-a11y@^6.10.0` (latest `6.10.2`), `typescript-eslint@^8.46.0` (latest `8.59.4`). All published before Feb 2026. **The peer-dep range allows v10, but runtime compatibility is not statically provable.** Captured in Risk R15. Mitigation: the "Local verification" section above classifies failure modes — `Cannot find module 'typescript'` was **not** R15 (it was the Decision C `typescript`-missing failure); a `TypeError: context.getCwd is not a function` (or similar v9-deprecated-API error) **would** be R15 and would trigger a v9 fallback.
|
||||||
|
10. **v10 user-impacting breaking changes audited against tcg-vault** ([migration guide](https://eslint.org/docs/latest/use/migrate-to-10.0.0)):
|
||||||
|
- **Node.js floor raised** — covered above (#7).
|
||||||
|
- **`eslint:recommended` updated (3 new rules enabled).** Will shift baseline. Goes to `fix-lint-baseline`.
|
||||||
|
- **Old config format removed.** We're already on flat config in this brief — no impact.
|
||||||
|
- **JSX references now tracked.** Will shift `no-unused-vars` / `no-undef` baseline (likely fewer false positives). Goes to `fix-lint-baseline`.
|
||||||
|
- **`eslint-env` comments are errors.** `rg "eslint-env"` returned zero matches in tcg-vault source. ✓
|
||||||
|
- **`stylish` formatter uses native `styleText` instead of `chalk`.** Cosmetic only. Honors `NO_COLOR` / `NODE_DISABLE_COLORS`. No action.
|
||||||
|
- **`no-shadow-restricted-names` reports `globalThis` by default.** Will potentially add baseline entries. Goes to `fix-lint-baseline`.
|
||||||
|
- **Plugin-developer changes** (deprecated `context` members, deprecated `SourceCode` methods, `Program` AST range, `RuleTester` strictness, `nodeType` on `LintMessage`). Not applicable to tcg-vault — we don't author plugins. **But these are exactly the APIs `eslint-config-next`'s bundled plugins might have used before v10**; that risk is captured in #9 / R15.
|
||||||
|
- **POSIX character classes in glob patterns / `radix` rule deprecated options / `func-names` schema / `no-invalid-regexp.allowConstructorFlags` uniqueness.** None apply (we don't override any of these rules; we don't use POSIX glob syntax).
|
||||||
|
11. **`next@16.2.6` peer deps and engines re-verified.** `react ^18.2.0 || ^19.0.0` ✓ (current `18.3.1`); engines `node >=20.9.0` ✓ (lower than ESLint v10's `^20.19.0` floor — ESLint v10 is now the binding constraint).
|
||||||
|
12. **No `next/image` usage in tcg-vault.** Re-verified via `rg "from ['\"]next/image['\"]"` — zero hits in `pages/`, `components/`, `lib/`. Convoy file's audit list (line 45) was incorrect.
|
||||||
|
13. **No `webpack:` config in `next.config.js`.** Turbopack-by-default in `next dev`/`next build` is safe per gate-1 acceptance. Fallback procedure documented in Risk R1 (convoy file).
|
||||||
|
14. **`.gitignore` already covers `.next/dev/`.** Next 16 splits dev and build outputs; existing `/.next/` rule (line 28) is a directory glob covering both.
|
||||||
|
15. **`scripts/migrations/` doesn't exist yet.** Per `.cursor/rules/no-go-zones.mdc`, "folder TBD." Adding to `globalIgnores` preemptively is harmless.
|
||||||
|
|
||||||
|
### Decision C narrow recheck (added 2026-05-23)
|
||||||
|
|
||||||
|
16. **TypeScript pin: `^5.9.3` (not `^6.0.3`).** `npm view typescript dist-tags` returned `{"latest": "6.0.3", "next": "6.0.0-dev.20260416", "rc": "6.0.1-rc", "beta": "6.0.0-beta", "maintenance": "5.9.3", ...}` — TypeScript 6 is the current `latest`, contrary to the gate-1 instruction's parenthetical claim that "5 is the latest TypeScript major." Latest 5.x is `5.9.3`. Two reasons to pin `^5.9.3` and defer v6:
|
||||||
|
- **Honor the literal gate-1 instruction.** Decision C says "Pin range: `^5`." The parenthetical was a documentation error, not the binding instruction.
|
||||||
|
- **`typescript-eslint@8.59.4`'s peer range is `>=4.8.4 <6.1.0`.** Strictly, `typescript@6.0.3` IS in range (`<6.1.0` ⊃ `6.0.3`), so `^6.0.3` would satisfy it. **But:** typescript-eslint historically pins TS minor versions tightly and ships compatibility releases out-of-band; v8.59.4 was published before TS 6 GA and has not advertised explicit v6 support. Pinning `^5.9.3` keeps us inside the well-trodden range until a future convoy bumps `typescript-eslint` to a v6-tested release. `^5.9.3` resolves to the latest 5.x patch (currently `5.9.3` itself) and is well within the peer range.
|
||||||
|
- **No peer deps on typescript itself.** `npm view typescript@latest peerDependencies` returns empty. `typescript@^5.9.3` adds zero transitive packages — only `typescript`'s own bundle (compiler, language service, declaration files). The lockfile diff is small.
|
||||||
|
- **Engines.** `typescript@5.9.3` and `typescript@6.0.3` both list `engines.node >= 14.17`, well below ESLint v10's `^20.19.0` floor. No new Node constraint introduced.
|
||||||
|
17. **Verified the unconditional `require('typescript')` site.** Extracted `@typescript-eslint/typescript-estree@8.59.4`'s published tarball (`npm pack` then `tar -xzf` in `/tmp/ts-estree-pkg`) and grepped `dist/` for `require('typescript')`:
|
||||||
|
```
|
||||||
|
dist/convert.js:40: const ts = __importStar(require("typescript"));
|
||||||
|
dist/useProgramFromProjectService.js:44:const ts = __importStar(require("typescript"));
|
||||||
|
dist/convert-comments.js:38: const ts = __importStar(require("typescript"));
|
||||||
|
dist/semantic-or-syntactic-errors.js:4: const typescript_1 = require("typescript");
|
||||||
|
dist/getModifiers.js:38: const ts = __importStar(require("typescript"));
|
||||||
|
dist/check-syntax-errors.js:37: const ts = __importStar(require("typescript"));
|
||||||
|
dist/check-modifiers.js:37: const ts = __importStar(require("typescript"));
|
||||||
|
dist/version-check.js:38: const ts = __importStar(require("typescript"));
|
||||||
|
dist/source-files.js:38: const ts = __importStar(require("typescript"));
|
||||||
|
```
|
||||||
|
All 9 sites are top-level `require('typescript')` calls — **no `try { require('typescript') } catch {}` gating, no dynamic-import lazy-loader, no `typeof require !== 'undefined' && require.resolve('typescript')` guard.** The package will throw `MODULE_NOT_FOUND` at import time if `typescript` isn't installed. The package's own `peerDependencies.typescript: ">=4.8.4 <6.1.0"` (in `package.json` at the typescript-estree level — **not flagged optional**) is the accurate signal; `eslint-config-next`'s `peerDependenciesMeta.typescript.optional: true` is a **misleading transitive override** at the wrapper level. Conclusion: any consumer of `eslint-config-next@16` MUST install `typescript` to lint. This is true under both ESLint v9 and v10 (same `typescript-eslint` chain), so reverting to v9 would not have fixed the crash.
|
||||||
|
18. **No `tsconfig.json` in `tcg-vault`.** Verified via `Glob tsconfig*.json` — zero hits. The repo is JS-only (per AGENTS.md §1: "Next.js 15 (Pages router) + React 18, JavaScript (not TypeScript)"). The `typescript` install enables `eslint-config-next`'s lint chain; it does NOT introduce TypeScript as a project language. The "no `tsconfig.json` created" guardrail is enforced explicitly under "No-scope-expansion guardrails."
|
||||||
|
|
||||||
|
### Decision D narrow recheck (added 2026-05-23, after pass-2 implementer escalation reversed Decision B's v10 pivot)
|
||||||
|
|
||||||
|
19. **`eslint@9.39.4` is still on the `maintenance` dist-tag — no superseding 9.x patch since Decision A.** `npm view eslint dist-tags --json` returned `{"latest": "10.4.0", "maintenance": "9.39.4", "next": "10.0.0-rc.2", "es6jsx": "0.11.0-alpha.0"}`. v9.39.4 was the v9 line's last release before v10 GA on 2026-02-06; the v9 line is in maintenance mode but still receives security backports if needed.
|
||||||
|
20. **`eslint@9.39.4` peer deps:** `jiti: *` only, with the same `peerDependenciesMeta.jiti.optional: true` semantics as v10 (only required for `.ts` configs; we use `.mjs`). No surprising new peer added since Decision A. **Engines:** `^18.18.0 || ^20.9.0 || >=21.1.0` — looser than v10's `^20.19.0 || ^22.13.0 || >=24` floor. CI's `setup-node@v4` `node-version: '20'` (latest 20.x), local `node@22.14.0`, and Vercel's default Node 22 runtime all satisfy. The R9 residual concern (CI moving target on `node-version: '20'`) **becomes inert under Decision D** because v9's floor is 20.9.0 instead of 20.19.0; any reasonable 20.x patch will satisfy.
|
||||||
|
21. **`eslint-config-next@16.2.6`'s peer-dep range on `eslint` is unchanged** since Decision B's verification: `>=9.0.0` (no upper bound). v9.39.4 satisfies trivially.
|
||||||
|
22. **`eslint.config.mjs` shape works on v9.39.4 with zero edits.** `defineConfig` and `globalIgnores` from `eslint/config` were introduced in 9.21.0 (per Boot-the-brief #4) and are present in 9.39.4. The same import line — `import { defineConfig, globalIgnores } from 'eslint/config';` — resolves correctly on both v9.39.4 and v10.4.0. **This is the load-bearing reason Decision D is a one-line `package.json` re-pin and not a multi-file rollback.**
|
||||||
|
23. **R15 fired empirically on the pass-2 implementer run with the following diagnostic:**
|
||||||
|
- **Crash signature:** `TypeError: scopeManager.addGlobals is not a function`
|
||||||
|
- **Call site:** ESLint v10's `lib/source-code/source-code.js:221` calls `scopeManager.addGlobals(...)`.
|
||||||
|
- **Missing-method site:** `@typescript-eslint/scope-manager@8.59.4` (a transitive dep of `typescript-eslint@8.59.4`, which `eslint-config-next@16.2.6` bundles as a regular `dependency`) does not implement `addGlobals` on its `ScopeManager` class.
|
||||||
|
- **Why:** `@typescript-eslint/scope-manager@8.x` was published Oct/Nov 2025, before ESLint v10 GA on 2026-02-06. The `addGlobals` method is a v10-introduced extension of the `ScopeManager` interface; v9 used a different ingestion path. `typescript-eslint` has not yet shipped a v10-tested release that adds the v10-required method.
|
||||||
|
- **Resolution path:** revert `eslint` to v9.39.4 (Decision D). The same `typescript-eslint@8.59.4` works correctly on v9 because v9 doesn't call `addGlobals`.
|
||||||
|
- **Pre-emptive note for the queued `bump-eslint-10` convoy:** when `typescript-eslint` ships a v10-tested release (likely `8.6.x`+ or `9.x`) AND `eslint-config-next` bundles it (likely `16.3+`), this incompatibility goes away and `bump-eslint-10` becomes a single-brief mechanical bump matching the shape of this convoy.
|
||||||
|
|
@ -1,3 +0,0 @@
|
||||||
{
|
|
||||||
"extends": "next/core-web-vitals"
|
|
||||||
}
|
|
||||||
16
eslint.config.mjs
Normal file
16
eslint.config.mjs
Normal file
|
|
@ -0,0 +1,16 @@
|
||||||
|
import { defineConfig, globalIgnores } from 'eslint/config';
|
||||||
|
import nextVitals from 'eslint-config-next/core-web-vitals';
|
||||||
|
|
||||||
|
const eslintConfig = defineConfig([
|
||||||
|
...nextVitals,
|
||||||
|
globalIgnores([
|
||||||
|
'.next/**',
|
||||||
|
'node_modules/**',
|
||||||
|
'out/**',
|
||||||
|
'build/**',
|
||||||
|
'next-env.d.ts',
|
||||||
|
'scripts/migrations/**',
|
||||||
|
]),
|
||||||
|
]);
|
||||||
|
|
||||||
|
export default eslintConfig;
|
||||||
|
|
@ -1,8 +1,12 @@
|
||||||
/** @type {import('next').NextConfig} */
|
/** @type {import('next').NextConfig} */
|
||||||
const nextConfig = {
|
const nextConfig = {
|
||||||
images: {
|
images: {
|
||||||
domains: ['api.scryfall.com', 'images.pokemontcg.io', 'lorcana-api.com'],
|
remotePatterns: [
|
||||||
|
{ protocol: 'https', hostname: 'api.scryfall.com' },
|
||||||
|
{ protocol: 'https', hostname: 'images.pokemontcg.io' },
|
||||||
|
{ protocol: 'https', hostname: 'lorcana-api.com' },
|
||||||
|
],
|
||||||
},
|
},
|
||||||
};
|
};
|
||||||
|
|
||||||
export default nextConfig;
|
export default nextConfig;
|
||||||
|
|
|
||||||
1721
package-lock.json
generated
1721
package-lock.json
generated
File diff suppressed because it is too large
Load diff
11
package.json
11
package.json
|
|
@ -7,7 +7,7 @@
|
||||||
"dev": "next dev",
|
"dev": "next dev",
|
||||||
"build": "next build",
|
"build": "next build",
|
||||||
"start": "next start",
|
"start": "next start",
|
||||||
"lint": "next lint",
|
"lint": "eslint .",
|
||||||
"setup-db": "node scripts/setup-neon-db.js",
|
"setup-db": "node scripts/setup-neon-db.js",
|
||||||
"import-popular": "node scripts/import-popular-sets.js",
|
"import-popular": "node scripts/import-popular-sets.js",
|
||||||
"import-all": "node scripts/bulk-import-all.js"
|
"import-all": "node scripts/bulk-import-all.js"
|
||||||
|
|
@ -19,7 +19,7 @@
|
||||||
"bcryptjs": "^3.0.2",
|
"bcryptjs": "^3.0.2",
|
||||||
"dotenv": "^17.2.1",
|
"dotenv": "^17.2.1",
|
||||||
"jsonwebtoken": "^9.0.2",
|
"jsonwebtoken": "^9.0.2",
|
||||||
"next": "^15.4.2",
|
"next": "^16.2.6",
|
||||||
"node-fetch": "^3.3.2",
|
"node-fetch": "^3.3.2",
|
||||||
"react": "^18.3.1",
|
"react": "^18.3.1",
|
||||||
"react-dom": "^18.3.1",
|
"react-dom": "^18.3.1",
|
||||||
|
|
@ -27,9 +27,10 @@
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"autoprefixer": "^10.4.21",
|
"autoprefixer": "^10.4.21",
|
||||||
"eslint": "^8",
|
"eslint": "^9.39.4",
|
||||||
"eslint-config-next": "15.4.2",
|
"eslint-config-next": "^16.2.6",
|
||||||
"postcss": "^8.5.6",
|
"postcss": "^8.5.6",
|
||||||
"tailwindcss": "^3.4.17"
|
"tailwindcss": "^3.4.17",
|
||||||
|
"typescript": "^5.9.3"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue