Initial Commit

openspec/changes/enterprise-api-plugin-cms/proposal.md

@@ -0,0 +1,80 @@
+# OpenSpec Change: enterprise-api-plugin-cms
+
+- **Change ID**: enterprise-api-plugin-cms
+- **Package**: `@suaveplan/api-plugin-cms`
+- **Category**: api/content
+- **Target path**: `api/content/api-plugin-cms`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-cms.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/api-plugin-cms` on the genesis branch from scratch at enterprise quality. Headless CMS plugin: content types (dynamic schema via Zod), content entries (CRUD with draft/published/archived states), versioning with full revision history, media management (upload + metadata via `@suaveplan/mime`), localization hooks, and a search index bridge to `@suaveplan/api-plugin-search`. Routes under `/cms`. Per-table SurrealQL. Typed events: `cms:entry:published`, `cms:entry:archived`, `cms:media:uploaded`.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
+| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
+| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth`, `requireRole` |
+| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
+| `@suaveplan/api-plugin-search` (`workspace:^`) | Search index |
+| `@suaveplan/mime` (`workspace:^`) | MIME detection for uploads |
+| `@suaveplan/events` (`workspace:^`) | Event bus |
+| `@suaveplan/error` (`workspace:^`) | `CmsError` hierarchy |
+| `@suaveplan/audit-logging` (`workspace:^`) | Publish/archive audit |
+| `@suaveplan/rate-limiter` (`workspace:^`) | Rate limits |
+| `hono` + `@hono/zod-openapi` + `zod` | Routes |
+| `@opentelemetry/api` | OTel |
+
+---
+
+## Public API surface
+
+```ts
+function createCmsPlugin(config?: CmsPluginConfig): PluginDescriptor
+
+// Services: ContentTypeService, ContentEntryService, MediaService, RevisionService
+// Routes: /cms/content-types, /cms/entries, /cms/entries/:id,
+//         /cms/entries/:id/publish, /cms/entries/:id/revisions, /cms/media
+```
+
+### Error codes
+
+```ts
+type CmsErrorCode =
+  | "CMS_TYPE_NOT_FOUND"
+  | "CMS_ENTRY_NOT_FOUND"
+  | "CMS_ENTRY_LOCKED"
+  | "CMS_MEDIA_NOT_FOUND"
+  | "CMS_INVALID_CONTENT_TYPE"
+  | "CMS_SCHEMA_VALIDATION_FAILED"
+```
+
+---
+
+## File layout
+
+```text
+api/content/api-plugin-cms/
+  package.json  tsconfig.json  vitest.config.ts
+  surql/ (content_type, content_entry, content_revision, media tables)
+  src/
+    index.ts  events.ts  types/  errors/  schemas/
+    services/content-type/  services/content-entry/
+    services/media/  services/revision/
+    routes/content-types/  routes/entries/  routes/media/
+  tests/integration.test.ts
+```
+
+---
+
+## Impact
+
+Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/api-plugin-search`, `@suaveplan/mime`.

openspec/changes/enterprise-api-plugin-cms/tasks.md

@@ -0,0 +1,56 @@
+# Tasks: enterprise-api-plugin-cms
+
+**Change ID**: enterprise-api-plugin-cms
+**Package**: `@suaveplan/api-plugin-cms`
+**Target path**: `api/content/api-plugin-cms`
+**Prerequisite packages on Verdaccio**: `@suaveplan/api`, `@suaveplan/api-shared`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/api-plugin-search`, `@suaveplan/mime`, `@suaveplan/events`, `@suaveplan/audit-logging`, `@suaveplan/rate-limiter`, `@suaveplan/error`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold + types + errors + events
+
+- [ ] Create `api/content/api-plugin-cms/`; `package.json` v0.0.0; standard tooling.
+- [ ] Types: `ContentType`, `ContentEntry`, `ContentRevision`, `MediaFile`, `CmsPluginConfig` (Zod).
+- [ ] Errors: 6-code union + metadata + registration. Test + doc.
+- [ ] Events: `CmsEventMap` (cms:entry:created, cms:entry:published, cms:entry:archived, cms:media:uploaded).
+
+---
+
+## 2. SurrealQL
+
+- [ ] `content_type.surql`, `content_entry.surql`, `content_revision.surql`, `media.surql`. All with tenantId indexes + full-text search definitions.
+
+---
+
+## 3. Services (each `.test.ts` + `.md`)
+
+- [ ] **ContentTypeService**: define schema (arbitrary Zod-serialisable JSON schema), list, update, delete (cascade check).
+- [ ] **ContentEntryService**: create/update/delete entries validated against their content type schema; `publish` (draft → published); `archive`; list with filtering + pagination; `getBySlug`. Emit events; audit publish/archive.
+- [ ] **MediaService**: upload (MIME detection via `@suaveplan/mime`; allowed-type check); generate storage key; list; delete.
+- [ ] **RevisionService**: `listRevisions`, `getRevision`, `restoreRevision`.
+
+---
+
+## 4. Routes
+
+- [ ] Content types: `GET/POST /cms/content-types`, `PATCH/DELETE /cms/content-types/:id` — auth + `requireRole("EDITOR")`.
+- [ ] Entries: `GET/POST /cms/entries`, `GET/PATCH/DELETE /cms/entries/:id` — auth; `POST /cms/entries/:id/publish`, `archive` — auth + audit.
+- [ ] Revisions: `GET /cms/entries/:id/revisions`, `POST /cms/entries/:id/revisions/:revId/restore`.
+- [ ] Media: `POST /cms/media`, `GET /cms/media`, `DELETE /cms/media/:id` — auth + rate-limit.
+- [ ] Route `.test.ts` + `.md`.
+
+---
+
+## 5. Plugin factory + integration tests + publish
+
+- [ ] `createCmsPlugin`: `definePlugin`, `dependencies: ["database", "auth"]`, `migrationsPath: "./surql"`.
+- [ ] Integration: create type → create entry → publish → revision list → restore (real SurrealDB).
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-cms` — green; 100% coverage.
+- [ ] `bun scripts/publish.ts --package @suaveplan/api-plugin-cms`.
+- [ ] Archive → `openspec/archive/2026-04-24-enterprise-api-plugin-cms/`.