agent-cms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Jokull Solberg
+
+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.

package/PROMPT.md

@@ -0,0 +1,55 @@
+You are an agent-cms setup guide. Your job is to help the user add a headless CMS to their project backed by Cloudflare D1 and R2.
+
+Reference the agent-cms repo for details as you work:
+- `README.md` — feature overview, bindings, field types, interfaces, examples
+- `examples/blog/` — complete CMS + Astro site with structured text, responsive images, service bindings
+- `examples/editor-mcp/` — editor onboarding with OAuth gateway and scoped tokens
+
+Clone or fetch the repo if you need specifics: `https://github.com/jokull/agent-cms`
+
+## Before Starting
+
+1. Assess the repository:
+   `ls -la wrangler.jsonc wrangler.json wrangler.toml package.json tsconfig.json bun.lock pnpm-lock.yaml package-lock.json 2>/dev/null`
+   Determine package manager from lock file. If multiple, ask.
+2. Determine integration mode. Ask the user:
+   - **Standalone Worker** — separate CMS Worker, site fetches via HTTP or service binding. Best when the CMS and site are separate projects.
+   - **Service binding** — separate CMS Worker, site calls `env.CMS.fetch()` with zero latency. Best for Cloudflare-to-Cloudflare.
+   - **Mounted** — mount agent-cms at `/cms` inside an existing Worker. Best when you want one Worker and one D1 database for everything.
+
+## Standalone Worker
+
+1. Run `pnpm create agent-cms <name>` (or npm/bun equivalent)
+2. `cd <name> && pnpm install && pnpm dev`
+3. `pnpm run setup -- http://127.0.0.1:8787`
+4. Register the MCP server:
+   `claude mcp add --transport http <name> http://127.0.0.1:8787/mcp`
+5. If the user wants a service binding from their site Worker, add to the site's `wrangler.jsonc`:
+   ```jsonc
+   { "services": [{ "binding": "CMS", "service": "<name>" }] }
+   ```
+   Then fetch from the site: `env.CMS.fetch(new Request("http://cms/graphql", { method: "POST", body: ... }))`
+
+## Mounted in Existing Worker
+
+1. Install: `pnpm add agent-cms`
+2. Check the user's existing `wrangler.jsonc` for D1 and R2 bindings. If D1 exists, ask whether to reuse it or create a new one for the CMS. If R2 exists, same question.
+3. Create the handler in the user's existing Worker entry point:
+   ```ts
+   import { createCMSHandler } from "agent-cms";
+   ```
+   Mount it at `/cms` using whatever router the project uses (Hono, itty-router, or raw URL matching).
+4. Run setup: `curl -X POST http://localhost:8787/cms/api/setup`
+5. Register MCP: `claude mcp add --transport http cms http://127.0.0.1:8787/cms/mcp`
+
+## After Setup
+
+1. Confirm the MCP server is responding: call `schema_info`
+2. Ask the user what content they need — blog posts, products, pages, events — and create the schema conversationally
+3. If the user has an existing site, help them query content via GraphQL. Check if they use a typed GraphQL client (gql.tada, graphql-codegen) and offer to introspect the schema for types.
+
+## What NOT to Do
+
+- Do not create content models without asking the user what they need
+- Do not deploy to production without explicit confirmation
+- Do not touch existing wrangler bindings without asking

package/README.md

@@ -0,0 +1,220 @@
+# agent-cms
+
+Agent-first headless CMS. Runs as a Cloudflare Worker backed by D1 and R2 in your own account. No hosted service, no admin UI. Agents define schemas, manage content, and publish — via MCP.
+
+## What you get
+
+- **Structured text with typed blocks** — a document tree where rich components (code blocks, media, custom types) are embedded inline. One GraphQL query returns the full tree with discriminated block unions. Map directly to React/Svelte/Vue components in a single server hop. Render with [`react-datocms`](https://github.com/datocms/react-datocms), `vue-datocms`, or `datocms-svelte` — the structured text format is [DAST](https://www.datocms.com/docs/structured-text/dast), an open standard.
+- **Hybrid search** — FTS5 for keyword matching, Cloudflare Vectorize for semantic similarity, combined with reciprocal rank fusion. All on D1.
+- **Draft/publish with scheduling** — records start as drafts. Publishing captures a version snapshot. Schedule publish/unpublish at future datetimes. Full version history — restore to any snapshot, and the restore itself is reversible.
+- **Geospatial filtering** — `lat_lon` field type with `near(latitude, longitude, radius)` queries in GraphQL.
+- **Automatic reverse references** — link model A to model B, and B gets a query field for all records in A that reference it, with full filtering, ordering, and pagination.
+- **Two MCP servers** — admin MCP (`/mcp`) for schema and content, editor MCP (`/mcp/editor`) scoped to content operations only. Create editor tokens with optional expiry.
+- **Multi-locale with fallback chains** — per-field opt-in. Locale A falls back to B falls back to C. The GraphQL resolver walks the chain.
+- **24 field types** — string, text, boolean, integer, float, date, date_time, slug (auto-generated), media (with focal point + blurhash), media_gallery, link, links, structured_text, seo (title + description + image + twitter card), json, color (RGBA), lat_lon, video. All validated with Effect schemas.
+- **Tree hierarchies and sortable collections** — parent-child nesting and explicit position ordering as first-class model properties.
+- **Dynamic SQL builder** — the query engine builds SQL at runtime from the content schema. No ORM, no generated client. The content schema is decoupled from your application schema — run this on the same D1 database as your site.
+- **Responsive images** — Cloudflare Image Resizing with focal points, blurhash for progressive loading, color palette extraction. R2 storage, no external service.
+- **Bulk operations** — create up to 1000 records in a single call.
+- **Schema portability** — export the full schema as JSON (no IDs, just api_keys), import it on a fresh instance.
+- **Three interfaces** — REST API, GraphQL, and MCP, all auto-generated from the content schema.
+- **Effect-TS throughout** — typed errors, dependency injection via services and layers, no try/catch. The whole CMS is a single Worker.
+
+## Quick start
+
+Copy the prompt from [`PROMPT.md`](./PROMPT.md) into Claude Code. It assesses your project, asks how you want to integrate (standalone Worker, service binding, or mounted in an existing Worker), and wires everything up — including D1 database, wrangler config, and MCP server connection.
+
+## Interfaces
+
+### `/mcp` — Admin agent interface
+
+MCP server with tools for schema management, content operations (CRUD, bulk insert, publish/unpublish, reorder), asset management, search, and schema import/export. Requires `writeKey`.
+
+### `/mcp/editor` — Editorial agent interface
+
+Reduced MCP server for content-authoring agents. Accepts either an editor token or `writeKey`. Exposes schema introspection, record CRUD, drafts, publish/unpublish, version restore, assets, site settings, and search. Does not expose schema mutation, token management, or admin operations.
+
+### `/graphql` — Content delivery
+
+Read-only GraphQL API. Supports filtering, ordering, pagination, locale fallback, and draft previews via `X-Include-Drafts`.
+
+```graphql
+{
+  all_posts(
+    filter: { _status: { eq: "published" } }
+    order_by: [_created_at_DESC]
+    first: 10
+  ) {
+    id
+    title
+    slug
+    cover_image {
+      url
+      width
+      height
+      alt
+    }
+    body {
+      value
+      blocks {
+        ... on CodeBlockRecord {
+          id
+          code
+          language
+        }
+      }
+    }
+  }
+}
+```
+
+#### Naming conventions
+
+Model `api_key` values (snake_case) map to GraphQL names:
+
+| api_key | GraphQL type | Single query | List query | Meta query |
+|---------|-------------|-------------|------------|------------|
+| `blog_post` | `BlogPost` | `blog_post` | `all_blog_posts` | `_all_blog_posts_meta` |
+| `category` | `Category` | `category` | `all_categories` | `_all_categories_meta` |
+
+Block types get a `Record` suffix: `code_block` → `CodeBlockRecord`.
+
+Field `api_key` values stay snake_case in queries: `cover_image`, `published_at`.
+
+#### Performance model
+
+GraphQL nesting is not compiled into one giant SQL join. The server fetches root records, batches linked records and StructuredText work into set-oriented SQL, then assembles the nested shape in memory. See [`PERFORMANCE.md`](./PERFORMANCE.md).
+
+#### MCP resources and prompts
+
+Agents connecting via MCP get two resources:
+- **`agent-cms://guide`** — workflow order, naming conventions, field value formats
+- **`agent-cms://schema`** — current schema as JSON
+
+Two prompts for common workflows:
+- **`setup-content-model`** — design and create content models from a description
+- **`generate-graphql-queries`** — generate typed GraphQL queries for a model
+
+### `/api` — REST
+
+JSON REST API for programmatic access. Models, fields, records, assets, locales, publish/unpublish, scheduling, bulk operations, schema import/export.
+
+### `/api/search` — Search
+
+FTS5 keyword search with BM25 ranking and snippets, scoped to all models or a single model. When `AI` + `VECTORIZE` bindings are configured:
+
+- **`keyword`** — FTS5. Phrases (`"exact match"`), prefix (`word*`), boolean (`AND`/`OR`).
+- **`semantic`** — Vectorize cosine similarity.
+- **`hybrid`** (default) — Reciprocal rank fusion of keyword + semantic results.
+
+## Editor tokens
+
+Editor tokens are the credential for non-admin editing flows. Create them via `POST /api/tokens` or the `editor_tokens` MCP tool (with `action: "create"`). The raw token is shown once; the server stores a hash.
+
+Editor tokens can access `/mcp/editor`, REST content/asset operations, and draft GraphQL previews. They cannot mutate schema, manage tokens, or run admin operations.
+
+For editor onboarding with OAuth, the package exports `createCmsAdminClient` and `createEditorMcpProxy` to stand up an app-land MCP gateway. See [`examples/editor-mcp/`](./examples/editor-mcp/).
+
+## Scheduling
+
+Schedule publish/unpublish at future datetimes via REST or MCP. To execute schedules automatically, add a cron trigger:
+
+```ts
+import { createCMSHandler } from "agent-cms";
+
+let cachedHandler: ReturnType<typeof createCMSHandler> | null = null;
+
+function getHandler(env: Env) {
+  if (!cachedHandler) {
+    cachedHandler = createCMSHandler({
+      bindings: { db: env.DB, assets: env.ASSETS, writeKey: env.CMS_WRITE_KEY },
+    });
+  }
+  return cachedHandler;
+}
+
+export default {
+  fetch(request: Request, env: Env) {
+    return getHandler(env).fetch(request);
+  },
+  scheduled(_controller: ScheduledController, env: Env) {
+    return getHandler(env).runScheduledTransitions();
+  },
+};
+```
+
+```json
+{ "triggers": { "crons": ["* * * * *"] } }
+```
+
+Without a cron trigger, schedules are stored and queryable but do not execute.
+
+## Lifecycle hooks
+
+React to content events with hooks passed to `createCMSHandler`:
+
+```ts
+createCMSHandler({
+  bindings: { db: env.DB, assets: env.ASSETS, writeKey: env.CMS_WRITE_KEY },
+  hooks: {
+    onPublish: ({ modelApiKey, recordId }) => fetch(env.DEPLOY_HOOK_URL, { method: "POST" }),
+    onRecordCreate: ({ modelApiKey, recordId }) => { /* notify, sync, etc. */ },
+  },
+});
+```
+
+Available: `onRecordCreate`, `onRecordUpdate`, `onRecordDelete`, `onPublish`, `onUnpublish`. All receive `{ modelApiKey, recordId }`. Fire-and-forget.
+
+## Bindings
+
+Only `DB` is required. Everything else is optional and degrades gracefully.
+
+| Binding | Type | What it enables |
+|---------|------|-----------------|
+| `DB` | D1 | **Required.** Content storage, schema, FTS5 search. |
+| `ASSETS` | R2 | Asset file storage and serving via `/assets/`. |
+| `AI` | Workers AI | Embedding generation for semantic search. |
+| `VECTORIZE` | Vectorize | Semantic vector search. Requires `AI`. |
+| `CMS_WRITE_KEY` | Secret | Auth for writes, MCP, and publish. Without it, writes are open. |
+| `ASSET_BASE_URL` | Variable | Public URL prefix for assets and Image Resizing. Must be a custom domain for transforms. |
+
+```jsonc
+{
+  "d1_databases": [{ "binding": "DB", "database_name": "my-cms-db", "database_id": "..." }],
+  "r2_buckets": [{ "binding": "ASSETS", "bucket_name": "my-cms-assets" }],
+  "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-cms-content" }],
+  "ai": { "binding": "AI" },
+  "vars": { "ASSET_BASE_URL": "https://cms.example.com" }
+}
+```
+
+To create the Vectorize index: `npx wrangler vectorize create my-cms-content --dimensions=384 --metric=cosine`
+
+## Assets
+
+Asset binaries live in R2. Metadata in D1. Served from `/assets/:id/:filename`.
+
+- **MCP/editor**: `import_asset_from_url` — download, store, register in one step
+- **Browser**: `PUT /api/assets/:id/file` then register metadata
+- **Server**: upload to R2, then `POST /api/assets`
+
+Focal points, blurhash, and color palette are stored per-asset. Cloudflare Image Resizing generates responsive variants at the edge.
+
+## Stack
+
+- **Runtime**: Cloudflare Workers
+- **Database**: D1 (managed SQLite)
+- **Assets**: R2 + Cloudflare Image Resizing
+- **Search**: SQLite FTS5 + Cloudflare Vectorize
+- **Application**: [Effect](https://effect.website)
+- **GraphQL**: [graphql-yoga](https://the-guild.dev/graphql/yoga-server) with generated SDL
+- **Testing**: [Vitest](https://vitest.dev) (`pnpm test`)
+
+## Examples
+
+- [`examples/blog/`](./examples/blog/) — CMS Worker + Astro SSR site with typed GraphQL (gql.tada), structured text rendering, responsive images, service bindings
+- [`examples/editor-mcp/`](./examples/editor-mcp/) — editor onboarding: app-land OAuth gateway, scoped editor tokens, separate MCP URLs for developers and editors
+
+## License
+
+MIT