@core / search

1.0.0 ▾

1.0.0

verifiedMIT

GitHub

Site search on Postgres full-text: per-language stemming, prefix matching, safe snippets and typo fallback

Code8 filesContext~511 tokensscan passed

~511 tokens→ src/lib/search/AGENTS.md→ .cursor/rules/genpm-core-search.mdc

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

@core/search — rules for AI agents

Purpose

Site search on Postgres full-text search: one search_documents table fed by any SearchSource (@core/contracts), weighted title/body vectors with the stemmer of each document's language, prefix matching for search-as-you-type, snippets returned as plain parts (never HTML) and, if the pg_trgm extension exists, a typo-tolerant fallback on titles. No external engine, no semantic search.

Map

index.ts — public API: search, registerSearchSource, reindex, indexDocument, removeDocument, reindexJob.
search.ts — indexing and querying. schema.ts — table and GIN index.
adapters/hono.ts — searchRoutes(). adapters/next.ts — searchRoute (GET).

Integration

Generate and apply migrations (see src/lib/db/AGENTS.md). Optional typo tolerance: run create extension if not exists pg_trgm; once (available on Neon, Supabase, RDS).
Register sources in the project file src/genpm/search.ts, imported at startup: registerSearchSource(contentSearchSource('pages', { path: ({ slug }) => /${slug} })).
Build the index once and then daily: await reindexJob.enqueue({}) and schedule('search.reindex', '0 3 * * *') (@core/jobs).
Query: const { hits } = await search(q, { locale }), or mount searchRoutes() / searchRoute at /api/search.
Render snippets by mapping parts: hit.snippet.map(p => p.match ? <mark>{p.text}</mark> : p.text).
Verify: index a document and find it by the first letters of a word in its title.

Conventions

Sources yield plain text bodies (strip Markdown/HTML first, e.g. with toPlainText of @core/rich-text).
Pass locale when you know it: the query uses that language's stemmer and the GIN index.
Only index published, public content; private data never goes into search_documents.

Don't

Don't build SQL from the query string; search() already sanitizes it to words.
Don't render snippets with dangerouslySetInnerHTML.
Don't call reindex() inside a request: use the job.

# @core/search — rules for AI agents

## Purpose
Site search on Postgres full-text search: one `search_documents` table fed by any `SearchSource` (@core/contracts),
weighted title/body vectors with the stemmer of each document's language, prefix matching for search-as-you-type,
snippets returned as plain parts (never HTML) and, if the `pg_trgm` extension exists, a typo-tolerant fallback on
titles. No external engine, no semantic search.

## Map
- `index.ts` — public API: `search`, `registerSearchSource`, `reindex`, `indexDocument`, `removeDocument`, `reindexJob`.
- `search.ts` — indexing and querying. `schema.ts` — table and GIN index.
- `adapters/hono.ts` — `searchRoutes()`. `adapters/next.ts` — `searchRoute` (GET).

## Integration
1. Generate and apply migrations (see `src/lib/db/AGENTS.md`). Optional typo tolerance: run
   `create extension if not exists pg_trgm;` once (available on Neon, Supabase, RDS).
2. Register sources in the project file `src/genpm/search.ts`, imported at startup:
   `registerSearchSource(contentSearchSource('pages', { path: ({ slug }) => `/${slug}` }))`.
3. Build the index once and then daily: `await reindexJob.enqueue({})` and `schedule('search.reindex', '0 3 * * *')` (@core/jobs).
4. Query: `const { hits } = await search(q, { locale })`, or mount `searchRoutes()` / `searchRoute` at `/api/search`.
5. Render snippets by mapping parts: `hit.snippet.map(p => p.match ? <mark>{p.text}</mark> : p.text)`.
6. Verify: index a document and find it by the first letters of a word in its title.

## Conventions
- Sources yield plain text bodies (strip Markdown/HTML first, e.g. with `toPlainText` of @core/rich-text).
- Pass `locale` when you know it: the query uses that language's stemmer and the GIN index.
- Only index published, public content; private data never goes into `search_documents`.

## Don't
- Don't build SQL from the query string; `search()` already sanitizes it to words.
- Don't render snippets with `dangerouslySetInnerHTML`.
- Don't call `reindex()` inside a request: use the job.

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

src/lib/search/adapters/next.tsread-only · ae66128

// Adaptador Next.js: `app/api/search/route.ts` → `export { searchRoute as GET } from '@/lib/search/adapters/next';`
// En Server Components llama a `search()` directamente.
import { search } from '../index.ts';

export async function searchRoute(req: Request): Promise<Response> {
  const p = new URL(req.url).searchParams;
  const res = await search((p.get('q') ?? '').slice(0, 200), {
    locale: p.get('locale') ?? undefined,
    types: p.getAll('type'),
    limit: Number(p.get('limit') ?? 10) || 10,
  });
  return Response.json(res, { headers: { 'cache-control': 'public, max-age=60' } });
}