From f8fd12c5de0e040390fbb69edc1c760b58d29b77 Mon Sep 17 00:00:00 2001 From: objec Date: Wed, 20 May 2026 17:04:46 +0400 Subject: [PATCH] Unify CLAUDE.md and AGENTS.md Signed-off-by: objec --- AGENTS.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 100 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 849203d3d..195688146 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,29 +1,108 @@ # Agent Instructions -This document provides guidance for AI agents working on the Open Source Point of Sale (OSPOS) codebase. +This document is the single source of truth for all AI agents working on the Open Source Point of Sale (OSPOS) codebase. Read it fully before making any changes. + +## Project Overview + +OpenSourcePOS is a web-based Point of Sale system built on **CodeIgniter 4** (PHP 8.2+) with MySQL/MariaDB. Frontend uses Bootstrap 3 (Bootstrap 5 migration in progress) and jQuery, with assets built via Gulp. + +## Common Commands + +```bash +# PHP dependencies +composer install + +# Frontend dependencies and asset build +npm install +npm run build # Runs Gulp: compiles and copies all CSS/JS to public/resources/ + +# Run full test suite +composer test + +# Run a single test file +vendor/bin/phpunit tests/unit/AppTest.php + +# Lint / code style check +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php --dry-run + +# Apply code style fixes +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php +``` + +Tests require a MariaDB/MySQL database (see CI config in `.github/workflows/phpunit.yml`). + +## Architecture + +### Framework & Entry Point + +- **Framework**: CodeIgniter 4 — MVC with QueryBuilder ORM, no Eloquent +- **Web root**: `public/` — `public/index.php` is the only entry point +- **Routes**: `app/Config/Routes.php` +- **App config**: `app/Config/App.php` (version, session, security settings) +- **Environment**: `.env` file (copy from `.env.example`); `CI_ENVIRONMENT` controls dev/prod/test mode + +### Directory Layout + +```text +app/ +├── Config/ # CI4 config classes +├── Controllers/ # ~27 controllers (Sales, Items, Reports, Customers, etc.) +├── Models/ # ~28 models (Sale, Item, Customer, Supplier, etc.) +├── Views/ # PHP view templates +├── Libraries/ # Business logic (Sale_lib, Tax_lib, Receiving_lib, etc.) +├── Plugins/ # Plugin system — each plugin is a subdirectory here +├── Database/ # Migrations (ospos_ prefix) and seeds +├── Language/ # i18n files (IETF BCP 47 locale names) +├── Filters/ # Request/response filters (auth, HTTPS, etc.) +└── Events/ # CI4 event subscribers +public/ +└── resources/ # Built CSS/JS (do not edit directly — generated by npm run build) +tests/ # PHPUnit test suite +``` + +### Key Libraries + +`app/Libraries/` holds core business logic: +- `Sale_lib.php` — sale cart state, pricing, discounts, tax calculation +- `Tax_lib.php` — multi-tier tax engine +- `Receiving_lib.php` — purchase orders / receivings +- `Barcode_lib.php` — barcode generation +- `Email_lib.php` — email delivery +- `Token_lib.php` — CSRF/session token management + +### Database + +- Table prefix: `ospos_` (defined in `app/Config/Database.php`) +- Migrations live in `app/Database/Migrations/` and run automatically on first access +- CodeIgniter QueryBuilder throughout — no raw SQL unless necessary + +### Plugin System + +Plugins live in `app/Plugins//` and are auto-discovered by `PluginManager`. Each plugin: +- Extends `BasePlugin` or implements `PluginInterface` +- Registers event hooks (e.g., `item_sale`, `customer_saved`, view hooks like `customer_tabs`) +- Can include its own `Views/`, `Models/`, `Controllers/`, and `Language/` subdirectories +- Configuration stored in `ospos_plugin_config` table +- See `app/Plugins/README.md` for plugin structure, event hooks, and LICENSE requirements + +### Frontend Build + +`gulpfile.js` (Gulp 5) copies vendor CSS/JS from `node_modules/` into `public/resources/`. Run `npm run build` after installing npm packages or changing gulp tasks. Do not manually edit files under `public/resources/`. ## Code Style -- Follow PHP CodeIgniter 4 coding standards -- Run PHP-CS-Fixer before committing: `vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php` -- Write PHP 8.2+ compatible code with proper type declarations -- Use PSR-12 naming conventions: `camelCase` for variables and functions, `PascalCase` for classes, `UPPER_CASE` for constants +- **PSR-12** enforced via PHP-CS-Fixer (config: `.php-cs-fixer.no-header.php`) +- `camelCase` for variables and methods; `PascalCase` for classes; `UPPER_CASE` for constants +- PHP 8.2+ features acceptable (named arguments, enums, readonly properties) +- Views in `app/Views/errors/html/` are excluded from the fixer +- Run fixer before committing: `vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php` -## Development +## Development Workflow - Create a new git worktree for each issue, based on the latest state of `origin/master` - Commit fixes to the worktree and push to the remote - -## Testing - -- Run PHPUnit tests: `composer test` -- Tests must pass before submitting changes -- Minimum PHPUnit version: 10.5.16+. Default config: `phpunit.xml.dist` in project root - -## Build - -- Install dependencies: `composer install && npm install` -- Build assets: `npm run build` or `gulp` +- Tests must pass before submitting changes (`composer test`) +- Minimum PHPUnit version: 10.5.16+. Default config: `phpunit.xml.dist` ## Conventions @@ -37,6 +116,10 @@ This document provides guidance for AI agents working on the Open Source Point o ## Security +- `app.allowedHostnames` **must** be set in production (host header injection protection) +- HTMLPurifier for HTML sanitization; Laminas Escaper for output escaping +- CSRF tokens managed via `Token_lib` — do not bypass CI4's CSRF filter +- Session storage is database-backed (`ospos_sessions` table) for multi-instance support - Never commit secrets, credentials, or `.env` files - Use parameterized queries to prevent SQL injection - Validate and sanitize all user input