From bc0d1687d0e7b7e6c8e64b88a6b9bfcf44430fbd Mon Sep 17 00:00:00 2001 From: Randall Stillwell Date: Sat, 23 May 2026 02:36:08 -0500 Subject: [PATCH] docs(AGENTS): reflect bump-next-js outcome (Next 16, ESLint v9, typescript devDep) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Doc-writer pass for convoy bump-next-js (PR #4 / commit e57ea17). Single file touched: AGENTS.md (+5 / -1). - § 1 Project overview: Framework line bumped Next.js 15 -> 16, with a cross-reference to new Gotcha #9 for the typescript-is-just-for-lint context. - § 4 Common gotchas: three new entries that future agents need to know about but wouldn't infer from the code: - #9: typescript@^5.9.3 is installed purely so eslint-config-next@16's bundled typescript-eslint chain can satisfy its hard require('typescript') at module load. No tsconfig.json, no .ts files, no @ts-check. Decision C. - #10: ESLint pinned to ^9.39.4 (maintenance), not v10 (latest). v10 surfaced Risk R15 empirically (TypeError: scopeManager.addGlobals) via @typescript-eslint/scope-manager@8.59.4 predating v10 GA. Do not bump independently — wait for queued bump-eslint-10 follow-up convoy. Decision D. - #11: Turbopack is now the default bundler in next dev/build. Fallback per-command is --webpack. Do not pre-emptively switch. - § 7 Deployment: reference VERCEL_AUTOMATION_BYPASS_SECRET (env var name only, no value) for the queued adopt-playwright-smoke convoy to use against protected preview deploys. CHANGELOG.md / DEVELOPER_CHANGELOG.md not created — those are deferred to launch-polish per the convoy's roles section. README.md staleness (line 16 still says "Next.js 15, React 18, TypeScript") flagged in the PR description but NOT fixed here per the docs-pass scope. Pickup: launch-polish. Co-authored-by: Cursor --- AGENTS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7921a92..4d4d13e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ Guidance for agents and humans working in this repo. Prefer existing patterns ov A web app for managing trading-card-game collections (Magic, Pokémon, Lorcana). Users authenticate, build collections + decks, scan physical cards via a camera+AI-OCR flow, and share publicly. Admin users curate the card database. -- **Framework:** Next.js 15 (Pages router) + React 18, JavaScript (not TypeScript) +- **Framework:** Next.js 16 (Pages router) + React 18, JavaScript (not TypeScript — see Gotcha #9) - **Data:** Neon Postgres, accessed two different ways — `@neondatabase/serverless` (`lib/database.js`) AND raw `@vercel/postgres` (`pages/api/**`). Pick ONE; see Gotcha #1. - **Auth:** Custom JWT (jsonwebtoken + bcryptjs), token stored in `localStorage`, sent as `Authorization: Bearer …`. No NextAuth. - **UI:** Tailwind CSS + custom CSS variables for theming (light/dark via `lib/theme-context.js`) @@ -52,6 +52,9 @@ Code graph is indexed by `user-code-review-graph` MCP (122 files, 628 nodes, 560 - **#6 — Migrations are bare scripts.** `scripts/add-*.js` and `scripts/fix-*.js` are run-once jobs with no idempotency tracking. Adopt `node-pg-migrate`, `kysely`, or `drizzle-kit` before more schema changes. - **#7 — Dual `is_public` semantics.** Collections and decks both have `is_public` columns; check which controls discovery vs. anonymous read in the relevant route. - **#8 — Layout has hardcoded default user.** `Layout({ user = { email: 'me@randallstillwell.com', role: 'user' } })`. Anything rendering Layout without passing `user` will impersonate the maintainer. Pass `user` explicitly from every page. +- **#9 — `typescript` is a devDep, but the source is still JavaScript-only.** `package.json` lists `typescript@^5.9.3` purely so `eslint-config-next@16`'s bundled `typescript-eslint` chain can satisfy its hard `require('typescript')` at module load (the `peerDependenciesMeta.typescript.optional: true` flag in `eslint-config-next` only suppresses npm's install-time warning, not the runtime require). There is no `tsconfig.json`, no `.ts`/`.tsx` files, and no `// @ts-check` directives. Do not rename `.js` files to `.ts` or add a `tsconfig.json` without an explicit convoy decision — TypeScript adoption is its own scope. See `.convoys/bump-next-js.md` § Decisions C. +- **#10 — ESLint pinned to v9 (maintenance), not v10 (latest).** `devDependencies.eslint` is `^9.39.4` even though `latest` is `10.4.0`. We tried v10 and `npm run lint` crashed with `TypeError: scopeManager.addGlobals is not a function` because `eslint-config-next@16`'s bundled `typescript-eslint@8.x` predates ESLint v10's redesigned global-ingestion path. Reverted to v9 under Decision D. **Do NOT bump ESLint independently** — wait for the queued `bump-eslint-10` follow-up convoy, which is upstream-blocked until `typescript-eslint` ships a v10-tested release that `eslint-config-next` bundles. See `.convoys/bump-next-js.md` § Decisions D + "Follow-up convoys queued". +- **#11 — Turbopack is now the default bundler.** `next dev` and `next build` use Turbopack by default in Next.js 16. The fallback per command is `--webpack` (e.g. `next build --webpack`). We have no custom `webpack:` block in `next.config.js`, no custom loaders/aliases, and no Sass tilde imports, so Turbopack should "just work" — but if a build/runtime regression appears, reproduce on both bundlers before deciding whether to revert or pin a script to webpack. Do not pre-emptively switch to `--webpack`. ## 5. Running locally @@ -66,6 +69,7 @@ Code graph is indexed by `user-code-review-graph` MCP (122 files, 628 nodes, 560 ## 7. Deployment - **Vercel** auto-deploys `main` and creates Preview deployments for every PR. `vercel.json` and `.vercel/` are committed. CI in `.github/workflows/` runs lint + types (no duplicate build — Vercel handles it). +- **Preview protection bypass for automation.** The project has a Protection Bypass for Automation token exposed locally as `VERCEL_AUTOMATION_BYPASS_SECRET` in `.env.local` (not committed). Smoke/visual-diff workflows pass this header (`x-vercel-protection-bypass`) when hitting password-protected preview URLs. Needed for the queued `adopt-playwright-smoke` convoy; do not log or echo the value. ## 8. Code graph