# 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.