Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (77 loc) · 3.56 KB

AGENTS.md

File metadata and controls

100 lines (77 loc) · 3.56 KB
Raw

AGENTS.md

Repository guide for AI coding agents. This file is tool-neutral and contains no references to specific AI tools. Point your agent here to get productive quickly.

Project Overview

This is the website for the OCPP DebugKit ecosystem — the marketing pages, documentation, and an in-browser trace inspector. It is a Next.js app.

License: Apache 2.0 Framework: Next.js 16 (App Router) Language: TypeScript (strict mode) Styling: Tailwind CSS v4 Package Manager: pnpm 10.x Node: >= 20.0.0

Key architectural fact

The inspector is powered by the published @ocpp-debugkit/toolkit npm package (a normal dependency in package.json), not a workspace build. This site is decoupled from the toolkit's source tree: it tracks released versions of the library. To pick up new toolkit capabilities, bump the dependency.

src/app/inspector/page.tsx
  imports: @ocpp-debugkit/toolkit/core, /reporter, /scenarios, /replay

The inspector is a client component ('use client') and runs entirely in the browser — no server round-trips for trace processing.

Structure

src/app/
├── page.tsx            # Landing page
├── layout.tsx          # Root layout + metadata
├── globals.css         # Tailwind entry + theme tokens
├── inspector/
│   └── page.tsx        # In-browser trace inspector (client-side)
└── docs/
    ├── layout.tsx      # Docs shell + nav
    ├── page.tsx        # Docs index
    └── <topic>/page.tsx
tests/                  # Playwright end-to-end specs

Build Commands

pnpm install          # Install dependencies
pnpm dev              # Dev server at http://localhost:3000
pnpm build            # Production build
pnpm typecheck        # tsc --noEmit
pnpm lint             # ESLint (eslint-config-next)
pnpm test:e2e         # Playwright end-to-end tests

pnpm build generates next-env.d.ts and .next/types, so run it before typecheck/lint on a clean checkout (this is the order CI uses).

Testing Conventions

  • End-to-end tests use Playwright (tests/*.spec.ts).
  • The inspector and replay specs double as a smoke test of the npm-backed toolkit: they load a sample scenario and assert the timeline, failures, and replay controls render.
  • Add or update a spec whenever you change what a page does.

Commit & PR Conventions

Uses Conventional Commits (feat: / fix: / docs: / chore:). One concern per PR; tests and living-doc updates ship in the same PR; CI (typecheck, lint, build, e2e) must be green before merge. See CONTRIBUTING.md.

Code Style

  • TypeScript strict mode — no any without justification.
  • Tailwind v4 utility classes; theme tokens in globals.css.
  • Use import type for type-only imports.

Security Constraints

  • The inspector processes untrusted input (trace files, pasted content). Validate and bound it — the limits live in @ocpp-debugkit/toolkit (MAX_INPUT_SIZE_BYTES, ParseError); do not bypass them.
  • Browser-local processing — never add automatic upload of user trace data.
  • No eval(), Function(), or dynamic code execution on untrusted input.
  • No dangerouslySetInnerHTML or unsafe HTML injection of user content.
  • No secrets, tokens, or credentials in committed files.
  • No personal or sensitive data in committed artifacts. User-loaded traces and runtime-generated reports are not subject to this rule — they are the user's own data, processed locally.

Current Status

See CURRENT_STATE.md.