@core / content

1.1.0 ▾

1.1.0

verifiedMIT

GitHub

Headless CMS core: typed collections and singletons with drafts, revisions, scheduling, locales and preview

Code11 filesContext~1.2K tokensscan passed

~1.2K tokens→ src/lib/content/AGENTS.md→ .cursor/rules/genpm-core-content.mdc

This is exactly what your AI reads when it works in src/lib/content. Nothing else is added to its context.

@core/content — rules for AI agents

Purpose

Content model of the CMS: collections (pages, posts, FAQs) and singletons (home, footer, settings) defined with zod, stored in Postgres with drafts separate from published data, revisions, scheduled publishing (@core/jobs), locales with fallback and signed preview. Implements ContentSource, sitemap/search sources and AdminResource (@core/contracts). No UI: @core/admin renders the editor from contentAdminResource().

Map

index.ts — public API. registry.ts — defineCollection, defineSingleton. entries.ts — create, saveDraft, publish, schedulePublish, unpublish, archive, revisions, seedEntry, migrateEntries.
read.ts — getEntry, listEntries, getSingleton, reader(collection) (typed). preview.ts — preview tokens. listEntries/countEntries also take nested where keys ({ 'series.slug': 'basics' }) and a publishedAt range (publishedFrom inclusive, publishedBefore exclusive): filter in SQL instead of fetching and filtering in memory.
sources.ts — contentSitemapSource, contentSearchSource. admin.ts — contentAdminResource.
adapters/next.ts — previewRoute(draftMode, cookies), exitPreviewRoute(draftMode).

Integration

Env: CONTENT_PREVIEW_SECRET (≥ 32 chars), optional CONTENT_DEFAULT_LOCALE (default en). Migrations as in src/lib/db/AGENTS.md.
Define the site's content in one project file imported everywhere, src/genpm/content.ts: export const pages = defineCollection('pages', { schema: z.object({ title: z.string(), body: z.string() }) }).
Read in pages: const page = await reader(pages).get(slug, { locale, draft: isDraftMode }) (404 if null).
Preview: app/api/preview/route.ts with export const GET = previewRoute(draftMode, cookies) (both from next/headers) and app/api/exit-preview/route.ts with export const GET = exitPreviewRoute(draftMode). Passing cookies makes Next's draft-mode cookie expire with the token (admin links: 600 s); without it, draft mode lasts the whole browser session.
Scheduled publishing needs the @core/jobs cron endpoint running.
Register contentAdminResource('pages') in src/genpm/admin.ts, and the sources in src/genpm/seo.ts / search.ts.
Verify: create, publish, and read an entry; drafts must not appear without draft mode.

Retrofit: make an existing site editable

Work page by page, one commit per page, without changing markup or styles:

List every visible literal (texts, image URLs, links) of the page.
Group them: one singleton per page (home, about). Repeated items of one page (features, prices, FAQs) are a list field inside that singleton (ordered, one edit screen); use a collection only when the items have their own pages or are shared by several pages.
Define the schema with the current values' shape and call seedEntry with the current values (idempotent; it only creates, so it never overwrites editor changes — and a field added later to the seed does not reach an already-seeded database: set it in the admin or with saveDraft + publish), e.g. from a seed script.
Replace literals with typed reads; keep a fallback only where a value is optional.
Render before/after and compare the HTML: it must be identical. Next 15 streams metadata into <body> for browsers once generateMetadata awaits data; htmlLimitedBots: /.*/ in next.config (kit-cms Integration 1) keeps it in <head>.
Grant editors the new singletons: defineRole with <singleton>:* (e.g. home:*, site_settings:*) — the default editor role only covers the kit's collections.

Conventions

Field names in admin resources are data.<field>; slugs are lowercase a-z0-9- with up to 6 / segments.
Changing a schema incompatibly requires migrateEntries; never edit jsonb by hand.
Permissions: <collection>:read|create|update|delete|publish, :own for authors (owner = authorId).
Public reads never pass draft: true unless draft mode came from a verified preview token.
A preview link is not bound to its entry: Next's draft mode is browser-wide, so while it lasts (until the token expires, when cookies is passed) that browser sees the drafts of every entry of every collection. Only share preview links with people who may see unpublished content; /api/exit-preview ends it early.
Admin update renames and saves the draft in one transaction: invalid data never leaves the entry renamed.

Don't

Don't write to content_entries directly; publishing must go through publish() (validation + revision).
Don't put secrets or personal data in content; it is public once published.
Don't redirect previews to absolute URLs; safePath rejects them.

# @core/content — rules for AI agents

## Purpose
Content model of the CMS: collections (pages, posts, FAQs) and singletons (home, footer, settings) defined with zod,
stored in Postgres with drafts separate from published data, revisions, scheduled publishing (@core/jobs), locales
with fallback and signed preview. Implements `ContentSource`, sitemap/search sources and `AdminResource`
(@core/contracts). No UI: @core/admin renders the editor from `contentAdminResource()`.

## Map
- `index.ts` — public API. `registry.ts` — `defineCollection`, `defineSingleton`. `entries.ts` — create, `saveDraft`,
  `publish`, `schedulePublish`, `unpublish`, `archive`, revisions, `seedEntry`, `migrateEntries`.
- `read.ts` — `getEntry`, `listEntries`, `getSingleton`, `reader(collection)` (typed). `preview.ts` — preview tokens.
  `listEntries`/`countEntries` also take nested `where` keys (`{ 'series.slug': 'basics' }`) and a `publishedAt` range
  (`publishedFrom` inclusive, `publishedBefore` exclusive): filter in SQL instead of fetching and filtering in memory.
- `sources.ts` — `contentSitemapSource`, `contentSearchSource`. `admin.ts` — `contentAdminResource`.
- `adapters/next.ts` — `previewRoute(draftMode, cookies)`, `exitPreviewRoute(draftMode)`.

## Integration
1. Env: `CONTENT_PREVIEW_SECRET` (≥ 32 chars), optional `CONTENT_DEFAULT_LOCALE` (default `en`). Migrations as in `src/lib/db/AGENTS.md`.
2. Define the site's content in one project file imported everywhere, `src/genpm/content.ts`:
   `export const pages = defineCollection('pages', { schema: z.object({ title: z.string(), body: z.string() }) })`.
3. Read in pages: `const page = await reader(pages).get(slug, { locale, draft: isDraftMode })` (404 if null).
4. Preview: `app/api/preview/route.ts` with `export const GET = previewRoute(draftMode, cookies)` (both from
   `next/headers`) and `app/api/exit-preview/route.ts` with `export const GET = exitPreviewRoute(draftMode)`.
   Passing `cookies` makes Next's draft-mode cookie expire with the token (admin links: 600 s); without it, draft mode
   lasts the whole browser session.
5. Scheduled publishing needs the @core/jobs cron endpoint running.
6. Register `contentAdminResource('pages')` in `src/genpm/admin.ts`, and the sources in `src/genpm/seo.ts` / `search.ts`.
7. Verify: create, publish, and read an entry; drafts must not appear without draft mode.

### Retrofit: make an existing site editable
Work page by page, one commit per page, without changing markup or styles:
1. List every visible literal (texts, image URLs, links) of the page.
2. Group them: one singleton per page (`home`, `about`). Repeated items of one page (features, prices, FAQs) are a
   `list` field inside that singleton (ordered, one edit screen); use a collection only when the items have their own
   pages or are shared by several pages.
3. Define the schema with the current values' shape and call `seedEntry` with the current values (idempotent; it
   only creates, so it never overwrites editor changes — and a field added later to the seed does not reach an
   already-seeded database: set it in the admin or with `saveDraft` + `publish`), e.g. from a seed script.
4. Replace literals with typed reads; keep a fallback only where a value is optional.
5. Render before/after and compare the HTML: it must be identical. Next 15 streams metadata into `<body>` for browsers
   once `generateMetadata` awaits data; `htmlLimitedBots: /.*/` in `next.config` (kit-cms Integration 1) keeps it in `<head>`.
6. Grant editors the new singletons: `defineRole` with `<singleton>:*` (e.g. `home:*`, `site_settings:*`) — the
   default `editor` role only covers the kit's collections.

## Conventions
- Field names in admin resources are `data.<field>`; slugs are lowercase `a-z0-9-` with up to 6 `/` segments.
- Changing a schema incompatibly requires `migrateEntries`; never edit jsonb by hand.
- Permissions: `<collection>:read|create|update|delete|publish`, `:own` for authors (owner = `authorId`).
- Public reads never pass `draft: true` unless draft mode came from a verified preview token.
- A preview link is not bound to its entry: Next's draft mode is browser-wide, so while it lasts (until the token
  expires, when `cookies` is passed) that browser sees the drafts of every entry of every collection. Only share
  preview links with people who may see unpublished content; `/api/exit-preview` ends it early.
- Admin `update` renames and saves the draft in one transaction: invalid data never leaves the entry renamed.

## Don't
- Don't write to `content_entries` directly; publishing must go through `publish()` (validation + revision).
- Don't put secrets or personal data in content; it is public once published.
- Don't redirect previews to absolute URLs; `safePath` rejects them.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/content/schema.tsread-only · 23978fe

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

const ts = (name: string) => timestamp(name, { withTimezone: true, mode: 'date' });

/**
 * Una fila por (colección, slug, idioma). `data` es lo publicado (lo que ve el público) y `draft` los cambios sin
 * publicar: editar una página publicada no cambia la web hasta volver a publicar. Las traducciones comparten `groupId`.
 */
export const contentEntries = pgTable(
  'content_entries',
  {
    id: primaryId('ent'),
    collection: text('collection').notNull(),
    slug: text('slug').notNull(),
    locale: text('locale').notNull(),
    groupId: text('group_id').notNull(),
    status: text('status', { enum: ['draft', 'scheduled', 'published', 'archived'] })
      .notNull()
      .default('draft'),
    data: jsonb('data').$type<Record<string, unknown>>(),
    draft: jsonb('draft').$type<Record<string, unknown>>(),
    authorId: text('author_id'),
    publishedAt: ts('published_at'),
    scheduledAt: ts('scheduled_at'),
    ...timestamps,
  },
  (t) => [
    uniqueIndex('content_entries_slug_idx').on(t.collection, t.slug, t.locale),
    index('content_entries_list_idx').on(t.collection, t.locale, t.status),
    index('content_entries_group_idx').on(t.groupId),
  ],
);

/** Historial: una revisión por publicación (y al restaurar). */
export const contentRevisions = pgTable(
  'content_revisions',
  {
    id: primaryId('rev'),
    entryId: text('entry_id')
      .notNull()
      .references(() => contentEntries.id, { onDelete: 'cascade' }),
    data: jsonb('data').$type<Record<string, unknown>>().notNull(),
    authorId: text('author_id'),
    message: text('message'),
    ...timestamps,
  },
  (t) => [index('content_revisions_entry_idx').on(t.entryId, t.createdAt)],
);

export type ContentRow = typeof contentEntries.$inferSelect;
export type ContentRevision = typeof contentRevisions.$inferSelect;