site changes by codex

.github/copilot-instructions.md

@@ -1,150 +1,126 @@
-# GSP (GameServerPanel) — Copilot Instructions (No-Code)
+# GSP (GameServerPanel) – Copilot Instructions
 
 **Repo of truth:** `GameServerPanel/GSP`, branch `Panel-unstable`.  
-**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.
+**Prime directive:** Read this document first. Keep `.github/agent.md` identical to this file—any edit here must be mirrored there in the same commit.
 
-## Standalone website mode
-- When working on website features, treat the `_website/` folder as a standalone website root. All website-focused changes (pages, runtime, data persistence, webhooks, and admin UI for the storefront) should live inside `_website/` and be referenced relative to that folder.
-- Do NOT modify files outside `_website/` (the panel codebase) unless a maintainer explicitly asks for cross-repo or panel-side changes. If a change necessarily touches panel files, call it out clearly in the plan and get maintainer approval first.
-- All redirects, data directories, and public-facing endpoints implemented for the storefront must be scoped under `_website/` (absolute or root-relative to the `_website` site root), not the panel root or external panel dashboard pages.
+## Deployment model & paths
+- `modules/billing/` houses the public storefront. Those files are always present inside the panel repo and get deployed either (a) as the root of a dedicated virtual host or (b) through the panel module loader (`home.php?m=billing`).
+- Because the storefront and the control panel live in the same tree, you may include panel helpers when needed. Use the dedicated bridge include (`modules/billing/includes/panel_bridge.php`) instead of sprinkling ad-hoc `../../includes/...` calls.
+- We keep Apache/Nginx vhosts pointed at `modules/billing/`, so every storefront URL must look root-relative (see critical section below). Never expose `/modules/billing` in any URL sent to a browser or external service.
+- Before touching billing logic or module wiring, skim `.github/module-map.md` to remember how the panel modules depend on each other.
 
 ## CRITICAL: Website file paths and URLs (modules/billing)
-- **The billing website files in `modules/billing/` will be deployed at the WEBSITE ROOT when live.**
-- **NEVER EVER use `/modules/billing/` in any URL, link, redirect, or file path within the billing website code.**
-- **All URLs must be root-relative (starting with `/` but NOT including `/modules/billing/`):**
-  - ✅ CORRECT: `/payment_success.php`, `/cart.php`, `/order.php`
-  - ❌ WRONG: `/modules/billing/payment_success.php`, `modules/billing/cart.php`
-- **This is a CRITICAL requirement that has been violated multiple times. Read this section carefully before making ANY changes to billing website files.**
+- **The billing website files in `modules/billing/` are deployed at the WEBSITE ROOT when live.**
+- **Never output `/modules/billing/` in any link, redirect, script tag, or webhook URL. All user-facing URLs must be root-relative**, e.g. `/payment_success.php`, `/cart.php`.
+- Continue to use root-relative URLs inside HTML/JS and when building PayPal return/cancel links. The deployment tooling rewrites the document root; hardcoding `/modules/billing` breaks both standalone hosting and module embedding.
 
-### Examples of CORRECT usage:
+### Examples of CORRECT usage
 ```php
-// PayPal return URLs
 $returnUrl = $siteBase . '/payment_success.php';
-$cancelUrl = $siteBase . '/payment_cancel.php';
-
-// Header redirects
-header('Location: /cart.php');
 header('Location: /order.php');
-
-// Links
-<a href="/my_account.php">My Account</a>
-<a href="/serverlist.php">Browse Servers</a>
-
-// Form actions
 <form action="/add_to_cart.php" method="POST">
+<a href="/my_account.php">My Account</a>
 ```
 
-### Examples of WRONG usage (NEVER DO THIS):
+### Examples of WRONG usage (NEVER DO THIS)
 ```php
-// ❌ WRONG - includes modules/billing path
 $returnUrl = $siteBase . '/modules/billing/payment_success.php';
 header('Location: /modules/billing/cart.php');
 <a href="/modules/billing/my_account.php">My Account</a>
 ```
 
-### Exception - Backend includes only:
-- Backend PHP includes CAN use `__DIR__` or relative paths for file inclusion:
-  - ✅ `require_once(__DIR__ . '/includes/config.inc.php')`
-  - ✅ `require_once(__DIR__ . '/../../includes/database_mysqli.php')`
-- But these are for SERVER-SIDE file inclusion, NOT for user-facing URLs/redirects/links.
+### Exception – backend includes only
+- Server-side includes may use absolute filesystem paths, but route those through the bridge helpers when panel context is required:
+  - ✅ `require_once(__DIR__ . '/includes/config.inc.php');`
+  - ✅ `require_once(__DIR__ . '/includes/panel_bridge.php');`
+- Avoid copy/pasting panel bootstrap code; lean on the helpers already shipped inside `modules/billing/includes/`.
 
-## 1) What to read first (paths & context)
-- `_website/` — canonical website storefront and Checkout/Webhooks flow.
-- `modules/config_games/server_configs/` — authoritative game catalog XMLs (all supported games live here).
-- `modules/` — panel modules (legacy `billing/` exists; its **schema** is authoritative for multi-remote, but the **pages** are deprecated).
-- `modules/billing/` — frontend website for selling gameservers to customers. Can interface with panel from same machine or external web host via MySQL tables. Uses `gameservers_website` session namespace (separate from panel sessions).
-- `includes/` — panel configuration and DB connectors.
-- `ogp_api.php` — internal API entry point for panel-side actions.
-- `api/` — Payment-related API code if present in this branch (previously under `paypal/` or `payments/`).
+## 1) What to read first
+- `.github/module-map.md` – living diagram of how the panel, billing site, daemons, and cron jobs talk to each other.
+- `modules/billing/` – storefront runtime, payment handlers, provisioning bridge.
+- `modules/config_games/server_configs/` – authoritative XML metadata for every supported game.
+- `modules/` – control-panel modules (billing runs here too when embedded).
+- `includes/` & `ogp_api.php` – database layer, shared helpers, remote agent operations.
 
-## 2) No-Code Planning Mode (default)
-- Do **not** emit PHP, SQL, XML, or shell commands unless a maintainer explicitly asks: **“Generate code now.”**
-- While in planning mode, produce only:
-  - Impacted paths and files,
-  - Step-by-step plans with acceptance criteria,
-  - Risks, rollbacks, and test/validation checklists,
-  - Data mappings that reference existing tables/fields.
+## 2) Planning mode (default)
+While scoping multi-file work, do **not** emit PHP/SQL/XML or run shell commands unless a maintainer explicitly says “Generate code now.” Plans should cover:
+- Impacted files and rationale.
+- Data mappings (tables/fields) you will touch.
+- Risks, rollback notes, validation/tests.
 
 ## 3) Scope & principles
-- **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).
-- **Billing module is STANDALONE AND RELOCATABLE.** The `modules/billing/` directory is a **complete standalone website** that:
-  - Can be deployed on the **same machine as the panel** OR on a **completely separate external web host**
-  - Must **NEVER** use `require_once` to include panel files (like `includes/database_mysqli.php`, `includes/functions.php`, or any panel helper files)
-  - Must use **ONLY standard PHP libraries** (mysqli, json, curl, session, etc.)
-  - Connects directly to MySQL using `mysqli_connect()` with credentials from `modules/billing/includes/config.inc.php`
-  - All database operations use native mysqli functions: `mysqli_query()`, `mysqli_real_escape_string()`, `mysqli_fetch_assoc()`, etc.
-  - Must **NOT** use panel-specific functions like `$db->query()`, `createDatabaseConnection()`, `get_lang()`, etc.
-  - All file paths for includes use `__DIR__` relative paths (e.g., `require_once(__DIR__ . '/includes/config.inc.php')`)
-  - All URLs/redirects/links use root-relative paths WITHOUT `/modules/billing/` prefix (see CRITICAL section above)
-- **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.
-- **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.
+- **Single session across panel + storefront.** Every billing page must call `session_name('opengamepanel_web')` before `session_start()`. Always keep `$_SESSION['user_id']`, `$_SESSION['users_login']`, `$_SESSION['users_group']`, and `$_SESSION['website_user_id']` in sync so that logging into either surface signs the visitor into both.
+- **Auth reuse.** Preferred order when verifying credentials: `users_pass_hash` (modern hash) → legacy `users_passwd` (MD5). Upgrading to a modern hash is allowed so long as panel logins keep working.
+- **Bridge for panel helpers.** Use `modules/billing/includes/panel_bridge.php` to load panel classes (`OGPDatabase`, `OGPRemoteLibrary`, XML parsers) when the storefront needs to provision servers or read panel-only metadata. Do not reinvent ad-hoc copies of panel logic.
+- **Storefront runtime.** Public pages continue to use mysqli with credentials from `modules/billing/includes/config.inc.php`. Provisioning steps may request an `OGPDatabase` handle from the bridge.
+- **Provisioning pipeline.** Always funnel server creation or renewals through the shared provisioner (`modules/billing/includes/provisioner.php`). This helper wraps the old `create_servers.php` logic and ensures PayPal captures, cron jobs, and panel clicks all follow the same code path.
+- **Catalog = XML.** Never hardcode game metadata. Parse `modules/config_games/server_configs/*.xml` at runtime; new XMLs must show up automatically.
+- **Regions/Nodes = live DB.** Pull nodes/locations from the panel DB (`gsp_remote_servers`, etc.). Respect admin enable/disable flags and never mirror node lists into flat files.
+- **Game XML wiki parity.** We ship a PHP-rendered version of https://github.com/OpenGamePanel/OGP-Website/wiki/XML-Notes inside `modules/billing/` (linked from the storefront admin area). Keep it updated so maintainers can edit XMLs without leaving the repo.
 
-## 4) Functional requirements (design-level only)
+## 4) Functional requirements
 ### 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.
+- Parse every XML under `modules/config_games/server_configs/`.
+- Normalize: game key, display name, install/update commands, default ports, mod metadata.
+- XML pages (`modules/billing/docs.php` and the new XML-notes mirror) must stay in sync so AI-powered edits can cross-reference expectations.
 
 ### 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.
+- Website registration must create/maintain panel users. Set both the legacy `users_passwd` and the modern hash column.
+- Login flow must hydrate the shared session variables so `home.php` immediately recognizes the visitor.
+- All storefront guards should treat `$_SESSION['user_id']` as the source of truth, falling back to `website_user_id` only for older sessions.
 
-### 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.3 Checkout → PayPal → Provisioning
+- Flow: add to cart → invoices (`billing_invoices`) → PayPal order (`api/create_order.php`) → capture (`api/capture_order.php`) → immediately hand off to `BillingProvisioner`.
+- Mark invoices paid **only** after verifying PayPal response/webhook. Support multiple servers per payment: loop through every paid invoice and either create a new order or extend an existing service.
+- For renewals, extend `end_date` from its current value and keep status at `installed`. For new services set status `installing`, invoke the provisioner, then switch to `installed` on success.
+- Provisioner is responsible for calling `modules/billing/create_servers.php` logic, adding homes, assigning ports, enabling FTP, and logging/notifications. Never bypass it.
 
 ### 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.
+- `remote_servers` and `remote_server_ips` tables remain the source for available locations. Admin tooling (`adminserverlist.php`) must let staff toggle availability and restrict services per location.
+- When a node is globally disabled it must disappear (or show as unavailable) in ordering and admin tools.
 
 ### 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).
+- Cron/workers under `modules/billing/cron-shop.php` still suspend/delete expired services. Renewals triggered via PayPal must update `billing_orders.status` and `end_date` consistently so cron jobs can pick up where they expect.
+- Keep audit logs in `modules/billing/logs/` whenever automatic provisioning, renewals, refunds, or coupon adjustments happen.
 
-## 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).
+## 5) Data model alignment (no DDL during planning)
+- Use panel tables as the source of truth (`gsp_billing_orders`, `gsp_billing_services`, `gsp_billing_invoices`, `gsp_game_mods`, etc.).
+- Multi-remote fields (`remote_server_id`, IP IDs) already exist—never introduce duplicates in the storefront DB.
+- When you truly need schema changes, follow the naming conventions, provide migrations under `modules/billing/*.sql`, and describe the plan first.
 
-## 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.
+## 6) Coding standards & security
+- Parameterize SQL or escape inputs with mysqli real_escape-string helpers.
+- Harden sessions (regenerate IDs on login, honor `modules/billing/timestamp.txt` for public timestamps).
+- CSRF-protect every POST/DELETE-like operation in the storefront admin.
+- Verify PayPal signatures, never trust client-side status.
+- XML parsing: disable external entities, enforce file size limits.
+- Observability: keep per-request IDs in `logs/` to trace provisioning attempts.
+- Licensing: leave upstream license headers intact.
 
-## 7) Validation checklist (pre-PR / pre-merge)
-- Read `_website/`, `modules/config_games/server_configs/`, `modules/`, `includes/`, `api/` (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.
+## 7) Validation checklist
+- Read `.github/module-map.md`, `modules/billing/`, panel helpers, and XMLs before proposing architecture changes.
+- Confirm catalog pages only use XML metadata.
+- Confirm node selectors reflect current DB state (respect enabled flags).
+- Test that logging into either the panel (`index.php`) or storefront (`modules/billing/login.php`) logs you into both.
+- PayPal capture should mark invoices paid, create/extend orders, and schedule provisioning instantly. Verify multi-item carts create all services.
+- `BillingProvisioner` must be exercised via PayPal capture, panel module (`create_servers.php`), and any admin “retry” buttons.
+- Documentation admin links must expose the XML-notes PHP mirror and the game docs browsers.
+- Timestamp footer requirement (see below) satisfied whenever site content changes.
 
-## 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.
+## 8) Deliverables for Copilot
+- Concise change plan with:
+  - Files to touch and why.
+  - Data tables/fields involved.
+  - UX notes (new buttons, admin affordances, etc.).
+  - Risks, rollback, and testing.
+- Update `CHANGELOG.md` with a short, high-signal entry.
+- Append one actionable line to `docs/COPILOT_TODO.md` if UI follow-ups remain.
+- Keep `.github/module-map.md` current whenever inter-module behavior changes.
 
-## 9) Prohibited while in planning
-- No PHP/SQL/XML.
-- No shell commands or system setup steps.
-- No scaffolding diffs or auto-generated file dumps.
+## 9) Prohibited while in planning mode
+- No PHP/SQL/XML snippets.
+- No shell commands or tooling setup instructions.
+- No auto-generated diff dumps.
 
 ---
 
@@ -178,4 +154,4 @@ Maintainer update requirement:
 - Rationale: themes are non-PHP files and may not support SSI on all servers; keeping a single canonical plain-text file reduces duplication and avoids server-side includes.
 
 
-**End of Copilot Instructions (No-Code).**
+**End of Copilot Instructions.**