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).