EpicNext-Cms/docs/superpowers/plans/2026-07-12-admin-operations.md

Admin Operations Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add complete moderation, logs, analytics, DevOps, and online-user administration verticals.

Architecture: Port each reference vertical independently, adapt its data access to EpicNext's Prisma/schema conventions, and enforce ACL at both route and mutation boundaries. Reuse shared admin components and semantic admin theme tokens.

Tech Stack: Next.js 16, React 19, TypeScript, Prisma/MariaDB, Vitest, RCON.

Global Constraints

• Work directly on main; no worktree or subagents.
• Preserve and never stage the local package.json change.
• Do not copy generated Prisma code.
• Every page/action/API must use its documented ACL permission.
• Missing optional emulator tables render unavailable states instead of crashing the admin shell.

---

Task 1: Define route, ACL, and theme contracts

Files:

• Create: src/lib/admin-operations-contract.test.ts

• Assert all moderation, log, analytics, DevOps, and online routes exist.

• Assert mutations and APIs contain the matching PERMS guard.

• Assert new sources contain no forbidden public structural theme tokens.

• Run the contract and confirm it fails because routes are absent.

• Commit with test: define admin operations contracts.

Task 2: Moderation and calls for help

Files:

• Create: src/actions/moderation.ts

• Create: src/app/admin/moderation/**

• Modify: src/app/admin/layout.tsx

• Port moderation validation tests and confirm failure.

• Add dashboard, actions, CFH list/detail, and team pages.

• Adapt user/ban/CFH queries and protect reads/edits with moderation ACL.

• Log actions and separate RCON failures from database results.

• Run contract, moderation tests, and typecheck; commit feat: add admin moderation operations.

Task 3: Detailed administration logs

Files:

• Create: src/app/admin/logs/{audit,chat,commands,trades}/**

• Modify: src/app/admin/logs/page.tsx

• Add failing route/filter contract coverage.

• Port paginated read-only tables using EpicNext log models or compatible raw queries.

• Protect every route with admin.logs.view and use semantic admin status colors.

• Run log tests and typecheck; commit feat: add detailed admin logs.

Task 4: Analytics and export

Files:

• Create: src/app/admin/analytics/**

• Create: src/app/api/admin/analytics/export/route.ts

• Add failing ACL/export contract checks.

• Port overview, activity, and economy aggregates.

• Guard reads with admin.analytics.view and export with admin.analytics.export.

• Ensure export excludes secrets and fields absent from the visible tables.

• Run analytics contracts and typecheck; commit feat: add admin analytics.

Task 5: DevOps health and online users

Files:

• Create: src/app/admin/devops/**

• Create: src/app/api/admin/devops/health/route.ts

• Create: src/app/admin/online/**

• Add failing route, redaction, and ACL checks.

• Port health/errors/online pages and adapt queries to EpicNext models.

• Redact credentials, connection strings, environment variables, and stack details from API responses.

• Guard DevOps with admin.devops.view/edit and online users with admin.users.view.

• Run contracts and typecheck; commit feat: add devops and online operations.

Task 6: Verify and publish

• Run git diff --check origin/main...HEAD.
• Run pnpm test, pnpm typecheck, and pnpm build.
• Confirm only package.json remains modified.
• Fetch origin/main, verify it is an ancestor of HEAD, and push main without force.