From aa8a1356dc18d012353bbd6dc982e049813dd5f5 Mon Sep 17 00:00:00 2001 From: jester Date: Sun, 3 May 2026 19:55:29 +0000 Subject: [PATCH] Update Portal current state for async create billing support validations --- Codex/Portal/CURRENT_STATE.md | 173 +++++++++++++--------------------- 1 file changed, 63 insertions(+), 110 deletions(-) diff --git a/Codex/Portal/CURRENT_STATE.md b/Codex/Portal/CURRENT_STATE.md index 7a753ab..4a48c46 100644 --- a/Codex/Portal/CURRENT_STATE.md +++ b/Codex/Portal/CURRENT_STATE.md @@ -1,140 +1,93 @@ # Portal - Current State -Verified against the current Portal repo after the dashboard/nav cleanup pass, fresh API and Agent repo review, server status/host lifecycle/IDE UX pass, public marketing/SEO refresh, mobile responsiveness pass, server create/delete/status follow-up fixes, and the API control-plane hardening review. - -This file records what is implemented now. +This file records what is believed to be implemented now in `zpack-portal`. ## Runtime / tooling baseline - Portal is aligned to the Node 24 runtime line used by the API repo. -- Current `package.json` pins `engines.node` to `24.14.1`. -- Current `package.json` uses `next@16.2.4`, React 18.2, TypeScript 5, Tailwind 3.4, ESLint 9, and `eslint-config-next@16.2.4`. -- Lint no longer relies on removed `next lint`; the repo uses `eslint .` with the Next 16 flat-config path. -- The lint configuration has been adjusted so current project patterns lint cleanly without forcing a broad React-compiler-style refactor. -- `npm run lint` has previously been reported passing with only existing React hook dependency warnings. -- `npm run build` has previously been reported passing on Next 16.2.4 with Turbopack. -- npm audit has previously been reported clean at moderate-or-higher severity. - -## Repo cleanup already done -- Confirmed-unused HUD wrapper components have been removed. -- Stale `src/styles.old/*` legacy CSS has been removed. -- Unused `js-cookie` type shim has been removed. -- Unused dependencies and Tailwind plugins have reportedly been pruned from the Portal repo. -- The Portal cleanup pass reports net line-count reduction rather than growth. -- Current root listing no longer shows the previously suspected stray root binary `testdameon`. +- Current `package.json` pins `engines.node` to the Node 24 line. +- Portal uses Next 16, React 18, TypeScript, Tailwind, Axios, and WebSocket console. +- Lint/build have been reported passing after the recent async create/support/billing validation work, with only existing unrelated warnings where noted. ## Public marketing / SEO site -- Public marketing now follows a hybrid SaaS structure: - - homepage acts as the conversion flow +- Public marketing follows a hybrid SaaS structure: + - homepage acts as conversion flow - separate pages support deeper product/SEO intent -- Homepage now includes: - - hero with platform-neutral copy: `Code, test, and run servers from your browser.` - - browser/dev + managed server subheadline - - product-style visual panel - - Build / Test / Ship workflow - - differentiators - - use cases - - SEO topic links - - pricing preview - - FAQ preview - - final CTA -- Root metadata has been updated from the old game-hosting-only description to browser dev environments + managed server hosting positioning. -- Pricing has been repositioned from `Vanilla / Modded / Heavy` to workload tiers: - - Starter - - Pro - - Performance -- Pricing copy now states that every plan includes a browser-based dev environment and managed server hosting. -- Public feature copy now presents the platform as build/test/run rather than Minecraft-only hosting. -- LXC/system-container differentiator is represented carefully as avoiding Docker-style game-server overhead without unsupported benchmark claims. -- The fake `zlh build --target server` hero command was removed and replaced with a real/plausible `$ npm run build` line. -- Public SEO/intent pages exist: - - `/minecraft-server-hosting` - - `/modded-minecraft-hosting` - - `/browser-dev-environment` -- Metadata has been added or refreshed for Home, Features, Pricing, FAQ, About, Support, and the three SEO landing pages. -- FAQ has been expanded around platform positioning, dev environments, Minecraft, mods, datapacks, local install expectations, backups/restores, and plan limits. -- Build and lint were previously reported passing after the marketing/SEO changes with the same existing unrelated warnings. +- Homepage and public copy position ZeroLagHub as browser dev environments plus managed server hosting, not Minecraft-only hosting. +- Pricing is positioned as Starter / Pro / Performance workload tiers. +- SEO/intent pages exist for Minecraft hosting, modded Minecraft hosting, and browser dev environments. +- LXC/system-container differentiator is represented carefully without unsupported Minecraft performance claims. +- Mobile responsiveness has had a targeted pass; complex console/file/backup panels are basic-mobile-usable rather than full mobile-native experiences. -## Current mobile status -- A targeted mobile responsiveness pass has been applied across public marketing, SEO landing pages, auth pages, server list, server create, and basic console/file/backup surfaces. -- Public nav now uses a working mobile menu and hides the desktop nav until the larger breakpoint. -- CTA groups, pricing cards, auth forms, server cards, and dashboard shell spacing have been adjusted with responsive Tailwind utilities. -- Complex console/file/backup panels are considered basic-mobile-usable rather than full mobile-native experiences. -- Remaining mobile work should be validation/polish only unless new breakage is observed. +## Server create / async provisioning UI +- Portal treats `POST /api/instances` returning `202 Accepted` as successful accepted creation. +- Create requests send a per-click `Idempotency-Key`. +- Portal stores `operationId`, `requestId`, `statusUrl`, status, phase, and eventual `serverId` in pending creation records. +- `/servers` polls the operation `statusUrl` while keeping existing server-list polling. +- Pending creation UI appears as an inline server card under the correct `GAME` or `DEV` section. +- Pending card states include `Request sent`, `Queued`, `Running: `, `Waiting for server record`, `Ready`, and failed phase/error states. +- When `serverId` appears or the operation completes, Portal refreshes the server list and replaces the placeholder with the real server card. +- This visually validated the previous multi-create/modal-overlap issue; async inline cards are now the launch model. ## Readiness / operation UI - Portal consumes API-normalized state. -- Portal understands: - - `ready` - - `operationInProgress` - - `operationType` - - `maintenance` - - `operationStartedAt` - - `operationMessage` -- targeted `409` and `503` UX messaging exists for operation conflicts and not-ready states. -- server card and game console readiness labels now share explicit mapping for ready, stopped, starting, stopping, restarting, maintenance, provisioning/network-pending, plan-limit, and true error states. -- `connectable === false` no longer automatically maps to `Needs attention`; expected non-connectable states such as stopped servers, host lifecycle actions, backup/restore maintenance, and provisioning use specific user-facing labels. -- game server readiness and dev container readiness are separated in the server list so DEV cards use host/agent/IDE state instead of game `connectable` semantics. -- host/container lifecycle status is surfaced from the LXC host layer, including `Online`, `Offline`, `Starting`, `Stopping`, and `Restarting`, plus active host-operation polling. -- server list refresh waits for per-server status enrichment before committing the merged state, preventing transient IDE/readiness badge flips during polling or page remount. -- server creation now records a pending setup marker and returns the user to `/servers` immediately after submit while the create request completes in the background. -- setup progress can be matched by pending name/type before the API returns a VMID, then by VMID once creation finishes. -- setup-step labels are state-aware; stopping or stopped hosts no longer appear as `installing`/`creating` simply because the host is offline. -- the previous maximum-update-depth loop in server-list creation progress hydration has been fixed by removing state values that were being changed from the polling effect dependency path. +- Portal understands readiness and operation fields such as `ready`, `operationInProgress`, `operationType`, `maintenance`, `operationStartedAt`, and `operationMessage`. +- Targeted `409` and `503` UX messaging exists for operation conflicts and not-ready states. +- Server card and game console readiness labels map ready, stopped, starting, stopping, restarting, maintenance, provisioning/network-pending, plan-limit, billing states, and true error states to explicit user-facing labels. +- `connectable === false` no longer automatically maps to `Needs attention`. +- Game server readiness and dev container readiness are separated in the server list. +- Host/container lifecycle status is surfaced from the LXC host layer, including active host-operation polling. +- Server list refresh waits for per-server status enrichment before committing merged state, preventing transient readiness/IDE badge flips. -## Metrics UI -- server console metrics continue to poll the API metrics summary route for both DEV and GAME servers. -- Portal normalizes multiple CPU, memory, disk, and network field shapes so API casing/name drift does not leave CPU or network stuck at zero. -- metrics polling sends no-cache headers and a cache-busting query value to avoid stale summary responses. -- if CPU/network still do not move for running servers, the remaining likely cause is API/agent metrics collection or rate calculation rather than Portal rendering. +## Billing / announcements +- Billing state/customer messaging is handled through the announcements system for launch. +- Portal billing suspension announcement was visually validated. +- Authenticated `/api/announcements` can surface billing suspension/status messaging for the affected user. +- Dedicated billing UI panels remain a later enhancement unless announcements prove insufficient. +- Portal must still handle stable billing error codes from API actions, including `BILLING_SUSPENDED`, `BILLING_BACKUP_BLOCKED`, `BILLING_PAYMENT_REQUIRED`, and related retained/past-due states. + +## Support +- The authenticated support surface posts to `/api/support/create`. +- Portal support form submit was validated live after the API support route was added. +- Portal shows success state after valid support ticket submit. +- Customer acknowledgement email and Discord `#support` alert were validated outside Portal. +- Support admin ticket view, support triage diagnostics, attachments, inbound reply parsing, and self-hosted helpdesk integration are post-launch enhancements. ## Backup UI -- game backup UI exists for: - - list - - create - - restore - - delete +- Game backup UI exists for list, create, restore, and delete. - Portal uses API routes, not direct agent calls. -- backup metadata is normalized and displayed when the API includes metadata fields. -- backup/restore actions now provide user feedback and progress/elapsed time during active operations. +- Backup metadata is normalized and displayed when API includes metadata fields. +- Backup/restore actions provide user feedback and progress/elapsed time during active operations. +- Restore start is async at the API layer and Portal should treat accepted restore as success then poll status. +- Live backup-route validation with a current game backup fixture remains a launch validation follow-up. ## Console / action gating -- console command transport uses POST JSON through API. -- previous blanket `ready === false` gating bug for game actions was fixed. +- Console command transport uses POST JSON through API. +- Previous blanket `ready === false` gating bug for game actions was fixed. - Start is not blocked merely because a stopped server is not ready. -- backup actions are not blocked purely by `ready === false`; backend validity decides. - -## Billing / auth / onboarding -- billing UI alignment exists with the newer billing state model. -- billing plan-limit gating has been observed in Portal create flow. -- forgot/reset password flow exists. -- logged-in change-password flow exists. -- first-login onboarding flow exists. -- Next 16 / current TypeScript cleanup included fixes around nullable normalization and search-param/Suspense usage in affected pages/components. +- Backup actions are not blocked purely by `ready === false`; backend validity decides. +- Terminal reliability hardening remains open: WebSocket connect timeout, error cleanup, streaming state reset, and recoverable `Connecting...` button state. ## Hosted IDE -- console and server-list `Open IDE` actions request `/api/dev/{serverId}/ide-token`. -- Portal opens the hosted URL returned by the API, falling back to the configured API base for relative URLs. -- DEV server console and server-list rows show compact IDE indicators and inline `Open`, `Start`, `Restart`, and `Stop` controls instead of large stacked action blocks. -- code-server service actions call `/api/dev/{serverId}/codeserver/start`, `/api/dev/{serverId}/codeserver/restart`, and `/api/dev/{serverId}/codeserver/stop`. -- Portal preserves last-known IDE state when a polling response omits code-server fields, avoiding UI blips between list and status responses. -- API owns the IDE bootstrap, hosted proxy, and tunnel flow. Portal is not expected to proxy IDE traffic itself. +- Console and server-list `Open IDE` actions request `/api/dev/{serverId}/ide-token`. +- Portal opens the hosted URL returned by API, falling back to configured API base for relative URLs. +- DEV cards show compact IDE indicators and inline Open/Start/Restart/Stop controls. +- code-server service actions call `/api/dev/{serverId}/codeserver/start`, `/restart`, and `/stop`. +- Hosted IDE access was validated during recent dev provisioning tests. ## API client layer - Portal uses API-mediated transport rather than direct agent calls. -- the old Portal-internal `/api/agent/{serverId}/{action}` bridge has been removed from the frontend repo. -- server deletion has been migrated from `DELETE /api/containers/{vmid}` to `DELETE /api/servers/{id}` through the normal user JWT API client. +- The old Portal-internal `/api/agent/{serverId}/{action}` bridge has been removed from the frontend repo. +- Server deletion has migrated to `DELETE /api/servers/{id}` through the normal user JWT API client. - Portal does not add or expose `INTERNAL_API_TOKEN` in browser code. -- delete UX maps API responses explicitly: `202` as already in progress, `401` as login required, `404` as not owned/missing, `409` as `Stop host before deleting`, and `500` as teardown failure. -- Current browser-side API helpers still include `listAuditLogs()` and `listInstances()`; these must be treated as admin/internal-sensitive surfaces until usage is audited against the API route boundary. -- `src/lib/api/legacy.ts` still contains legacy/Pterodactyl-era helper exports and TODOs; keep them quarantined and remove only after confirming there are no live imports. -- Project cleanup has removed dead weight around unused wrappers/dependencies, but API-client/status-polling consolidation is not yet considered fully complete. +- Delete UX maps API responses explicitly: accepted/already-in-progress, login required, not owned/missing, stop-host-before-deleting, and teardown failure. +- Browser-side API helpers for admin/internal-sensitive surfaces must remain audited and not accidentally reachable from normal user UI. ## Dashboard / IA -- the dashboard spotlight server card now uses API-backed server data instead of placeholder entries. -- the spotlight card no longer links to a non-existent `/servers/{id}` route; it routes users back into the supported `/servers` surface. -- the spotlight card now recognizes DEV containers across API field aliases and mirrors server-list badges, including the IDE indicator, readiness badge, and host status. -- hub navigation now includes Billing and Profile so onboarding tour targets match the actual menu. -- the hub shell now covers authenticated account/control-surface pages including billing, profile, and support instead of only dashboard/servers. +- Dashboard spotlight server card uses API-backed server data instead of placeholder entries. +- Spotlight card routes users into supported `/servers` surface. +- Spotlight card recognizes DEV containers and mirrors server-list badges, including IDE indicator, readiness badge, and host status. +- Hub navigation includes Billing, Profile, and Support. +- Hub shell covers authenticated account/control-surface pages including billing, profile, and support. ## Still true - Portal should track API auth / JWT behavior closely because API-side token hardening can require Portal compatibility verification.