Revise Open Game Panel ControlPanel instructions

Updated instructions for Open Game Panel ControlPanel, including repository structure, validation processes, and guidelines for development and testing.
2025-10-21 20:15:41 -04:00 · 2025-10-21 20:15:41 -04:00 · 06b0074cee
commit 06b0074cee
parent e20d1c0de6
1 changed files with 136 additions and 108 deletions
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@ -1,123 +1,151 @@
-# Open Game Panel (OGP) ControlPanel
+Repo of truth: GameServerPanel/GSP, branch Panel-unstable.
-Open Game Panel is a PHP-based web application for managing game servers with Linux/Windows agents and Python documentation tools.
+Prime directive: Read this document first. Propose changes that align with our repo and specs. Only search for external info if something contradicts this file.
-Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+1) What to read first (paths & context)
-## Working Effectively
+_website/ — canonical website storefront and Checkout/Webhooks flow.
 - Bootstrap and test the repository:
  - `sudo apt-get update && sudo apt-get install -y php mysql-server libxml-parser-perl libpath-class-perl libarchive-extract-perl libdbi-perl libdbd-mysql-perl libxml-simpleobject-perl libproc-daemon-perl liblinux-inotify2-perl libarchive-zip-perl pandoc texlive-xetex python3 python3-yaml`
  - `sudo service mysql start`
  - `sudo mysql --defaults-file=/etc/mysql/debian.cnf -e "CREATE DATABASE IF NOT EXISTS panel; CREATE USER IF NOT EXISTS 'localuser'@'localhost' IDENTIFIED BY 'testpass'; GRANT ALL PRIVILEGES ON panel.* TO 'localuser'@'localhost'; FLUSH PRIVILEGES;"`
  - Edit `/home/runner/work/ControlPanel/ControlPanel/includes/config.inc.php` to set database password to `testpass`
 - Test Python guide generation tools:
  - `cd /home/runner/work/ControlPanel/ControlPanel && ./tools/generate_all_guides.sh` -- takes 3-10 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
  - `python3 tools/validate_guides.py` -- takes under 1 second
 - Test PHP web application:
  - `cd /home/runner/work/ControlPanel/ControlPanel && php -S localhost:8080 &` 
  - `curl -I http://localhost:8080` (will show 500 error due to missing database schema - this is expected)
  - `pkill -f "php -S"` to stop server
 - Test Perl agent syntax:
  - `cd /home/runner/work/ControlPanel/ControlPanel/_agent-linux && perl -c ogp_agent.pl` -- should show "syntax OK"
-## Validation
+modules/config_games/server_configs/ — authoritative game catalog XMLs (all supported games live here).
 - Always test the Python guide generation workflow when making changes to tools/ directory
 - ALWAYS run `./tools/generate_all_guides.sh` to validate guide generation changes  
 - Test PHP syntax with `php -l <file.php>` for any PHP file changes
 - Test Perl agent syntax with `perl -c ogp_agent.pl` when modifying agent files
 - The web application requires a complete database schema to run properly, but basic connectivity can be tested
-## CRITICAL Build & Test Timing
+modules/ — panel modules (legacy billing/ exists; its schema is authoritative for multi-remote, but the pages are deprecated).
 - **Guide generation: 3-10 seconds** - NEVER CANCEL. Set timeout to 30+ seconds minimum
 - **Guide validation: Under 1 second** - Set timeout to 15+ seconds  
 - **Package installation: 5-15 minutes** - NEVER CANCEL. Set timeout to 20+ minutes
 - **PDF generation (with LaTeX): 2-5 seconds per document** - NEVER CANCEL
 - **Database setup: Under 10 seconds** - Set timeout to 30+ seconds
-## Common Tasks
+includes/ — panel configuration and DB connectors.
 The following are outputs from frequently run commands. Reference them instead of viewing, searching, or running bash commands to save time.
-### Repository Structure
+ogp_api.php — internal API entry point for panel-side actions.
 ```
 /home/runner/work/ControlPanel/ControlPanel/
 ├── index.php                    # Main web application entry point
 ├── includes/                    # PHP includes and configuration
 │   ├── config.inc.php          # Database configuration  
 │   ├── database_mysqli.php     # Database abstraction layer
 │   └── helpers.php             # Utility functions
 ├── modules/                     # Web application modules
 ├── themes/                      # UI themes
 ├── tools/                       # Python guide generation tools
 │   ├── generate_all_guides.sh  # Main guide generation script
 │   ├── generate_server_guides.py # Python guide generator
 │   └── validate_guides.py      # Guide validation script
 ├── _agent-linux/               # Linux agent (Perl)
 │   ├── ogp_agent.pl           # Main agent script
 │   └── ogp_agent_run          # Agent wrapper script
 ├── _agent-windows/             # Windows agent
 ├── data/games/                  # YAML game definitions for guides
 └── dist/pdfs/                  # Generated PDF guides
 ```
-### Dependencies Status  
+paypal/ — PayPal code if present in this branch.
 - **PHP 8.3.6**: Available, with MySQLi extension
 - **MySQL 8.0**: Available, can be started with `sudo service mysql start`
 - **Perl 5.38**: Available, with all required OGP modules installed
 - **Python 3.12**: Available, with PyYAML installed  
 - **Pandoc + XeLaTeX**: Available, for PDF generation
-### Guide Generation Workflow
+2) No-Code Planning Mode (default)
 ```bash
 # Complete workflow (3-10 seconds total)
 cd /home/runner/work/ControlPanel/ControlPanel
 ./tools/generate_all_guides.sh
-# Individual steps
+Do not emit PHP, SQL, XML, or shell commands unless a maintainer explicitly asks: “Generate code now.”
 python3 tools/generate_server_guides.py  # Generate markdown + PDFs
 python3 tools/validate_guides.py         # Validate output
-# Expected output structure:
+While in planning mode, produce only:
 # docs/games/<game-slug>/index.md         # Markdown guides
 # dist/pdfs/<game-slug>__Server_Admin_Guide_v1.pdf # PDF guides  
 # docs/games/_index.md                    # Index page
 # dist/pdfs/manifest.json                 # Metadata manifest
 ```
-### Agent Testing
+Impacted paths and files,
 ```bash
 # Test Perl agent syntax (agent requires special permissions to run)
 cd /home/runner/work/ControlPanel/ControlPanel/_agent-linux
 perl -c ogp_agent.pl
 # Expected: "ogp_agent.pl syntax OK"
 ```
-### Database Setup for Testing
+Step-by-step plans with acceptance criteria,
 ```bash
 # Basic database setup (already configured)
 sudo service mysql start
 mysql -u localuser -ptestpass -e "SHOW DATABASES;"
 # Should show: information_schema, panel, performance_schema
 ```
-### Web Application Testing
+Risks, rollbacks, and test/validation checklists,
 ```bash
 # Start development server (will show 500 errors without complete DB schema)
 cd /home/runner/work/ControlPanel/ControlPanel  
 php -S localhost:8080 &
 curl -I http://localhost:8080  # Test connectivity
 pkill -f "php -S"              # Stop server
 ```
-## Key Projects in Codebase
+Data mappings that reference existing tables/fields.
 1. **Web Panel** (`index.php`, `modules/`, `themes/`): PHP web application for game server management
 2. **Linux Agent** (`_agent-linux/`): Perl-based agent for Linux game server management  
 3. **Windows Agent** (`_agent-windows/`): Windows version of server agent
 4. **Guide Tools** (`tools/`): Python scripts for generating comprehensive server admin documentation
 5. **Game Definitions** (`data/games/`): YAML files defining game server configurations for guide generation
-## Important Notes
+3) Scope & principles
- The web application requires complete database schema initialization to run fully (beyond basic connectivity testing)
+
- Agents require special system permissions and users to run properly in production
+Website ↔ Panel on the same host. Website uses the panel DB for authentication and the panel’s internal APIs for provisioning. Sessions remain separate (website session ≠ panel session).
- Guide generation tools work independently and can be tested without the web application
+
- PDF generation requires both pandoc and XeLaTeX (texlive-xetex package)
+Catalog = XML. Enable every game present under modules/config_games/server_configs/. The website reads those XMLs for ports, params, install/update metadata. New XMLs should become available without code changes.
- All basic syntax checking and connectivity testing works in this environment
+
- Focus testing on the components that can be fully validated: guide tools, PHP syntax, Perl syntax, and basic connectivity
+Regions/Nodes = panel DB. Regions and nodes are configured in the panel and must be queried live from the panel DB. Never hardcode or mirror region lists on the website.
 Slotless model. Pricing/UX must not enforce slot caps. If an engine requires a player count parameter, set a safe high default and surface engine limits transparently if they exist.
 Auth compatibility. Panel users use legacy MD5 in ogp_users. The website should prefer a modern hashing shadow and upgrade transparently on successful login, without breaking panel login.
 Checkout/Webhooks. Follow the working PayPal Checkout flow in _website/. Use REST Webhooks only. Mark orders paid only after webhook verification.
 Legacy billing module. Treat modules/billing/ pages as deprecated. Reuse the existing tables/fields introduced there for multi-remote support. Do not invent parallel schema.
 4) Functional requirements (design-level only)
 4.1 Catalog (from XML)
 Parse all XMLs under modules/config_games/server_configs/.
 Normalize game key, display name, required ports, startup parameters, install/update routines, and any engine constraints.
 Support hot-add: new XMLs become available to the storefront after a repo update.
 4.2 Authentication & sessions
 Website registration creates a panel user (legacy-compatible) and stores a modern hash shadow linked 1:1 to that user.
 Login prefers the modern hash; on MD5 success, upgrade silently to the modern hash.
 Maintain separate sessions for website and panel.
 4.3 Checkout → Webhooks → Provisioning
 Mirror _website/ structure and flows for Checkout.
 On verified webhook events: transition order state to paid, create service records, and provision a panel Home using internal panel APIs.
 Derive ports and startup parameters from the XML metadata.
 4.4 Regions/Nodes (multi-remote)
 At checkout or during provisioning, present or auto-select regions/nodes by reading the panel DB.
 If a node is hidden/disabled in the panel, it must not appear in the website UI.
 4.5 Billing automation (website-side)
 Reconcile renewals and invoke panel APIs to suspend/reactivate/terminate services.
 Operations must be idempotent and observable (logs/metrics defined at design time).
 5) Data model alignment (no DDL)
 Use the panel DB as the source of truth.
 Multi-remote tables and fields already exist (introduced by the legacy billing work). Reuse them.
 Only propose new fields/tables if strictly necessary; when doing so, reference existing naming conventions and provide a migration plan (still no SQL while in planning mode).
 6) Coding standards & security (what to enforce when code is requested)
 Repository-first: Before proposing file names, endpoints, or structures, search Panel-unstable to reuse existing helpers, patterns, and locations.
 Strictness: Prefer strict comparisons; parameterized DB access; centralized input validation and output escaping.
 Session & CSRF: Harden website sessions and require CSRF tokens on state-changing requests.
 Webhooks: Verify signatures and event types server-side; never trust client redirects for payment state.
 XML: Harden parsing (no external entities; size/complexity limits). Treat XML as untrusted input even though it’s in-repo.
 Observability: Define success/failure metrics, audit logs for state changes, and trace IDs for provisioning flows.
 Licensing: Preserve upstream notices and ensure our additions stay license-compatible.
 7) Validation checklist (pre-PR / pre-merge)
 Read _website/, modules/config_games/server_configs/, modules/, includes/, paypal/ (if present), and ogp_api.php to anchor proposals to actual code.
 Catalog uses only the XML metadata; no hardcoded ports/params.
 Regions/nodes are read live from the panel DB; no duplicates on the website.
 Auth plan preserves panel compatibility and modernizes website hashing; sessions remain separate.
 Checkout mirrors _website/; uses REST Webhooks; paid state changes occur only after verification.
 Provisioning calls panel internals (e.g., ogp_api.php), respects selected/auto node, and records mappings consistently.
 Legacy billing module pages are not extended; its schema is reused for multi-remote.
 Security items from §6 are addressed in the plan: CSRF, webhook verification, strict comparisons, hardened XML.
 8) Deliverables for Copilot (when planning)
 A concise change plan that lists:
 Files to create/modify/remove and their locations,
 Data sources and mappings to existing tables/fields,
 UX notes (e.g., region selector vs auto-placement),
 Risks, rollback approach, and test coverage,
 Acceptance criteria aligned to these instructions.
 Update CHANGELOG.md with a brief, high-signal entry (date, scope, rationale).
 Append a single line item to docs/COPILOT_TODO.md for any UI follow-ups or next steps.
 9) Prohibited while in planning
 No PHP/SQL/XML.
 No shell commands or system setup steps.
 No scaffolding diffs or auto-generated file dumps.