ohmj2/AGENTS.md

AGENTS.md - Development Guidelines

This file contains essential information for AI agents working on this codebase.

Project Overview

PHP website for "Harmonie de Montpellier-Jacou" (music band) with a Vue.js 2 frontend for score management.

• Backend: PHP with MySQL (legacy codebase)
• Frontend: Vue.js 2 + Bootstrap Vue (in frontend/score/)
• API: RESTful PHP API in api/ directory

Build Commands

Frontend (Vue.js)

cd frontend/score
npm install
npm run serve      # Development server
npm run build      # Production build
npm run lint       # ESLint check

PHP

No build step required. Deploy to PHP-enabled web server.

Testing

No test framework configured.

To add tests:

• PHP: Consider PHPUnit
• Vue: Add Jest or Vitest via Vue CLI

Run single test (when configured):

# Example for Jest (not yet configured)
npm test -- --testNamePattern="test name"

Code Style Guidelines

PHP

• Use <?php opening tags (avoid short <? tags for consistency)
• Classes: PascalCase (e.g., Score, Database)
• Methods: camelCase (e.g., readScore, getEntryName)
• Variables: snake_case or camelCase (be consistent within files)
• Indent: 3 spaces (legacy style) - maintain consistency with surrounding code
• Place opening braces on same line as class/function declaration
• Use include_once for required files
• Note: Uses legacy MySQL functions (consider upgrading to PDO/MySQLi)

JavaScript/Vue

• ESLint configuration in package.json:
  • Extends: plugin:vue/essential, eslint:recommended
  • Parser: babel-eslint
• Use ES6+ features (async/await, arrow functions)
• Components: PascalCase
• Data properties: camelCase
• Use 2-space indentation
• Semicolons required

General

• UTF-8 encoding for all files
• French language for user-facing content
• Maintain GPL v2 license headers in PHP files

File Organization

/
├── api/              # REST API endpoints
│   ├── config/       # Database configuration
│   ├── objects/      # Data models
│   └── score/        # API endpoints
├── frontend/score/   # Vue.js application
│   ├── src/          # Source code
│   └── public/       # Static assets
├── Scripts/          # PHP page controllers
├── fpdf/             # PDF generation library
├── Imgs/             # Image assets
├── Textes/           # Text content files
└── index.php         # Main entry point

Database

MySQL database connection configured in api/config/database.php:

• Uses legacy mysql_* functions
• Database name: ohmj2
• Tables: repertoire (for scores)

Error Handling

• PHP: Uses @ error suppression operator in some places
• Vue: Uses try/catch with console.log for errors
• Return HTTP 200 on success in API responses

Security Notes

• API uses Access-Control-Allow-Origin: * (CORS enabled for all)
• SQL queries use string concatenation (vulnerable to SQL injection)
• Database credentials stored in plain text in api/config/database.php
• Sanitize user inputs before database queries

Git

• No CI/CD configured
• Commit to main branch
• Standard .gitignore for Node.js projects

Dependencies

Frontend

• Vue 2.6.11
• Bootstrap Vue 2.17.3
• Axios 0.21.0
• Vue CLI 4.5.0

PHP

• FPDF library for PDF generation
• MySQL extension (legacy)

Important Notes

• No external CDN dependencies allowed - All assets must be local (fonts, JS libraries, etc.)
• Use local copies in static/ folder instead of CDN

Notes

• This is a legacy codebase with mixed coding styles
• Prefer consistency with existing code over strict style enforcement
• Site targets French-speaking users
• Production URL: ohmj2.free.fr

Design Guidelines

• Style: Clean, sober, and modern
• Icons: Use SVG icons instead of emojis for better consistency
• Buttons: Integrate related actions (view + download) in a single row with consistent styling
• Hide unnecessary labels: Don't show "Piece 1" or "Version 1" when there's only one
• Visual hierarchy: Use spacing, subtle borders, and hover effects for interactivity

Temporary Work Files

• Use _builds/ directory for temporary scripts and working files
• Only scripts/convert_final_v2.js should be kept in the scripts folder (committed to git)
• CSV output files belong in _builds/

Authentication

• Login: Use apiService.login('admin', 'password') from frontend
• API calls: Include token in Authorization header:

  Authorization: Bearer <token>
  

• Token format: JWT (HS256) - see api/lib/Auth.php
• Frontend: Token stored in localStorage, auto-attached to API requests via axios interceptor
• Test: http://localhost:5173 - login with admin/password
• API base URL: http://localhost:8000/api/

Current Tech Stack (2024)

• Frontend: SvelteKit (NOT Vue.js 2) in /partitions/
• Backend: PHP API in /api/
• Scores storage: /legacy/Scores/ (directory-based, not MySQL)