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