mainty/AGENTS.md

# AGENTS.md

Agent guidance for working in this repository (`mainty`).

## Project Snapshot

- Stack: PHP 8+, SQLite, Apache, Tailwind via CDN, Bootstrap Icons via CDN.
- Architecture: lightweight MVC-style structure (no Composer, no framework).
- Entry point: `index.php`.
- Routing: `core/Router.php` maps routes to `Controller@method`.
- Data layer: PDO SQLite through singleton in `core/Database.php`.
- Runtime config: constants and debug flags in `config.php`.
- Deployment option: Docker (`Dockerfile`, `docker-compose.yml`) or traditional Apache/PHP host.

## Repository Layout

- `index.php`: bootstrap, environment checks, route registration, request dispatch.
- `core/`: base infrastructure (`Controller`, `Router`, `Database`).
- `controllers/`: request handlers, auth/setup guards, redirects.
- `models/`: database queries and persistence logic.
- `views/`: server-rendered PHP templates and inline JS.
- `data/`: SQLite DB location (`data/mainty.db`), ignored by Git.
- `README.md`: user-facing setup notes.
- `DOCKER.md`: Docker workflow and troubleshooting.

## Build, Lint, and Test Commands

This repo currently has no formal package manager scripts (`composer.json`, `package.json`) and no configured PHPUnit/Pest suite.

### Local runtime checks

- Start app with Docker:
  - `docker-compose up -d`
- Rebuild and start:
  - `docker-compose up -d --build`
- Stop containers:
  - `docker-compose down`
- Follow logs:
  - `docker-compose logs -f`
- Open app:
  - `http://localhost:8080`

### Linting (available today)

- Lint a single PHP file:
  - `php -l path/to/file.php`
- Lint all PHP files from repo root:
  - `find . -name "*.php" -print0 | xargs -0 -n1 php -l`

### Tests (current state)

- There is no automated test suite committed in this repository at this time.
- Use targeted syntax checks plus manual verification in browser for affected flows.

### Single-test guidance

- Since no test framework is configured, there is no native "run one unit test" command yet.
- Closest equivalent today:
  - Run syntax check on changed file: `php -l path/to/changed.php`
  - Validate one user flow manually (for example setup/login/add vehicle).
- If PHPUnit is introduced later, single-test pattern should be:
  - `vendor/bin/phpunit tests/Path/To/TestFile.php`
  - or `vendor/bin/phpunit --filter testMethodName`

## Development Workflow for Agents

- Prefer small, focused edits in the relevant layer (controller/model/view).
- Preserve existing architecture; avoid introducing frameworks or heavy abstractions.
- Keep route definitions centralized in `index.php` unless project conventions change.
- For DB changes, update `Database::initialize()` schema and ensure migration path for existing DBs.
- Validate impact on setup/auth guards (`requireSetup()`, `requireAuth()`).
- When touching rendered output, maintain existing Tailwind + Bootstrap Icons approach.

## Code Style and Conventions

The project does not include an enforced formatter. Follow established in-repo patterns.

### PHP formatting

- Use 4-space indentation; no tabs.
- Opening braces are on the same line for classes, methods, and control structures.
- Keep method visibility explicit (`public`, `private`, `protected`).
- Prefer strict return types and parameter types where already used.
- Add blank lines between logical blocks to keep controllers readable.

### Imports and file organization

- There are no namespaces and no `use` imports currently.
- Autoloading is manual via `spl_autoload_register` in `index.php`.
- New class files should be placed in one of:
  - `core/`
  - `controllers/`
  - `models/`
- Class name must match filename (e.g., `VehicleController` in `controllers/VehicleController.php`).

### Types and data handling

- Follow existing scalar type hints (`string`, `int`, `array`, `bool`, `void`).
- For IDs from route params, cast to int in controllers before model calls.
- Treat user input as untrusted; trim and validate before persistence.
- Use nullable values consistently when optional fields are absent.

### Naming conventions

- Classes: PascalCase (`MaintenanceController`, `QuickTask`).
- Methods/functions: camelCase (`changePassword`, `getByVehicleId`).
- Variables/properties: camelCase (`$maintenanceItems`, `$quickTaskModel`).
- DB columns: snake_case (`license_plate`, `updated_at`).
- Route paths: kebab/snake mix already exists; follow existing route patterns.

### Database and SQL conventions

- Use prepared statements for variable-bound SQL (existing standard).
- Keep SQL readable with multiline strings where complex.
- Return arrays from model queries (`fetchAll()`/`fetch()`) per current style.
- Keep persistence logic inside models; avoid SQL in controllers/views.

### Error handling and user feedback

- Controllers use session flash messages (`$_SESSION['error']`, `$_SESSION['success']`).
- Redirect after mutations instead of rendering directly.
- For JSON endpoints, return structured JSON via `Controller::json()`.
- Internal failures are currently handled with basic `die()` or fallback messages.
- Do not leak sensitive data in production; respect `DEBUG` flag in `config.php`.

### Security and output escaping

- Escape user-facing output in views with `htmlspecialchars()`.
- Keep password handling through `password_hash()` and `password_verify()`.
- Maintain auth checks on protected routes.
- Be cautious with direct echo of exception messages.

### Frontend conventions in views

- Server-rendered PHP templates with inline Tailwind classes.
- Keep interactions lightweight with inline `<script>` blocks per page.
- Reuse visual language already present (cards, rounded corners, blue primary actions).
- Preserve responsiveness (mobile-first classes used throughout existing views).

## Cursor / Copilot Instruction Files

Checked locations requested by user:

- `.cursor/rules/`: not present in this repository.
- `.cursorrules`: not present in this repository.
- `.github/copilot-instructions.md`: not present in this repository.

If any of these files are added later, treat them as high-priority agent instructions and update this document accordingly.

## Verification Checklist Before Finishing a Change

- Run `php -l` on each changed PHP file.
- If Dockerized workflow is relevant, run `docker-compose up -d` and load the touched page.
- Confirm setup/auth redirects still behave correctly.
- Confirm flash messages and redirects still match expected UX.
- Avoid committing generated DB files or secrets (`data/*.db`, `.env`).