coding agent adjustments
This commit is contained in:
parent
a06b2607c7
commit
90e730c2fe
227
AGENTS.md
227
AGENTS.md
@ -1,55 +1,206 @@
|
||||
# AGENTS.md
|
||||
# Agents Guide (Single Source of Truth)
|
||||
|
||||
This file provides guidance to Opencode when working with code in this repository.
|
||||
This document is the canonical reference for humans and `Agents` working in this repository. It standardizes stack, structure, workflows, and guardrails so contributions stay consistent and safe.
|
||||
|
||||
## Repository Snapshot
|
||||
## 1) Scope and goals
|
||||
|
||||
TypeScript + React 19 (Next.js 15.5.4) site builder for Biohazard VFX studio. Single npm workspace. Deployed to Cloudflare Workers via OpenNext. ESLint + TypeScript strict mode enforced pre-commit. No automated tests; manual QA in Chromium/Safari only. (Sources: package.json, tsconfig.json, README.md)
|
||||
* Make onboarding fast with a single place to look
|
||||
* Define conventions so changes are predictable
|
||||
* Provide exact commands that `Agents` can run without guesswork
|
||||
* Prevent accidental regressions in routing, theming, SEO, and deployment
|
||||
|
||||
## Commands
|
||||
## 2) Tech stack
|
||||
|
||||
| Task | Command | Scope | Source |
|
||||
|------|---------|-------|--------|
|
||||
| Dev server | `npm run dev` | Root | package.json:6 |
|
||||
| Build (Next.js) | `npm run build` | Root | package.json:7 |
|
||||
| Build (Cloudflare Workers) | `npm run build:open-next` | Root | package.json:8 |
|
||||
| Lint (ESLint) | `npm run lint` | Root | package.json:10 |
|
||||
| Type check (TypeScript) | `npm run type-check` | Root | package.json:11 |
|
||||
| Start production server | `npm run start` | Root | package.json:9 |
|
||||
* **Framework**: Next.js 15.5.4, React 19, TypeScript
|
||||
* **Styling**: Tailwind CSS 4, shadcn/ui
|
||||
* **Animation**: Framer Motion
|
||||
* **Forms**: react-hook-form + Zod
|
||||
* **Platform**: Cloudflare Workers via OpenNext
|
||||
* **Package manager**: npm
|
||||
* **Node**: LTS 20 or 22
|
||||
|
||||
**Run a single test:** Not applicable; no automated test runner configured.
|
||||
## 3) Project layout
|
||||
|
||||
## Architecture Overview
|
||||
```
|
||||
root
|
||||
├─ src/
|
||||
│ ├─ app/ # App Router pages and layouts
|
||||
│ │ ├─ (marketing)/ # Example route groups
|
||||
│ │ ├─ api/ # Route handlers
|
||||
│ │ └─ layout.tsx # Root layout, see rules below
|
||||
│ ├─ components/ # Reusable UI
|
||||
│ ├─ data/ # JSON or TS data objects consumed by pages
|
||||
│ ├─ lib/ # Utilities, hooks, server actions
|
||||
│ ├─ styles/ # globals.css, tailwind utilities if applicable
|
||||
│ └─ types/ # Shared types
|
||||
├─ public/ # Static assets
|
||||
├─ next.config.ts
|
||||
├─ tailwind.config.ts
|
||||
├─ wrangler.toml # Cloudflare deploy config
|
||||
└─ package.json
|
||||
```
|
||||
|
||||
- **Entry point**: `src/app/layout.tsx` (root layout with Navigation & Footer); app routes in `src/app/{route}/page.tsx` (about, contact, portfolio, services). (Source: README.md:61–69, src/app/layout.tsx)
|
||||
- **Components**: Functional React + Radix UI via shadcn/ui. Primitives in `src/components/ui/`; feature components in `src/components/`. (Source: README.md:70–79, package.json:16–24)
|
||||
- **Data & utils**: Project and service metadata in `src/data/projects.ts` and `src/data/services.ts`; shared utilities in `src/lib/utils.ts`. (Source: README.md:80–84)
|
||||
- **Styling**: Tailwind CSS 4 + CSS variables in `src/app/globals.css`; components use `clsx` + `tailwind-merge` for conditional styles. (Source: tsconfig.json, package.json:39)
|
||||
- **Forms**: `react-hook-form` + Zod validation; e.g., MultiStepForm (contact page). (Source: package.json:14–15, 33, 35)
|
||||
- **External services**: Instagram Feed component integrates Instagram API via `src/lib/instagram-api.ts`. Remote images from unsplash.com. (Source: next.config.ts:7–13, src/lib/)
|
||||
- **Deployment**: OpenNext adapter for Cloudflare Workers. Build output in `.open-next/` (worker.js + assets). Domain routes in wrangler.toml. (Source: wrangler.toml, open-next.config.ts, next.config.ts:16–22)
|
||||
### Import aliases
|
||||
|
||||
## Conventions and Rules
|
||||
* Prefer absolute imports using `@` mapped to `src` via `tsconfig.json` paths.
|
||||
|
||||
From CONTRIBUTING.md:
|
||||
## 4) Authoritative UI system
|
||||
|
||||
- **Commit format**: conventional commits (`feat(scope): subject`). Atomic commits. Examples: `feat(portfolio): add project filtering`, `fix(header): resolve mobile menu overflow`. (CONTRIBUTING.md:122–147)
|
||||
- **Branch strategy**: `main` (production), `develop` (integration), `feature/*`, `fix/*`, `hotfix/*`. Always create from `develop`. (CONTRIBUTING.md:49–54, 57–62)
|
||||
- **React/Next.js**: Server components by default; client-only where needed. Single responsibility per component. Keep custom CSS minimal. (CONTRIBUTING.md:80–92)
|
||||
- **TypeScript**: Avoid `any`. Define interfaces for props and API responses. (CONTRIBUTING.md:74–78)
|
||||
* **Theme**: dark mode is the default. Do not introduce light-first designs without approval.
|
||||
* **Typography**: default to Geist and Geist Mono via CSS variables. If adding a new font, add it as a variable and document it here before use.
|
||||
* **Components**: use shadcn/ui primitives. Extend with local wrappers placed in `src/components/ui/`.
|
||||
* **Spacing and rhythm**: follow Tailwind 4 defaults. Prefer utility classes over custom CSS unless componentized.
|
||||
* **Animation**: keep motion subtle. Framer Motion only for meaningful transitions.
|
||||
|
||||
## CI Hooks That Matter Locally
|
||||
## 5) Routing and layout rules
|
||||
|
||||
From `.gitea/workflows/ci.yml`:
|
||||
* The **root layout** owns global providers, theme class, `<Nav />`, and `<Footer />`. Do not duplicate these in child layouts.
|
||||
* Pages live in `src/app`. Keep server components as the default. Promote to client component only when needed.
|
||||
* Metadata must be defined per route with the Next.js Metadata API.
|
||||
|
||||
## 6) SEO and metadata
|
||||
|
||||
* Use the Metadata API for title, description, Open Graph, and Twitter cards.
|
||||
* Add structured data with JSON-LD in the root layout or specific routes when required.
|
||||
* All pages must render a unique `title` and `description` suitable for indexing.
|
||||
|
||||
## 7) Forms and validation
|
||||
|
||||
* Use `react-hook-form` with Zod schemas.
|
||||
* Surface field-level errors and a generic submit error. Never swallow validation errors.
|
||||
|
||||
## 8) Images and assets
|
||||
|
||||
* Use Next Image component for remote images.
|
||||
* If a new external domain is introduced, add it to `next.config.ts` remote patterns and document it here.
|
||||
* Keep `public/` for truly static assets only.
|
||||
|
||||
## 9) Environment variables
|
||||
|
||||
Provide a `.env.sample` and keep it in sync. Typical keys:
|
||||
|
||||
```
|
||||
NEXT_PUBLIC_SITE_URL=
|
||||
RESEND_API_KEY=
|
||||
CF_PAGES_URL=
|
||||
```
|
||||
|
||||
Do not commit real secrets. `Agents` must fail a task rather than hardcode a secret.
|
||||
|
||||
## 10) Local development
|
||||
|
||||
```
|
||||
# install
|
||||
npm ci
|
||||
|
||||
# run dev server
|
||||
npm run dev
|
||||
|
||||
# type checks and linting
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
|
||||
# build and preview
|
||||
npm run build
|
||||
npm run start
|
||||
```
|
||||
|
||||
Notes
|
||||
|
||||
* The Next build may be configured to ignore ESLint and TS errors for production bundling speed. CI still gates on `lint` and `typecheck` before merge.
|
||||
|
||||
## 11) Deployment on Cloudflare Workers with OpenNext
|
||||
|
||||
### Required wrangler.toml settings
|
||||
|
||||
```
|
||||
name = "site-worker"
|
||||
main = ".open-next/worker/index.mjs"
|
||||
compatibility_date = "2024-09-23"
|
||||
compatibility_flags = ["nodejs_compat"]
|
||||
assets = { directory = ".open-next/assets" }
|
||||
```
|
||||
|
||||
### Build and deploy
|
||||
|
||||
```
|
||||
# produce OpenNext build artifacts
|
||||
npx open-next@latest build
|
||||
|
||||
# deploy worker and assets
|
||||
npx wrangler deploy .open-next/worker
|
||||
```
|
||||
|
||||
Guidelines
|
||||
|
||||
* Always run `npm run typecheck` and `npm run lint` before build.
|
||||
* Ensure `assets.directory` matches the OpenNext output.
|
||||
* Keep the compatibility date at or after 2024-09-23.
|
||||
|
||||
## 12) Branching, commits, and CI
|
||||
|
||||
* **Default branch**: `main` is protected.
|
||||
* **Workflow**: feature branches -> PR -> required checks -> squash merge.
|
||||
* **Commit format**: Conventional Commits. Examples
|
||||
|
||||
* `feat: add contact form schema`
|
||||
* `fix: correct Image remote pattern`
|
||||
* `chore: bump dependencies`
|
||||
* **Required checks**
|
||||
|
||||
* `npm run lint`
|
||||
* `npm run typecheck`
|
||||
* `npm run build` can be optional locally if CI runs it, but must succeed before deploy.
|
||||
|
||||
## 13) Testing
|
||||
|
||||
* **Unit**: place tests close to sources, name with `.test.ts` or `.test.tsx`.
|
||||
* **E2E**: optional Playwright. If used, add a `playwright.config.ts` and a `npm run e2e` script.
|
||||
|
||||
## 14) Data and content
|
||||
|
||||
* Non-secret content belongs in `src/data` as TS modules or JSON. Keep it presentation-agnostic.
|
||||
* Do not fetch static project data in client components. Prefer server components or file imports.
|
||||
|
||||
## 15) `Agents` operating rules
|
||||
|
||||
1. Read this guide before making changes.
|
||||
2. Before adding a dependency, justify it in the PR description and update this document if it affects conventions.
|
||||
3. When creating pages, set Metadata and verify unique title and description.
|
||||
4. If a build ignores ESLint or TS errors, CI still blocks merges on `lint` and `typecheck`. Fix the errors instead of bypassing checks.
|
||||
5. Never commit secrets. Use `.env` and keep `.env.sample` current.
|
||||
6. If you change image domains or fonts, document the change here.
|
||||
7. Prefer small, reviewable PRs. Include screenshots for UI changes.
|
||||
|
||||
## 16) Common pitfalls
|
||||
|
||||
* Adding a remote image domain but forgetting to allow it in `next.config.ts`.
|
||||
* Introducing a client component unnecessarily and breaking streaming or SSR.
|
||||
* Duplicating navigation inside nested layouts.
|
||||
* Styling drift by bypassing Tailwind utilities and shadcn primitives.
|
||||
|
||||
## 17) Quick command reference
|
||||
|
||||
```
|
||||
# install deps
|
||||
npm ci
|
||||
|
||||
# develop
|
||||
npm run dev
|
||||
|
||||
# quality gates
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
|
||||
# build and preview
|
||||
npm run build
|
||||
npm run start
|
||||
|
||||
# open-next build and deploy
|
||||
npx open-next@latest build
|
||||
npx wrangler deploy .open-next/worker
|
||||
```
|
||||
|
||||
- **Lint & type-check** (lines 14–35): `npm run lint` and `npm run type-check` run on every PR to main/develop. **Failures block merge.**
|
||||
- **Build** (lines 37–65): `npm run build` with `NODE_ENV=production` required before merge. Artifacts uploaded for 7 days.
|
||||
|
||||
Run both before pushing: `npm run lint && npm run type-check && npm run build`.
|
||||
|
||||
## Known Pitfalls
|
||||
|
||||
- **Build ignores errors**: next.config.ts (lines 17–22) sets `eslint.ignoreDuringBuilds` and `typescript.ignoreBuildErrors` to `true`. Lint and typecheck **must pass locally** before deploy or CI will catch them. (Source: next.config.ts)
|
||||
- **No test suite**: Manual QA only. Verify changes in Chromium and Safari before PR. (Source: README.md:55, AGENTS.md (this file, earlier))
|
||||
- **Secrets in wrangler.toml**: Never commit credentials there. Use Gitea Secrets for env vars. (Source: CONTRIBUTING.md:153, AGENTS.md (this file, earlier))
|
||||
- **Cloudflare compatibility**: Requires `nodejs_compat` flag and compatibility date ≥ 2024-09-23. (Source: wrangler.toml:4)
|
||||
|
||||
205
QWEN.md
Normal file
205
QWEN.md
Normal file
@ -0,0 +1,205 @@
|
||||
# Agents Guide (Single Source of Truth)
|
||||
|
||||
This document is the canonical reference for humans and `Agents` working in this repository. It standardizes stack, structure, workflows, and guardrails so contributions stay consistent and safe.
|
||||
|
||||
## 1) Scope and goals
|
||||
|
||||
* Make onboarding fast with a single place to look
|
||||
* Define conventions so changes are predictable
|
||||
* Provide exact commands that `Agents` can run without guesswork
|
||||
* Prevent accidental regressions in routing, theming, SEO, and deployment
|
||||
|
||||
## 2) Tech stack
|
||||
|
||||
* **Framework**: Next.js 15.5.4, React 19, TypeScript
|
||||
* **Styling**: Tailwind CSS 4, shadcn/ui
|
||||
* **Animation**: Framer Motion
|
||||
* **Forms**: react-hook-form + Zod
|
||||
* **Platform**: Cloudflare Workers via OpenNext
|
||||
* **Package manager**: npm
|
||||
* **Node**: LTS 20 or 22
|
||||
|
||||
## 3) Project layout
|
||||
|
||||
```
|
||||
root
|
||||
├─ src/
|
||||
│ ├─ app/ # App Router pages and layouts
|
||||
│ │ ├─ (marketing)/ # Example route groups
|
||||
│ │ ├─ api/ # Route handlers
|
||||
│ │ └─ layout.tsx # Root layout, see rules below
|
||||
│ ├─ components/ # Reusable UI
|
||||
│ ├─ data/ # JSON or TS data objects consumed by pages
|
||||
│ ├─ lib/ # Utilities, hooks, server actions
|
||||
│ ├─ styles/ # globals.css, tailwind utilities if applicable
|
||||
│ └─ types/ # Shared types
|
||||
├─ public/ # Static assets
|
||||
├─ next.config.ts
|
||||
├─ tailwind.config.ts
|
||||
├─ wrangler.toml # Cloudflare deploy config
|
||||
└─ package.json
|
||||
```
|
||||
|
||||
### Import aliases
|
||||
|
||||
* Prefer absolute imports using `@` mapped to `src` via `tsconfig.json` paths.
|
||||
|
||||
## 4) Authoritative UI system
|
||||
|
||||
* **Theme**: dark mode is the default. Do not introduce light-first designs without approval.
|
||||
* **Typography**: default to Geist and Geist Mono via CSS variables. If adding a new font, add it as a variable and document it here before use.
|
||||
* **Components**: use shadcn/ui primitives. Extend with local wrappers placed in `src/components/ui/`.
|
||||
* **Spacing and rhythm**: follow Tailwind 4 defaults. Prefer utility classes over custom CSS unless componentized.
|
||||
* **Animation**: keep motion subtle. Framer Motion only for meaningful transitions.
|
||||
|
||||
## 5) Routing and layout rules
|
||||
|
||||
* The **root layout** owns global providers, theme class, `<Nav />`, and `<Footer />`. Do not duplicate these in child layouts.
|
||||
* Pages live in `src/app`. Keep server components as the default. Promote to client component only when needed.
|
||||
* Metadata must be defined per route with the Next.js Metadata API.
|
||||
|
||||
## 6) SEO and metadata
|
||||
|
||||
* Use the Metadata API for title, description, Open Graph, and Twitter cards.
|
||||
* Add structured data with JSON-LD in the root layout or specific routes when required.
|
||||
* All pages must render a unique `title` and `description` suitable for indexing.
|
||||
|
||||
## 7) Forms and validation
|
||||
|
||||
* Use `react-hook-form` with Zod schemas.
|
||||
* Surface field-level errors and a generic submit error. Never swallow validation errors.
|
||||
|
||||
## 8) Images and assets
|
||||
|
||||
* Use Next Image component for remote images.
|
||||
* If a new external domain is introduced, add it to `next.config.ts` remote patterns and document it here.
|
||||
* Keep `public/` for truly static assets only.
|
||||
|
||||
## 9) Environment variables
|
||||
|
||||
Provide a `.env.sample` and keep it in sync. Typical keys:
|
||||
|
||||
```
|
||||
NEXT_PUBLIC_SITE_URL=
|
||||
RESEND_API_KEY=
|
||||
CF_PAGES_URL=
|
||||
```
|
||||
|
||||
Do not commit real secrets. `Agents` must fail a task rather than hardcode a secret.
|
||||
|
||||
## 10) Local development
|
||||
|
||||
```
|
||||
# install
|
||||
npm ci
|
||||
|
||||
# run dev server
|
||||
npm run dev
|
||||
|
||||
# type checks and linting
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
|
||||
# build and preview
|
||||
npm run build
|
||||
npm run start
|
||||
```
|
||||
|
||||
Notes
|
||||
|
||||
* The Next build may be configured to ignore ESLint and TS errors for production bundling speed. CI still gates on `lint` and `typecheck` before merge.
|
||||
|
||||
## 11) Deployment on Cloudflare Workers with OpenNext
|
||||
|
||||
### Required wrangler.toml settings
|
||||
|
||||
```
|
||||
name = "site-worker"
|
||||
main = ".open-next/worker/index.mjs"
|
||||
compatibility_date = "2024-09-23"
|
||||
compatibility_flags = ["nodejs_compat"]
|
||||
assets = { directory = ".open-next/assets" }
|
||||
```
|
||||
|
||||
### Build and deploy
|
||||
|
||||
```
|
||||
# produce OpenNext build artifacts
|
||||
npx open-next@latest build
|
||||
|
||||
# deploy worker and assets
|
||||
npx wrangler deploy .open-next/worker
|
||||
```
|
||||
|
||||
Guidelines
|
||||
|
||||
* Always run `npm run typecheck` and `npm run lint` before build.
|
||||
* Ensure `assets.directory` matches the OpenNext output.
|
||||
* Keep the compatibility date at or after 2024-09-23.
|
||||
|
||||
## 12) Branching, commits, and CI
|
||||
|
||||
* **Default branch**: `main` is protected.
|
||||
* **Workflow**: feature branches -> PR -> required checks -> squash merge.
|
||||
* **Commit format**: Conventional Commits. Examples
|
||||
|
||||
* `feat: add contact form schema`
|
||||
* `fix: correct Image remote pattern`
|
||||
* `chore: bump dependencies`
|
||||
* **Required checks**
|
||||
|
||||
* `npm run lint`
|
||||
* `npm run typecheck`
|
||||
* `npm run build` can be optional locally if CI runs it, but must succeed before deploy.
|
||||
|
||||
## 13) Testing
|
||||
|
||||
* **Unit**: place tests close to sources, name with `.test.ts` or `.test.tsx`.
|
||||
* **E2E**: optional Playwright. If used, add a `playwright.config.ts` and a `npm run e2e` script.
|
||||
|
||||
## 14) Data and content
|
||||
|
||||
* Non-secret content belongs in `src/data` as TS modules or JSON. Keep it presentation-agnostic.
|
||||
* Do not fetch static project data in client components. Prefer server components or file imports.
|
||||
|
||||
## 15) `Agents` operating rules
|
||||
|
||||
1. Read this guide before making changes.
|
||||
2. Before adding a dependency, justify it in the PR description and update this document if it affects conventions.
|
||||
3. When creating pages, set Metadata and verify unique title and description.
|
||||
4. If a build ignores ESLint or TS errors, CI still blocks merges on `lint` and `typecheck`. Fix the errors instead of bypassing checks.
|
||||
5. Never commit secrets. Use `.env` and keep `.env.sample` current.
|
||||
6. If you change image domains or fonts, document the change here.
|
||||
7. Prefer small, reviewable PRs. Include screenshots for UI changes.
|
||||
|
||||
## 16) Common pitfalls
|
||||
|
||||
* Adding a remote image domain but forgetting to allow it in `next.config.ts`.
|
||||
* Introducing a client component unnecessarily and breaking streaming or SSR.
|
||||
* Duplicating navigation inside nested layouts.
|
||||
* Styling drift by bypassing Tailwind utilities and shadcn primitives.
|
||||
|
||||
## 17) Quick command reference
|
||||
|
||||
```
|
||||
# install deps
|
||||
npm ci
|
||||
|
||||
# develop
|
||||
npm run dev
|
||||
|
||||
# quality gates
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
|
||||
# build and preview
|
||||
npm run build
|
||||
npm run start
|
||||
|
||||
# open-next build and deploy
|
||||
npx open-next@latest build
|
||||
npx wrangler deploy .open-next/worker
|
||||
```
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user