Added agentic files.
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# 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`).
|
||||
Reference in New Issue
Block a user