From 6dba37ed5e451b7ce6304747cc1b18d66dbb2b31 Mon Sep 17 00:00:00 2001 From: Frank Harris Date: Tue, 21 Oct 2025 20:16:56 -0400 Subject: [PATCH] Revise Copilot instructions for clarity and updates Updated Copilot instructions to clarify no-code planning mode and functional requirements. --- .github/copilot-instructions.md | 247 +++++++++++++------------------- 1 file changed, 96 insertions(+), 151 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6d3452e2..0fcb20a0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,151 +1,96 @@ -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. - -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). - -includes/ — panel configuration and DB connectors. - -ogp_api.php — internal API entry point for panel-side actions. - -paypal/ — PayPal code if present in this branch. - -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). - -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/, 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. +# 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. + +## 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). +- `includes/` — panel configuration and DB connectors. +- `ogp_api.php` — internal API entry point for panel-side actions. +- `paypal/` — PayPal code if present in this branch. + +## 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). +- **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/`, `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. + +--- + +**End of Copilot Instructions (No-Code).**