From 63ab21616c74db2189b6c93f1ffd26f63bfa160f Mon Sep 17 00:00:00 2001 From: simoleo89 Date: Sun, 12 Jul 2026 19:00:47 +0200 Subject: [PATCH] docs: define acl and import backend work --- .../plans/2026-07-12-acl-import-backend.md | 94 +++++++++++++++++++ .../2026-07-12-acl-import-backend-design.md | 33 +++++++ 2 files changed, 127 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-12-acl-import-backend.md create mode 100644 docs/superpowers/specs/2026-07-12-acl-import-backend-design.md diff --git a/docs/superpowers/plans/2026-07-12-acl-import-backend.md b/docs/superpowers/plans/2026-07-12-acl-import-backend.md new file mode 100644 index 00000000..5fa8d482 --- /dev/null +++ b/docs/superpowers/plans/2026-07-12-acl-import-backend.md @@ -0,0 +1,94 @@ +# ACL and Import Backend 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:** Complete ACL management and activate every existing administration import workflow. + +**Architecture:** Use the normalized ACL tables as the single authorization source and map emulator ranks to `rank_` roles. Port the proven import core and services from `habbo-next`, expose them through locale-free API routes guarded server-side, and verify DB plus filesystem outputs. + +**Tech Stack:** Next.js 16 route handlers, React 19, TypeScript, Prisma/MariaDB, Vitest, Node filesystem and streams. + +## Global Constraints + +- Work directly in `E:\Users\simol\Desktop\EpicNext-cms`; no worktree or subagents. +- Preserve and never stage the existing `package.json` modification. +- Pull `main` before publication and never force-push. +- Do not copy generated Prisma files. +- Every import API requires `admin.assets.import`; destructive catalog operations also require `admin.catalog.edit`. +- Import success requires database and required filesystem/FurnitureData outputs. + +--- + +### Task 1: Lock ACL and route coverage with failing contracts + +**Files:** +- Create: `src/lib/admin/acl-management-contract.test.ts` +- Create: `src/lib/import-backend-contract.test.ts` + +- [ ] Assert that permission mutations use `adminAction` with `PERMS.PERMISSIONS_MANAGE`, write normalized ACL tables, and do not write legacy housekeeping permission tables. +- [ ] Assert that every API referenced by `src/app/admin/import/**` exists and contains a server-side `PERMS.ASSETS_IMPORT` guard. +- [ ] Run both tests and verify they fail on the missing management/API implementation. +- [ ] Commit with `test: define acl and import backend contracts`. + +### Task 2: Normalize ACL persistence and management + +**Files:** +- Modify: `src/actions/permissions.ts` +- Modify: `src/app/admin/permissions/page.tsx` +- Modify: `src/app/admin/permissions/[id]/page.tsx` +- Modify: `src/app/admin/permissions/[id]/rank-edit-client.tsx` +- Use: `src/lib/services/permission-ranks.ts` +- Create: `prisma/migrations/0014_complete_acl_and_import_permissions.sql` + +- [ ] Add focused failing tests for rank service and ACL assignment behavior. +- [ ] Replace legacy writes with emulator rank service and normalized ACL assignments. +- [ ] Seed and migrate roles/permissions idempotently, using `Role` and `User` discriminator casing. +- [ ] Invalidate permission cache, update RCON, and log each mutation. +- [ ] Run ACL tests and migration contract tests; commit with `fix: complete acl management`. + +### Task 3: Port shared import core and domain services + +**Files:** +- Create: `src/lib/services/import/core/*.ts` +- Create: `src/lib/services/{clone-import,clothing-set-import,effect-import,figure-import,furni-import,nitro-assets,pet-import}.ts` +- Modify: `src/lib/services/furni-asset-dirs.ts` +- Modify: `src/lib/services/furni-data.ts` +- Test: matching `*.test.ts` files + +- [ ] Port tests first and verify failures from missing modules. +- [ ] Port reference implementations, adapting Prisma model names and EpicNext settings. +- [ ] Preserve Windows absolute-path handling and live Nitro mirroring. +- [ ] Run all import service tests; commit with `feat: add asset import services`. + +### Task 4: Add guarded import route handlers + +**Files:** +- Create: `src/app/api/admin/import/**/route.ts` +- Create: `src/app/api/nitro-assets/bundled/furniture/[...path]/route.ts` + +- [ ] Add badge, clone, clothing, effects, furni, pets, and repair handlers used by the existing clients. +- [ ] Apply server-side API context plus `PERMS.ASSETS_IMPORT` to every handler. +- [ ] Require `PERMS.CATALOG_EDIT` for deletion, repair, resync, and catalog-mutating operations. +- [ ] Run route contract, API authorization, and service tests; commit with `feat: add guarded asset import api`. + +### Task 5: Align pages, actions, and permissions + +**Files:** +- Modify: `src/app/admin/import/**/page.tsx` +- Modify: `src/actions/import-badges.ts` +- Modify: `src/actions/import-furni.ts` +- Modify: `src/lib/permission-slugs.ts` + +- [ ] Make every import page use `PERMS.ASSETS_IMPORT` consistently. +- [ ] Replace stub cleanup/deletion behavior with guarded service calls. +- [ ] Run contract tests and TypeScript; commit with `fix: connect admin import workflows`. + +### Task 6: Complete verification and publish + +**Files:** +- Verify all committed files; exclude `package.json`. + +- [ ] Run `git diff --check origin/main...HEAD`. +- [ ] Run `pnpm test`, `pnpm typecheck`, and `pnpm build`. +- [ ] Confirm `git status --short` contains only ` M package.json`. +- [ ] Fetch `origin/main`, require it to be an ancestor of `HEAD`, and push `main` without force. diff --git a/docs/superpowers/specs/2026-07-12-acl-import-backend-design.md b/docs/superpowers/specs/2026-07-12-acl-import-backend-design.md new file mode 100644 index 00000000..8b177f95 --- /dev/null +++ b/docs/superpowers/specs/2026-07-12-acl-import-backend-design.md @@ -0,0 +1,33 @@ +# ACL and import backend design + +## Goal + +Complete the administration ACL management and make every existing asset-import page functional end to end. + +## ACL architecture + +`acl_permissions`, `acl_roles`, `acl_model_permissions`, and `acl_model_roles` are the only CMS authorization source. Emulator ranks remain in `permission_ranks`; each rank maps to the CMS role `rank_`. Legacy `website_permissions` and `website_housekeeping_permissions` may be migrated but are not written by the new management flow. + +The permissions screen manages emulator ranks, rank roles, role permission assignments, and direct user roles/permissions. Rank creation, editing, and deletion use the emulator rank service, refresh RCON permissions, invalidate the permission cache, and log staff activity. Every mutation requires `admin.permissions.manage` and fails closed. + +## Import authorization + +All import pages and every `/api/admin/import/**` handler require `admin.assets.import`. Catalog deletion or repair operations that mutate catalog data additionally require `admin.catalog.edit`. Page-level checks are navigation guards only; API handlers repeat authorization before reading remote sources, writing the database, or writing files. + +## Import pipeline + +Port the reference import core, services, API routes, and tests for badges, clone, clothing, effects, furni, pets, and repair. Adapt imports to EpicNext's generated Prisma names and locale-free routes. Do not copy generated Prisma files. + +The furni success boundary is atomic at the workflow level: verify database rows, repository asset output, configured live Nitro asset output, and `FurnitureData.json`. External Windows paths use the existing cross-platform resolver. Repair/audit reports partial state instead of treating a database insert as success. + +## Migration + +Add an idempotent migration that seeds `admin.assets.import`, normalizes ACL discriminator casing to `Role` and `User`, creates missing `rank_` roles, migrates compatible legacy permission assignments, and grants the highest rank explicit management/import permissions. Dynamic highest-rank bypass remains an emergency compatibility path, not the persisted assignment model. + +## Error handling and verification + +Remote download errors, invalid archives/data, filesystem failures, schema mismatches, and partial writes return structured errors and are logged without exposing secrets. Contract tests assert route coverage and server-side ACL guards. Service tests cover path resolution, batch behavior, data reconciliation, and fail-closed authorization. Final verification runs all tests, TypeScript, and the production build. + +## Scope boundary + +This block does not add moderation, analytics, detailed logs, or DevOps pages. Those remain the next phase after ACL and imports are verified.