zlh-grind/Codex/Portal/CURRENT_STATE.md

Portal — Current State

Verified against local Portal repo plus the reported Node 24 / Next 16 cleanup pass.

This file records what is implemented now.

Runtime / tooling baseline

• Portal is now aligned to the Node 24 runtime line used by the API repo.
• .nvmrc, package.json engines, and package-lock.json are expected to be synchronized on the current Node 24 baseline.
• 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 reportedly passes with only existing React hook dependency warnings.
• npm run build reportedly passes on Next 16.2.4 with Turbopack.
• npm audit is 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.

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.

Backup UI

• game backup UI exists for:
  • list
  • create
  • restore
  • delete
• Portal uses API routes, not direct agent calls.
• backup metadata is normalized and displayed when the API includes metadata fields.

Console / action gating

• 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.
• profile save now sends the backend-supported account fields to authenticated PATCH /api/auth/me:
  • email normalized to lowercase after trim
  • username trimmed
  • firstName, lastName, and displayName trimmed
  • 409 responses surface a duplicate email/username message
• forgot/reset password flow exists:
  • login includes a Forgot password? link to /forgot-password
  • /forgot-password posts { email } to POST /api/auth/password-reset/request
  • the Portal always shows If the account exists, a reset link has been sent. for account-lookup-style responses
  • /reset-password?token=... reads token from query params, trims it, and requires it to be a 64-character hex token before submit
  • valid reset submissions post { token, password } to POST /api/auth/password-reset/confirm
  • client validation requires an 8+ character password and confirmation match
  • missing, malformed, invalid, or expired reset tokens show This reset link is invalid or has expired.
  • successful reset does not auto-login; Portal leaves the user with login navigation
• profile change-password UI exists:
  • profile includes current password, new password, and confirm new password fields
  • client validation requires an 8+ character new password and matching confirmation
  • submit uses authenticated POST /api/auth/change-password with { currentPassword, newPassword }
  • successful change clears the password fields and reports success without changing login/session state
• first-login onboarding flow exists.
• Next 16 / current TypeScript cleanup included fixes around nullable normalization and search-param/Suspense usage in affected pages/components.

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 code-server start, restart, and stop controls directly under the Open IDE button.
• code-server service actions call /api/dev/{serverId}/codeserver/start, /api/dev/{serverId}/codeserver/restart, and /api/dev/{serverId}/codeserver/stop.

API client layer

• Portal still uses API-mediated transport rather than direct agent calls.
• Project cleanup has reportedly removed dead weight around unused wrappers/dependencies, but API-client/status-polling consolidation is not yet considered fully complete.

Dashboard / IA

• spotlight server card/dashboard refresh landed.

Still true

• Portal should track API auth / JWT behavior closely because API-side token hardening can require Portal compatibility verification.
• Portal cleanup should remain behavior-preserving; build/lint green status is part of the current baseline.