From dbb9cad01ed8f7eea64bc22a1ac0efa682b64ed8 Mon Sep 17 00:00:00 2001
From: simoleo89 <simoleo89@gmail.com>
Date: Sun, 12 Jul 2026 20:00:46 +0200
Subject: [PATCH] docs: plan admin operations port

---
 .../plans/2026-07-12-admin-operations.md      | 86 +++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-12-admin-operations.md

diff --git a/docs/superpowers/plans/2026-07-12-admin-operations.md b/docs/superpowers/plans/2026-07-12-admin-operations.md
new file mode 100644
index 00000000..13bd2260
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-12-admin-operations.md
@@ -0,0 +1,86 @@
+# 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.