175 lines
5.7 KiB
Markdown
175 lines
5.7 KiB
Markdown
# AGENTS
|
|
|
|
This file orients coding agents for the test-card repo.
|
|
Stack: SvelteKit + Vite + TypeScript + Vitest + ESLint + Prettier.
|
|
Package scripts are in `package.json` at repo root.
|
|
|
|
## Repository layout
|
|
|
|
- `src/` SvelteKit app source.
|
|
- `src/routes/` route and load files.
|
|
- `src/lib/` shared code exposed via `$lib`.
|
|
- `tests/` Vitest tests and helpers.
|
|
- `av-sync/` small Vite + Svelte app for AV sync tools.
|
|
- `assets/` generated assets (see `npm run generate-assets`).
|
|
- `tests/output/` visual regression artifacts (baseline/current/diff).
|
|
|
|
## Setup
|
|
|
|
- Use the existing package manager for scripts; root scripts assume `npm`.
|
|
- Install deps with `npm install` if needed.
|
|
- Do not add new dependencies without explicit permission.
|
|
|
|
## Common commands
|
|
|
|
- Dev server: `npm run dev`.
|
|
- Build: `npm run build`.
|
|
- Preview build: `npm run preview`.
|
|
- Typecheck: `npm run check`.
|
|
- Typecheck (watch): `npm run check:watch`.
|
|
- Lint: `npm run lint`.
|
|
- Format: `npm run format`.
|
|
- Generate assets: `npm run generate-assets`.
|
|
- AV sync dev server: `npm run av:dev` (runs inside `av-sync/`).
|
|
- AV render video: `npm run av:render:video -- <args>`.
|
|
- AV render audio: `npm run av:render:audio`.
|
|
|
|
## Tests
|
|
|
|
- Test runner: Vitest (no `test` script defined).
|
|
- Run all tests once: `npx vitest --run`.
|
|
- Run all tests in watch mode: `npx vitest`.
|
|
- Run a single file: `npx vitest --run tests/test-card.test.ts`.
|
|
- Run a single test by name: `npx vitest --run -t "matches baseline"`.
|
|
- Filter by file and name: `npx vitest --run tests/test-card.test.ts -t "matches baseline"`.
|
|
|
|
### Visual regression test notes
|
|
|
|
- The test starts its own dev server on port 5888.
|
|
- It uses Puppeteer; first run creates `tests/output/testcard-baseline.png`.
|
|
- If the baseline changes on purpose, delete the baseline and rerun.
|
|
- Diffs are written to `tests/output/testcard-diff.png` when mismatches exist.
|
|
|
|
## Formatting
|
|
|
|
- Prettier is the source of truth.
|
|
- Tabs for indentation (`useTabs: true`).
|
|
- Single quotes (`singleQuote: true`).
|
|
- No trailing commas (`trailingComma: none`).
|
|
- Max line width 100 (`printWidth: 100`).
|
|
- Svelte files use the Svelte parser.
|
|
|
|
## Linting
|
|
|
|
- ESLint with TypeScript + Svelte recommended rules and Prettier.
|
|
- ESLint ignores `av-sync/**` and all `*.js` files.
|
|
- Prefer fixing lint at the source rather than disabling rules.
|
|
|
|
## TypeScript and SvelteKit
|
|
|
|
- `tsconfig.json` is strict; keep types accurate.
|
|
- Prefer `type` imports: `import type { Foo } from '...'`.
|
|
- Keep `export const` config in SvelteKit route files.
|
|
- Use `+page.ts`/`+layout.ts` conventions and `$types` imports.
|
|
- Use `$lib` alias for shared code inside `src/lib/`.
|
|
- Keep server-only logic in `*.server.ts` or server load functions.
|
|
|
|
## Import style
|
|
|
|
- Order imports: external packages, internal `$lib` or alias, relative paths.
|
|
- Separate type-only imports from runtime imports when it improves clarity.
|
|
- Avoid deep relative paths when `$lib` can be used.
|
|
- Keep named imports sorted when it improves readability.
|
|
|
|
## Naming conventions
|
|
|
|
- Components: `PascalCase.svelte`.
|
|
- Functions/variables: `camelCase`.
|
|
- Constants: `UPPER_SNAKE_CASE` for true constants.
|
|
- Routes: use SvelteKit folder conventions; keep names short and descriptive.
|
|
- Files: favor `kebab-case` for non-component utilities.
|
|
|
|
## Code structure
|
|
|
|
- Use `const` by default; `let` only when reassigned.
|
|
- Prefer `async/await` over `.then()` chains.
|
|
- Keep functions small and focused; extract helpers to `src/lib/`.
|
|
- Keep Svelte components thin; move heavy logic to modules.
|
|
|
|
## Error handling
|
|
|
|
- Throw `Error` objects with clear messages.
|
|
- Catch errors only when you can add context or recover.
|
|
- Avoid silent failures; log or rethrow with added context.
|
|
- For async utilities, reject with `Error` (not strings).
|
|
|
|
## Testing style
|
|
|
|
- Use Vitest `describe/it/expect`.
|
|
- Keep tests deterministic; avoid time-based flakiness.
|
|
- Store artifacts under `tests/output/` only.
|
|
- Use helper functions in `tests/utils.ts` for shared setup.
|
|
|
|
## Styling and UI
|
|
|
|
- This project uses Svelte; prefer local component styles.
|
|
- Keep global styles minimal and intentional.
|
|
- If editing fonts or assets, ensure they remain licensed in dependencies.
|
|
|
|
## Configuration files
|
|
|
|
- `vite.config.ts` defines the `@assets` alias and inlang plugin.
|
|
- `svelte.config.js` uses the static adapter.
|
|
- Keep config changes minimal and documented in code when needed.
|
|
|
|
## Dependency policy
|
|
|
|
- Do not add, remove, or upgrade deps without explicit permission.
|
|
- If you want a new dependency, explain why and ask first.
|
|
|
|
## Cursor/Copilot rules
|
|
|
|
- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found.
|
|
|
|
## Agent workflow tips
|
|
|
|
- Prefer small, focused edits with Prettier-friendly formatting.
|
|
- Run `npm run lint` and `npx vitest --run` for changes touching logic.
|
|
- For UI-only tweaks, at least run `npm run lint`.
|
|
- For config changes, run `npm run check`.
|
|
- For AV sync changes, validate via `npm run av:dev`.
|
|
|
|
## When adding new files
|
|
|
|
- Follow the existing folder structure and naming conventions.
|
|
- Update tests if behavior changes.
|
|
- Avoid introducing new top-level folders without discussion.
|
|
|
|
## Logging
|
|
|
|
- Use `debug` for structured logs in Node utilities.
|
|
- Avoid noisy `console.log` in production code.
|
|
|
|
## Performance
|
|
|
|
- Avoid unnecessary re-renders in Svelte components.
|
|
- Prefer derived values over repeated computation.
|
|
|
|
## Accessibility
|
|
|
|
- Keep semantic HTML in Svelte templates.
|
|
- Ensure interactive elements are keyboard reachable.
|
|
|
|
## Data and assets
|
|
|
|
- Generated assets live under `assets/generated/`.
|
|
- Do not edit generated assets by hand.
|
|
|
|
## Build output
|
|
|
|
- `npm run build` uses Vite and SvelteKit static adapter.
|
|
- `npm run preview` serves the build for verification.
|
|
|
|
## Notes
|
|
|
|
- Keep this file updated when commands or conventions change.
|