@core / admin

1.0.0 ▾

1.0.0

인증됨MIT

GitHub

AdminResource로 생성되는 관리자 패널: 목록, 폼, 액션, 대시보드, RBAC, CSRF 방지, 감사 로그

코드파일 12개컨텍스트약 849토큰검사 통과

약 849토큰→ src/lib/admin/AGENTS.md→ .cursor/rules/genpm-core-admin.mdc

이것이 AI가 src/lib/admin에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/admin — rules for AI agents

Purpose

Admin panel generated from AdminResource descriptions (from @core/contracts): navigation, dashboard widgets, searchable/sortable lists, create/edit forms, record actions with confirmation, and delete. No per-resource screens: any module that exports an AdminResource appears in the panel. Server side: session from @core/auth, permissions from @core/rbac (admin:access + <resource>:<action>), CSRF protection on writes and an audit log of every change. Table: admin_audit.

Map

index.ts — server API: defineAdmin, handleAdminApi, adminContextFor, listAudit, auditAdminResource, countWidget, listWidget, fieldsFromZod.
client.ts — 'use client': AdminApp, createAdminApi, FieldControl, defaultLabels, renderer types.
admin.css — layout on @core/ui tokens. constants.ts — ADMIN_HEADER (shared by server and client).
adapters/hono.ts — adminRoutes(admin). adapters/next.ts — adminRouteHandlers(admin).

Integration

Install @core/auth, @core/rbac and @core/ui first; run migrations as in src/lib/db/AGENTS.md (admin_audit).

Create src/genpm/admin.ts:

import { defineAdmin, auditAdminResource } from '@/lib/admin';
import { mediaAdminResource } from '@/lib/media';
export const admin = defineAdmin({ title: 'My site', resources: [mediaAdminResource, auditAdminResource], widgets: [] });

Every installed module's AGENTS.md says which resources to add here.

API route. Next: app/api/admin/[...path]/route.ts → export const { GET, POST, PUT, DELETE } = adminRouteHandlers(admin); export const dynamic = 'force-dynamic'; Hono: app.route('/api/admin', adminRoutes(admin)).
Page. Next: app/admin/[[...path]]/page.tsx renders a client component that imports ../lib/ui/ui.css, ../lib/admin/admin.css and returns <AdminApp basePath="/admin" path={(await params).path?.join('/') ?? ''} />. Protect the page itself too (redirect to sign-in when there is no session) and add robots: { index: false }.
Rich text, media pickers or blocks: pass renderers={{ richText: MyEditorField, media: MyMediaPicker }}. Without them those fields fall back to a JSON textarea / relation select.
Translate the UI with labels={{ save: t('admin.save'), … }} (keys: defaultLabels).
Verify: a user without admin:access gets 403 on /api/admin/schema; an editor sees only their resources; an edit creates a row in admin_audit with before/after.

Conventions

Resources enforce permissions themselves (ctx.can(...)); the panel hides what the user cannot do but the server never trusts that. Use <resource>:<action>:own for author-only rules.
Field names may be nested (data.title); read-only fields are shown but never sent.
Money fields hold integer minor units (or { amount, currency }); the form edits decimals.
Actions that change state declare available(row) so the panel only offers them when valid.

Don't

Don't call the admin API from other origins or without the x-admin-request: 1 header (requests are rejected).
Don't write per-resource admin pages; extend the AdminResource or add a field renderer instead.
Don't put secrets or full payment data in resource rows: the audit log stores before/after snapshots.
Don't expose /admin in the sitemap or let it be indexed.

# @core/admin — rules for AI agents

## Purpose
Admin panel generated from `AdminResource` descriptions (from @core/contracts): navigation, dashboard widgets,
searchable/sortable lists, create/edit forms, record actions with confirmation, and delete. No per-resource screens:
any module that exports an `AdminResource` appears in the panel. Server side: session from @core/auth, permissions
from @core/rbac (`admin:access` + `<resource>:<action>`), CSRF protection on writes and an audit log of every change.
Table: `admin_audit`.

## Map
- `index.ts` — server API: `defineAdmin`, `handleAdminApi`, `adminContextFor`, `listAudit`, `auditAdminResource`, `countWidget`, `listWidget`, `fieldsFromZod`.
- `client.ts` — `'use client'`: `AdminApp`, `createAdminApi`, `FieldControl`, `defaultLabels`, renderer types.
- `admin.css` — layout on @core/ui tokens. `constants.ts` — `ADMIN_HEADER` (shared by server and client).
- `adapters/hono.ts` — `adminRoutes(admin)`. `adapters/next.ts` — `adminRouteHandlers(admin)`.

## Integration
1. Install @core/auth, @core/rbac and @core/ui first; run migrations as in `src/lib/db/AGENTS.md` (`admin_audit`).
2. Create `src/genpm/admin.ts`:
   ```ts
   import { defineAdmin, auditAdminResource } from '@/lib/admin';
   import { mediaAdminResource } from '@/lib/media';
   export const admin = defineAdmin({ title: 'My site', resources: [mediaAdminResource, auditAdminResource], widgets: [] });
   ```
   Every installed module's `AGENTS.md` says which resources to add here.
3. API route. Next: `app/api/admin/[...path]/route.ts` →
   `export const { GET, POST, PUT, DELETE } = adminRouteHandlers(admin); export const dynamic = 'force-dynamic';`
   Hono: `app.route('/api/admin', adminRoutes(admin))`.
4. Page. Next: `app/admin/[[...path]]/page.tsx` renders a client component that imports `../lib/ui/ui.css`,
   `../lib/admin/admin.css` and returns `<AdminApp basePath="/admin" path={(await params).path?.join('/') ?? ''} />`.
   Protect the page itself too (redirect to sign-in when there is no session) and add `robots: { index: false }`.
5. Rich text, media pickers or blocks: pass `renderers={{ richText: MyEditorField, media: MyMediaPicker }}`.
   Without them those fields fall back to a JSON textarea / relation select.
6. Translate the UI with `labels={{ save: t('admin.save'), … }}` (keys: `defaultLabels`).
7. Verify: a user without `admin:access` gets 403 on `/api/admin/schema`; an editor sees only their resources; an edit
   creates a row in `admin_audit` with before/after.

## Conventions
- Resources enforce permissions themselves (`ctx.can(...)`); the panel hides what the user cannot do but the server
  never trusts that. Use `<resource>:<action>:own` for author-only rules.
- Field names may be nested (`data.title`); read-only fields are shown but never sent.
- Money fields hold integer minor units (or `{ amount, currency }`); the form edits decimals.
- Actions that change state declare `available(row)` so the panel only offers them when valid.

## Don't
- Don't call the admin API from other origins or without the `x-admin-request: 1` header (requests are rejected).
- Don't write per-resource admin pages; extend the `AdminResource` or add a field renderer instead.
- Don't put secrets or full payment data in resource rows: the audit log stores before/after snapshots.
- Don't expose `/admin` in the sitemap or let it be indexed.

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/admin/LICENSE읽기 전용 · 3b5bae0

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.