@core / comments

1.0.1 ▾

1.0.1

verificadoMIT

GitHub

Comentários moderados em qualquer entidade: visitante ou usuário, respostas, nota 1–5, bloqueios, LGPD e HTML seguro

Código9 arquivosContexto~552 tokensanálise aprovada

~552 tokens→ src/lib/comments/AGENTS.md→ .cursor/rules/genpm-core-comments.mdc

Isto é exatamente o que sua IA lê quando trabalha em src/lib/comments. Nada mais é adicionado ao contexto dela.

@core/comments — rules for AI agents

Purpose

Comments on anything (entityType + entityId: posts, products, pages): guests (name + email, stored only as a hash) or signed-in users, one level of replies, optional 1–5 rating (reused by @core/reviews), moderation queue with email alerts, bans, GDPR erasure and safe HTML rendering. Anti-spam via @core/antispam. Tables: comments, comment_bans.

Map

index.ts — public API: postComment, listComments, moderate, ban, eraseComments, ratingSummary, commentHtml, commentsAdminResource.
comments.ts — logic and the comments.notify job. admin.ts — moderation queue. schema.ts — tables.
adapters/hono.ts — commentRoutes({ currentUser }). adapters/next.ts — commentRoute({ currentUser }) → { GET, POST }.

Integration

Env: optional COMMENTS_NOTIFY_TO (moderators, comma-separated) and EMAIL_FROM. Migrations as in src/lib/db/AGENTS.md; the @core/jobs cron must run.
Mount the endpoints at /api/comments/:type/:id with currentUser from @core/auth (getUser/getUserFromCookieHeader).
The form posts body (and name, email for guests, parentId for replies) plus the @core/antispam fields (honeypotProps, _ts). Show "your comment awaits moderation" when the response status is pending.
Render the list from GET or listComments(type, id); render each body with commentHtml(body) (escaped; the only HTML allowed).
Add commentsAdminResource to src/genpm/admin.ts (permissions comments:read, comments:moderate).
Verify: a guest comment is pending until approved in the admin, then it is listed.

Conventions

Default moderation is guests: guests and users without an approved comment wait for approval. Use none only on trusted, private sites.
Erase on request with eraseComments({ email }) or ({ userId }); delete user comments when the account is deleted.
Show ratings only from ratingSummary (approved comments).

Don't

Don't store or show guest emails; don't render comment bodies as Markdown/HTML.
Don't auto-approve guests to "increase engagement".
Don't expose pending, spam or deleted comments in public endpoints.

# @core/comments — rules for AI agents

## Purpose
Comments on anything (`entityType` + `entityId`: posts, products, pages): guests (name + email, stored only as a hash)
or signed-in users, one level of replies, optional 1–5 rating (reused by @core/reviews), moderation queue with email
alerts, bans, GDPR erasure and safe HTML rendering. Anti-spam via @core/antispam. Tables: `comments`, `comment_bans`.

## Map
- `index.ts` — public API: `postComment`, `listComments`, `moderate`, `ban`, `eraseComments`, `ratingSummary`, `commentHtml`, `commentsAdminResource`.
- `comments.ts` — logic and the `comments.notify` job. `admin.ts` — moderation queue. `schema.ts` — tables.
- `adapters/hono.ts` — `commentRoutes({ currentUser })`. `adapters/next.ts` — `commentRoute({ currentUser })` → `{ GET, POST }`.

## Integration
1. Env: optional `COMMENTS_NOTIFY_TO` (moderators, comma-separated) and `EMAIL_FROM`. Migrations as in `src/lib/db/AGENTS.md`; the @core/jobs cron must run.
2. Mount the endpoints at `/api/comments/:type/:id` with `currentUser` from @core/auth (`getUser`/`getUserFromCookieHeader`).
3. The form posts `body` (and `name`, `email` for guests, `parentId` for replies) plus the @core/antispam fields (`honeypotProps`, `_ts`).
   Show "your comment awaits moderation" when the response status is `pending`.
4. Render the list from `GET` or `listComments(type, id)`; render each body with `commentHtml(body)` (escaped; the only HTML allowed).
5. Add `commentsAdminResource` to `src/genpm/admin.ts` (permissions `comments:read`, `comments:moderate`).
6. Verify: a guest comment is pending until approved in the admin, then it is listed.

## Conventions
- Default moderation is `guests`: guests and users without an approved comment wait for approval. Use `none` only on trusted, private sites.
- Erase on request with `eraseComments({ email })` or `({ userId })`; delete user comments when the account is deleted.
- Show ratings only from `ratingSummary` (approved comments).

## Don't
- Don't store or show guest emails; don't render comment bodies as Markdown/HTML.
- Don't auto-approve guests to "increase engagement".
- Don't expose `pending`, `spam` or `deleted` comments in public endpoints.

A árvore exata que será injetada, após o .genpmignore. Fixada em

src/lib/comments/schema.tssomente leitura · abfbbe8

// Tablas de @core/comments. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { index, integer, pgTable, text, uniqueIndex } from 'drizzle-orm/pg-core';
import { users } from '../auth/index.ts';
import { primaryId, timestamps } from '../db/index.ts';

export const comments = pgTable(
  'comments',
  {
    id: primaryId('cmt'),
    /** A qué se comenta: `post`, `product`, `page`… y su id. */
    entityType: text('entity_type').notNull(),
    entityId: text('entity_id').notNull(),
    /** Respuesta a otro comentario (un solo nivel). */
    parentId: text('parent_id'),
    authorId: text('author_id').references(() => users.id, { onDelete: 'set null' }),
    /** Nombre visible (de la cuenta o del invitado). */
    authorName: text('author_name').notNull(),
    /** SHA-256 del email del invitado normalizado (para bajas RGPD y bloqueos); nunca el email en claro. */
    guestEmailHash: text('guest_email_hash'),
    body: text('body').notNull(),
    /** Valoración 1–5 opcional (la usan las reseñas). */
    rating: integer('rating'),
    status: text('status', { enum: ['pending', 'approved', 'spam', 'deleted'] })
      .notNull()
      .default('pending'),
    ...timestamps,
  },
  (t) => [
    index('comments_entity_idx').on(t.entityType, t.entityId, t.status, t.createdAt),
    index('comments_status_idx').on(t.status, t.createdAt),
    index('comments_author_idx').on(t.authorId),
  ],
);

export const commentBans = pgTable(
  'comment_bans',
  {
    id: primaryId('ban'),
    /** `user:<id>` o `email:<sha256>`. */
    subject: text('subject').notNull(),
    reason: text('reason'),
    ...timestamps,
  },
  (t) => [uniqueIndex('comment_bans_subject_idx').on(t.subject)],
);

export type Comment = typeof comments.$inferSelect;