feat: Add content engine

.github/workflows/build-lint-test.yml

@@ -2,11 +2,11 @@ name: Build, Lint & Test
 
 on:
   pull_request:
-    branches: "*"
     types:
       - opened
       - edited
       - synchronize
+      - reopened
 
 jobs:
   build:
@@ -47,3 +47,6 @@ jobs:
 
       - name: Run tests
         run: pnpm test
+
+      - name: Run type tests
+        run: pnpm test:types

AGENTS.md

@@ -4,7 +4,7 @@ You are VitNode, an expert AI coding assistant. Follow repository conventions an
 
 # React / Next.js
 
-- Arrow functions for components — never `React.FC`.
+- Arrow functions for components - never `React.FC`.
 - No `any`; use `unknown` as rarely as possible.
 - Use `AutoForm` for forms instead of hand-built form components.
 - `React.lazy` + `Suspense` for content-heavy dialogs (e.g. dialogs in forms).
@@ -25,16 +25,16 @@ import { Activity } from "react";
 
 ### Caching APIs
 
-- `revalidateTag(tag, profile)` — profile is required for SWR: `revalidateTag("blog-posts", "max")` (prefer `'max'`; also `'days'`, `'hours'`) or inline `{ revalidate: 3600 }`.
-- `updateTag(\`user-${userId}\`)` — Server Actions only, read-your-writes semantics.
-- `refresh()` — Server Actions only, refreshes uncached data, never touches the cache.
+- `revalidateTag(tag, profile)` - profile is required for SWR: `revalidateTag("blog-posts", "max")` (prefer `'max'`; also `'days'`, `'hours'`) or inline `{ revalidate: 3600 }`.
+- `updateTag(\`user-${userId}\`)` - Server Actions only, read-your-writes semantics.
+- `refresh()` - Server Actions only, refreshes uncached data, never touches the cache.
 
 # Coding Guidelines
 
 - Always implement best practices for performance, security, and accessibility.
 - Semantic HTML (`main`, `header`) with correct ARIA roles/attributes, `sr-only` for screen-reader-only text, and alt text on all images unless decorative or repetitive.
 - Emit events for important actions (create, update, delete) so other components can react; use events instead of prop drilling or context. Document them in `apps/docs/content/docs/dev/events/built-in-events.mdx`.
-- AI features use the Vercel AI SDK only — resolve models via the `c.get("ai")` registry and call native SDK functions.
+- AI features use the Vercel AI SDK only - resolve models via the `c.get("ai")` registry and call native SDK functions.
 
 # Design
 
@@ -43,7 +43,7 @@ import { Activity } from "react";
 - Exactly 3–5 colors total. Never use purple or violet prominently.
 - If you override a background color, you MUST override its text color for contrast.
 - Prefer semantic design tokens (`bg-background`, `text-foreground`).
-- Use the Tailwind spacing scale (`p-4`, `mx-2`) — never arbitrary values (`p-[16px]`).
+- Use the Tailwind spacing scale (`p-4`, `mx-2`) - never arbitrary values (`p-[16px]`).
 - Use `gap-*` classes for spacing. Never use `space-*`, and never mix margin/padding with gap on the same element.
 - Use semantic (`items-center`, `justify-between`) and responsive (`md:grid-cols-2`) classes.
 - No floats or absolute positioning unless absolutely necessary.
@@ -53,7 +53,7 @@ import { Activity } from "react";
 # Documentation
 
 - Document every new feature. Keep it simple, SEO-friendly, and understandable at any skill level.
-- Friendly and lightly funny tone — don't overdo it.
+- Friendly and lightly funny tone - don't overdo it.
 - Skip big comments; code is self-documenting.
 - Request images with a comment: `// Image prompt: {here_prompt_to_generate_image}`
 - Put install commands in tabbed code blocks with correct syntax highlighting:
@@ -81,5 +81,8 @@ npm i x
 # Testing
 
 - Admin login: `test@test.com` / `Test123!`
-- Write and run vitest unit tests for all new features and bug fixes — skip only if vitest isn't configured.
-- Don't write tests for trivial code unless they have complex logic or edge cases.
+- Write and run vitest unit tests for all new features and bug fixes - skip only if vitest isn't configured.
+- Don't write tests:
+  - for trivial code unless they have complex logic or edge cases
+  - for tests where it uses a database or external API
+  - how UI should be rendered (use playwright for that to write e2e tests)

apps/api/package.json

@@ -43,6 +43,7 @@
     "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",
     "@vitnode/blog": "workspace:*",
+    "@vitnode/example": "workspace:*",
     "@vitnode/config": "workspace:*",
     "@vitnode/nodemailer": "workspace:*",
     "dotenv": "^17.4.2",

apps/api/src/vitnode.api.config.ts

@@ -2,6 +2,7 @@ import { google } from "@ai-sdk/google";
 import { blogApiPlugin } from "@vitnode/blog/config.api";
 // import { LocalStorageAdapter } from "@vitnode/core/api/adapters/storage/local";
 import { buildApiConfig } from "@vitnode/core/vitnode.config";
+import { exampleApiPlugin } from "@vitnode/example/config.api";
 import { NodeCronAdapter } from "@vitnode/node-cron";
 import { NodemailerEmailAdapter } from "@vitnode/nodemailer";
 // import { S3StorageAdapter } from "@vitnode/s3";
@@ -17,7 +18,7 @@ export const POSTGRES_URL =
   process.env.POSTGRES_URL ?? "postgresql://root:root@localhost:5432/vitnode";
 
 export const vitNodeApiConfig = buildApiConfig({
-  plugins: [blogApiPlugin()],
+  plugins: [blogApiPlugin(), exampleApiPlugin()],
   ai: {
     models: [
       {

apps/docs/content/docs/dev/advanced/queue.mdx

@@ -145,9 +145,86 @@ import { TypeTable } from "fumadocs-ui/components/type-table";
       type: "Date",
       default: "now",
     },
+    pluginId: {
+      description:
+        "Who owns the handler, when that is not the plugin handling the request. The worker resolves handlers by `${pluginId}:${name}`, so dispatching a core task from a plugin route needs this - otherwise nothing ever claims the row.",
+      type: "string",
+      default: "the requesting plugin, or @vitnode/core",
+    },
+    tx: {
+      description:
+        "Join an existing transaction instead of using the request handle. Needed whenever the row the task refers to is written in the same unit of work, or the queue row can commit while that row rolls back.",
+      type: "Transaction",
+    },
   }}
 />
 
+<Callout type="info" title="Both exist because of scheduled publishing">
+  The [Content Engine](/docs/dev/content-engine/publication-and-editorial#4-scheduled-publishing) books a schedule row
+  and its queue task in one transaction, from a plugin's route, against a task
+  core registers. That needs `tx` for atomicity and `pluginId` so the worker can
+  find the handler - and it is a shape any plugin can reuse.
+</Callout>
+
+## Tasks core ships
+
+| Task | Attempts | What it does |
+| --- | --- | --- |
+| `send-email` | 3 | Delivers a rendered email through the configured provider |
+| `rebuild-search-index` | 3 | Clears and rebuilds the [search](/docs/dev/content-engine/public-api-and-caching#2-full-text-search-indexing) index, whole or per collection |
+| `content-schedule` | 3 | Runs one [scheduled publication](/docs/dev/content-engine/publication-and-editorial#4-scheduled-publishing). A cancelled, rescheduled or already-executed schedule is a no-op |
+| `content-schedule-effects` | 5 | Emits the event, syncs search and expires the cache for a scheduled transition that has **already committed**. Never republishes |
+
+`content-schedule` is worth reading as a pattern: its payload is
+`{ scheduleId, generation }` and nothing else. Every real value is re-read from
+the row under `FOR UPDATE`, so a task left over from a plan that has since
+changed finds a mismatch and quietly does nothing - which is far more reliable
+than trying to delete a queued row. It holds that lock from the claim all the
+way to the commit, so a cancel arriving mid-flight waits and then honestly
+reports that the schedule already ran.
+
+### Why the effects are a second task
+
+The pair is worth reading as a pattern too, because splitting them is the whole
+point:
+
+```text
+content-schedule            claim → publish → revision → settle → enqueue effects
+                            ── one transaction ──────────────────────────────────
+content-schedule-effects    event → search → cache bridge
+```
+
+A transition is a database write that either committed or did not. Announcing it
+is three calls to systems a transaction cannot reach. Retrying them **together**
+would re-run a publish that is idempotent - so the second run finds nothing
+changed and skips the announcements entirely, which is how a scheduled unpublish
+ends up permanently serving a page it should have expired.
+
+The effects row is written inside the transition's transaction, so it exists if
+and only if the transition committed, and it carries everything frozen rather
+than re-reading a record that may have moved on.
+
+All three have to land for the task to succeed - a listener that threw, a search
+engine that refused the write, or any configured web origin that did not accept
+its invalidation each fail the run, and the reasons are combined into one
+`effectsError`. `EventsModel.emit()` never throws, so the task reads
+`EventEmitResult.failures` rather than waiting for an exception that is not
+coming.
+
+Delivery is at-least-once: the search write and the cache expiry are idempotent,
+but a listener can see one `published` twice, so a listener that must act once
+keys off the `scheduleId` in the payload.
+
+The event's envelope is stamped with the plugin that owns the **content type**,
+not with core. Core owns the handler; `content.example.article.published`
+belongs to the example plugin however it was triggered.
+
+<Callout type="info" title="An announcement failure is not a publication failure">
+  The schedule stays `completed` and the reason lands in `effectsError` on the
+  schedule row. Nothing is ever moved back to `pending` because an event
+  bounced - the record really did publish.
+</Callout>
+
 ## Retries and backoff
 
 If a handler throws, the task is retried with an exponential backoff

apps/docs/content/docs/dev/advanced/redis.mdx

@@ -88,26 +88,43 @@ export const vitNodeApiConfig = buildApiConfig({
 
 ### Options
 
-The `redis` object accepts a `url` plus any
-[ioredis](https://github.com/redis/ioredis) `RedisOptions`.
+The `redis` object is a
+[node-redis](https://github.com/redis/node-redis) `RedisClientOptions`.
 
 import { TypeTable } from "fumadocs-ui/components/type-table";
 
 <TypeTable
   type={{
     url: {
       description:
-        "The Redis connection string (redis:// or rediss://). When omitted, ioredis connects to localhost:6379 using the other options.",
+        "The Redis connection string (redis:// or rediss://). When omitted, node-redis connects to localhost:6379 using the other options.",
       type: "string",
     },
-    "...RedisOptions": {
+    password: {
       description:
-        "Any ioredis option, e.g. host, port, password, db, tls. enableOfflineQueue defaults to false so cache commands fail fast (and fall through) when Redis is unreachable - override it if you prefer queuing.",
-      type: "RedisOptions",
+        "Password used to authenticate. Pair it with username when your Redis uses ACL users.",
+      type: "string",
+    },
+    socket: {
+      description:
+        "Connection-level options: host, port, tls, connectTimeout, reconnectStrategy.",
+      type: "RedisSocketOptions",
+    },
+    "...RedisClientOptions": {
+      description:
+        "Any other node-redis option, e.g. database or name. disableOfflineQueue defaults to true so cache commands fail fast (and fall through) when Redis is unreachable - override it if you prefer queuing.",
+      type: "RedisClientOptions",
     },
   }}
 />
 
+<Callout type="info" title="Connecting happens in the background">
+  VitNode opens the connection at boot without blocking startup, and node-redis
+  keeps retrying with an exponential backoff if Redis is unreachable. Requests
+  that land before the socket is ready behave exactly like a Redis outage: the
+  cache reports a miss and the request goes to the database.
+</Callout>
+
 ## Using the cache
 
 Access the cache in any route or model with `c.get("cache")`.

apps/docs/content/docs/dev/ai/index.mdx

@@ -7,7 +7,7 @@ description: Easily configure and resolve AI models in VitNode using the native
 
 VitNode brings AI powers straight into your backend via the built-in [Vercel AI SDK](https://ai-sdk.dev/). Configure your models once in `buildApiConfig`, grab them in any route handler using `c.get("ai")`, and call native AI SDK functions directly. Zero wrappers, zero hassle! 🚀
 
-AI is completely **optional** — if you don't configure any models, VitNode won't touch any external services.
+AI is completely **optional** - if you don't configure any models, VitNode won't touch any external services.
 
 ## Quick Setup
 
@@ -59,11 +59,23 @@ Define your model registry in `buildApiConfig`. The **first model** listed acts
 export const vitNodeApiConfig = buildApiConfig({
   ai: {
     models: [
-      { id: "default", name: "Claude Sonnet 5", model: "anthropic/claude-sonnet-5" },
-      { id: "fast", name: "Claude Haiku 4.5", model: "anthropic/claude-haiku-4.5" },
+      {
+        id: "default",
+        name: "Claude Sonnet 5",
+        model: "anthropic/claude-sonnet-5",
+      },
+      {
+        id: "fast",
+        name: "Claude Haiku 4.5",
+        model: "anthropic/claude-haiku-4.5",
+      },
     ],
     embeddingModels: [
-      { id: "default", name: "Text Embedding 3 Small", model: "openai/text-embedding-3-small" },
+      {
+        id: "default",
+        name: "Text Embedding 3 Small",
+        model: "openai/text-embedding-3-small",
+      },
     ],
     imageModels: [
       { id: "default", name: "GPT Image 1", model: "openai/gpt-image-1" },
@@ -78,8 +90,16 @@ import { anthropic } from "@ai-sdk/anthropic";
 export const vitNodeApiConfig = buildApiConfig({
   ai: {
     models: [
-      { id: "default", name: "Claude Sonnet 5", model: anthropic("claude-sonnet-5") },
-      { id: "fast", name: "Claude Haiku 4.5", model: anthropic("claude-haiku-4.5") },
+      {
+        id: "default",
+        name: "Claude Sonnet 5",
+        model: anthropic("claude-sonnet-5"),
+      },
+      {
+        id: "fast",
+        name: "Claude Haiku 4.5",
+        model: anthropic("claude-haiku-4.5"),
+      },
     ],
   },
 });
@@ -115,4 +135,3 @@ import { TypeTable } from "fumadocs-ui/components/type-table";
 />
 
 Ready to generate text or create embeddings? Check out the [Usage](/docs/dev/ai/usage) guide!
-