mnswpr/CONTRIBUTING.md

Contributing to Cozy Games

Thanks for your interest in contributing! This guide covers what you need to develop, test, and submit changes.

Working as an AI coding agent? See AGENTS.md for machine-oriented guidance. This document is for human contributors.

Prerequisites

• Node.js — the version pinned in .nvmrc (lts/*). With nvm: nvm use.
• pnpm — pnpm is required (npm/yarn will not work). The repo pins its pnpm version via the packageManager field, so the simplest way to get the right one is Corepack: corepack enable.
• Java (JDK 11+, 21 recommended) — only needed to run the local Firestore emulator (used by the mnswpr app's leaderboard in development). pnpm install tries to install a user-local Temurin JRE automatically; if that is skipped (CI or an unsupported platform) install a JDK yourself. You can avoid Java entirely with the dev:no-db script below.

Project Structure

This repo is a single package at the root — the mnswpr.com web app. main.js and index.html are the app itself, modules/ holds the app-owned services, scripts/ holds tooling, and docs/ documents the backend. The game engine and leaderboard come from npm (ayo-run/cozy-games); there is no local packages/ to edit.

Backend config (Firestore rules, Firebase project aliases, Netlify hosting) is committed at the root — see AGENTS.md "Infra".

Setup

pnpm i        # install dependencies

Commands (all run from the repo root)

pnpm test           # run the whole test suite once (Vitest, jsdom)
pnpm test:watch     # tests in watch mode
pnpm lint           # eslint (JS + CSS)
pnpm lint:fix       # eslint --fix

Running the game locally

pnpm run dev          # Vite dev server + Firestore emulator (auto-seeded) — needs Java
pnpm run dev:no-db    # Vite only, no emulator (UI work, or no Java)
pnpm run build        # build the app     -> dist
pnpm run preview      # preview the production build

Tests

Tests run under Vitest with a jsdom environment and live next to the code they exercise (test/, scripts/test/). They drive real behavior — e.g. mounting the game and dispatching DOM events — not just isolated unit calls. Run pnpm test (or pnpm test:watch) before opening a PR, and add tests for new behavior.

Code style

Style is enforced by ESLint (Stylistic), not Prettier:

• 2-space indent, single quotes, no semicolons, no trailing commas
• spaces inside { braces } but not [brackets]
• both **/*.js and **/*.css are linted

Run pnpm lint:fix before committing. The codebase is plain JavaScript with JSDoc + // @ts-check — no TypeScript. Match the style and patterns of the file you're editing (modules/ uses ES classes; scripts/ uses plain functions).

A pre-commit hook runs the linter and a secret scan automatically — commits fail if either does. Keep credentials and any .env.production out of commits.

Infra & local backend (optional)

Only relevant if you're working on backend-touching features. Every app owns its own backend config (declarative, committed in-repo) and its tooling (CLIs as devDependencies) — no web dashboards. For mnswpr (Firestore + Netlify), the local DB emulator is all a contributor needs:

pnpm run db:start   # start the local Firestore emulator (standalone) — needs Java
pnpm run db:seed    # seed the running emulator with sample data
pnpm run db:stop    # stop a stray emulator holding :8080

Deploy scripts (deploy:db, deploy:site) also exist but require project credentials, so they're for maintainers — the first-time setup is documented in docs/deployment.md. See README.md and docs/ for the full backend reference.

Project structure

The repo layout and architecture are documented in AGENTS.md — worth a read before a large change.

Submitting changes

1. Create a branch off main.
2. Make a focused change.
3. Run pnpm lint and pnpm test — both must pass.
4. Write clear, conventional commit messages (feat:, fix:, chore:, …).
5. Open a pull request describing what changed and why; link any related issue.

For anything large, open an issue to discuss the approach first.

Commit & PR hygiene

Write commit messages in plain project voice — what changed and why. Keep them free of AI-tool attribution trailers or footers (including Co-Authored-By: lines crediting a coding assistant) and of session links; the same goes for PR titles and bodies. Co-authoring with another person is always fine — use any address you like, there is no contributor allowlist.

CI also checks your changes against a maintainer-managed reserved-terms list. If a check flags your change, reword it — or ask a maintainer if it isn't clear why. The checks run locally too: the pre-commit hook scans staged changes and your branch name, and the commit-msg hook scans the message. If a line legitimately needs wording a check objects to (prose about these topics, say), put a content-policy: allow-next-line comment above it and mention why in the PR.

License

By contributing, you agree that your contributions are licensed under the project's MIT license.