EpicNext-Cms/docs/superpowers/plans/2026-07-12-acl-import-backend.md

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_<id> 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.