Add @suaveplan/api-plugin-cms

Package: @suaveplan/api-plugin-cms Status: PROPOSED Type: new-package

Why

Headless-CMS primitives for @suaveplan/api applications. The upstream package on main (/mnt/s/web/suaveplan/packages/server/api-plugin-cms) ships a CmsEngine that manages flexible ContentModel definitions, ContentEntry records with draft → review → published → archived status transitions guarded by VALID_STATUS_TRANSITIONS, versioned ContentVersion history, slug uniqueness, an RFC 7807 problem+json helper, and a CmsError hierarchy registered into the shared error metadata registry on module load. Genesis needs that surface ported at full functional parity so downstream @suaveplan/api apps can author content models, validate entries, and walk the status lifecycle without reaching for main.

What changes

ADDED: CmsEngine — in-memory CMS core managing models, entries, and version history; emits eight typed events through @suaveplan/events.
ADDED: CmsError, CMS_CODES, CmsErrorCode — SuaveplanError subclass and seven stable error codes (CONTENT_NOT_FOUND, MODEL_NOT_FOUND, INVALID_TRANSITION, VALIDATION_FAILED, DUPLICATE_SLUG, MODEL_IN_USE, INVALID_INPUT). The first six are verbatim upstream; INVALID_INPUT is raised by the new createCmsPlugin factory when Zod boundary validation fails (genesis convention, mirrors api-plugin-audit / api-plugin-database).
ADDED: contentNotFound, modelNotFound, invalidStatusTransition, validationFailed, duplicateSlug, modelInUse — error-factory helpers.
ADDED: respondProblemJson, formatProblemJson, PROBLEM_JSON_CONTENT_TYPE, HttpResponseLike, ProblemDetails — RFC 7807 problem+json rendering.
ADDED: ContentStatus, ContentType, FieldType, ContentField, FieldValidation, ContentModel, ContentEntry, ContentVersion, CreateContentInput, UpdateContentInput, ContentQuery, CmsEventMap — content-model types.
ADDED: generateSlug, validateContentData, VALID_STATUS_TRANSITIONS — utility surface.
ADDED: createCmsPlugin — definePlugin() factory that registers the constructed CmsEngine as the cms slot on the host ServiceRegistry, matching the genesis api-plugin convention.
ADDED: CmsPluginOptionsSchema, CmsPluginOptions, CmsPluginConfig — Zod-validated plugin options bundle (injectable Clock / IdGenerator).
ADDED: CmsInstruments, getCmsInstruments, resetCmsInstruments — OTel meter bundle (content created / updated / published / archived / deleted counters; model created counter; validation-failure counter).

Out of scope

SurrealDB storage adapter — upstream is in-memory only; matched.
HTTP route mounting on app — upstream ships respondProblemJson but no actual routes; matched.
Auth/role gating, audit-log integration, webhook/preview tokens, rich-text/media handling, full-text search hook — every item listed under §4 of enterprise/api-plugin-cms.md is an aspirational future enhancement, not in the upstream baseline.
Counter-based ID replacement with ULID — kept as an injectable IdGenerator so callers wanting ULID supply it; default mirrors upstream cms_<n>_<ts> for byte-identical parity.

Source mapping

This change derives from ../suaveplan/enterprise/api-plugin-cms.md and the upstream source at ../suaveplan/packages/server/api-plugin-cms/.

Requirement	Source lines	Notes
`CmsEngine` lifecycle (`createModel`, `getModel`, `listModels`, `deleteModel`)	upstream `src/routes/cms-engine.ts` L38–L70	verbatim port — same method bodies, adapted to `EventBus<CmsEventMap>` instead of upstream `EventEmitter`
Content entry CRUD (`createContent`, `getContent`, `queryContent`, `updateContent`, `deleteContent`)	upstream `src/routes/cms-engine.ts` L71–L210	verbatim port — query filtering / sorting / paging preserved
Status-transition guard via `VALID_STATUS_TRANSITIONS`	upstream `src/routes/cms-engine.ts` L179–L202 + `src/types/cms.types.ts` L134–L142	verbatim
Versioned history (`getVersions`, `saveVersion`)	upstream `src/routes/cms-engine.ts` L213–L230	verbatim
`CmsError` + six factory helpers	upstream `src/errors/cms-errors.ts` L1–L71	adapted from `BaseError<Code, Context>` to genesis `SuaveplanError<Code>` (genesis has no second-generic context — context lives on `options.context`)
Stable code registry (`CMS_CODES`)	upstream `src/errors/error-codes.ts` L20–L74	adapted from upstream `ErrorCodes.registerMany(metadata)` (no equivalent in genesis `@suaveplan/error`) to `defineCodes("CMS", [...])`; HTTP-status metadata folded into the problem-json renderer (mirrors `api-plugin-database`)
Side-effect import of code registry on barrel load	upstream `src/index.ts` L3	matched — `src/index.ts` side-effect-imports `./error-codes/error-codes.js`
`respondProblemJson`, `PROBLEM_JSON_CONTENT_TYPE`	upstream `src/routes/problem-json.ts` L1–L47	adapted — genesis `@suaveplan/error` does not yet ship `HttpError` / `formatErrorAsProblemJson` / `ProblemDetails`, so a local `formatProblemJson` mirrors `api-plugin-database`'s pattern
`ContentStatus`, `ContentType`, `FieldType`, `ContentField`, `FieldValidation`, `ContentModel`, `ContentEntry`, `ContentVersion`, `CreateContentInput`, `UpdateContentInput`, `ContentQuery`, `CmsEventMap`	upstream `src/types/cms.types.ts` L1–L131	verbatim
`generateSlug`	upstream `src/types/cms.types.ts` L145–L152	verbatim
`validateContentData` + private `validateField`	upstream `src/types/cms.types.ts` L155–L230	verbatim
`VALID_STATUS_TRANSITIONS`	upstream `src/types/cms.types.ts` L134–L142	verbatim

Requirements with no source line

Requirement	Justification
`createCmsPlugin` factory + `cms` ServiceRegistry slot	Every other genesis `api-plugin-*` ships a `definePlugin()` factory wiring its primary service into the registry. Matching the convention costs <50 lines and aligns with `enterprise/api-plugin-cms.md` §3 "Clarify identity → wrap in `definePlugin()`".
`CmsPluginOptionsSchema` (Zod)	Genesis-wide policy: every public option bundle is Zod-validated at the boundary (CLAUDE.md).
`Clock` / `IdGenerator` injection	Genesis-wide policy: no `new Date()` in hot paths, no non-deterministic ID generation in tests (CLAUDE.md "Code Organization"). Default factory mirrors upstream behavior byte-for-byte.
OTel instrument bundle	Genesis-wide policy: every plugin emits OTel metrics from its production hot path and asserts them with an in-memory `MeterProvider`.
100% test coverage	Genesis-wide policy, not package-specific.

Verification approach

Every requirement in the spec delta is pinned by concrete it(...) titles. Test files that will exist after this change ships:

src/engine/cms-engine.test.ts — covers model + content CRUD, query filtering / sorting / paging, status transitions, version history, event emission, and every error-throwing path.
src/engine/cms-engine.spec-conformance.test.ts — pins type-level claims (expectTypeOf on CmsEngine's event map), determinism with injected Clock / IdGenerator, and the full CMS_CODES enumeration.
src/error-codes/error-codes.test.ts — every factory raises the expected code; cause chain is preserved; instanceof CmsError narrows.
src/routes/problem-json.test.ts — covers CmsError → 4xx/409 mapping, generic SuaveplanError → 500, non-error throwables → 500.
src/schemas/options.test.ts — Zod boundary accept/reject, default-fill behavior.
src/plugin/plugin.test.ts — factory returns valid PluginDescriptor, onInit registers cms in the ServiceRegistry, onClose clears it, invalid options raise CMS_CODES.INVALID_INPUT.
src/otel/instruments.test.ts — instruments are emitted from the engine and observed via in-memory MeterProvider.
src/types/cms.types.test.ts — generateSlug, validateContentData, VALID_STATUS_TRANSITIONS shape.
src/api-plugin-cms.spec-conformance.test.ts — every CMS.* code is thrown from at least one production path; barrel side-effect-imports the code registry.
tests/dep-graph.test.ts — pins the eight runtime workspace deps and forbids drift.

Migration impact

None — additive only. New package; no existing consumers.

8.3 KiB Raw Blame History Unescape Escape