Panel/.github/copilot-instructions.md

GSP (GameServerPanel) — Copilot Instructions (No-Code)

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.

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.

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.

Examples of CORRECT usage:

// 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">

Examples of WRONG usage (NEVER DO THIS):

// ❌ 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.

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/).

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.

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.

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/, 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.

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.

---

Additional UI requirement: "Last updated" footer on key pages

When making small content or page edits to the website, ensure the following pages display a human-friendly "Last updated" timestamp at the very bottom of the page (visible to site visitors):

• modules/billing/index.php
• index.php (site root)
• modules/dashboard/dashboard.php

Requirements:

• The text must read exactly: "Last updated at YYYY-MM-DD HH:MM:SS" (24-hour time) where the timestamp reflects the deliberate edit time of the page (see acceptance criteria below).
• Place the timestamp in the page footer area so it does not break layout on mobile or desktop. Keep styling minimal and consistent with the existing footer typography.
• Use the server/local timezone for the timestamp and include the date and time in the format above. Do not include timezone abbreviations in the UI; internal logs may record timezone if needed.

Acceptance criteria:

• Visiting each page shows the "Last updated at" line at the very bottom of the rendered HTML.
• The timestamp matches the time the page's source was last edited (file modification time) or the annotated edit time used by the deployment process. The project maintainer must decide which of these sources is canonical; document the choice in the change plan.
• The line is visible and readable on small screens and does not overlap other UI elements.

Testing checklist:

• Manually open each page and confirm the timestamp is present.
• After making a small edit and deploying, confirm the timestamp updates to the new edit time.
• If using automated deploys, ensure the deploy process preserves or updates the canonical timestamp source (e.g., touch file, update metadata) so the displayed value is accurate.

Maintainer update requirement:

• The canonical human-friendly timestamp is stored in modules/billing/timestamp.txt and MUST be updated whenever site files or content are edited and deployed.
• Format and wording: use a single-line plain-text entry such as: "Last Updated at 7:25am on 2025-15-11". This exact text (including capitalization) is what appears in theme footers.
• Update process: include the timestamp.txt change in the same commit/PR as any content change that should alter the "Last Updated" time, or ensure your deployment process updates the file automatically (for example, a post-deploy hook that writes the current deploy time in the agreed format).
• 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).