first commit

docs/api-stack/api/api-plugin-cms/src/schemas/options.md

@@ -0,0 +1,69 @@
+# `CmsPluginOptionsSchema`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Zod schema validating the `CmsPluginOptions` bundle accepted by
+`createCmsPlugin(...)`. Boundary validation at the plugin factory
+ensures that misuse fails before the plugin reaches the registry, with
+the underlying `ZodError` preserved as the `cause` chain on the
+resulting `CmsError(CMS.INVALID_INPUT)`. The schema is intentionally
+minimal — only `clock` and `idGenerator` are accepted today — and both
+fields are passed through as `unknown` because Zod cannot usefully
+type-check arbitrary function signatures. The runtime `typeof ===
+"function"` guard inside `createCmsPlugin` is the actual gate.
+
+## Features
+
+- Boundary validation for `CmsPluginOptions`.
+- `safeParse` style for opt-in error handling at the factory site.
+- `z.input` / `z.output` derived types for downstream consumers that
+  want the pre-/post-validation shapes.
+- The schema invokes `.transform(...)` so omitted fields are stripped
+  from the output rather than serialised as `undefined`.
+
+## Usage: Basic
+
+```ts
+import { CmsPluginOptionsSchema } from "@suaveplan/api-plugin-cms";
+
+const result = CmsPluginOptionsSchema.safeParse(input);
+if (!result.success) throw new Error("bad options");
+const { clock, idGenerator } = result.data;
+```
+
+## Usage: Advanced
+
+Compose with a project-level config schema that also drives logging /
+telemetry parameters:
+
+```ts
+import z from "zod";
+import { CmsPluginOptionsSchema } from "@suaveplan/api-plugin-cms";
+
+const ProjectConfigSchema = z.object({
+    cms: CmsPluginOptionsSchema,
+    logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+```
+
+## API Reference
+
+| Symbol | Description |
+|---|---|
+| `CmsPluginOptionsSchema` | Zod schema. |
+| `CmsPluginOptionsInput` | `z.input<typeof CmsPluginOptionsSchema>`. |
+| `CmsPluginOptionsResolved` | `z.output<typeof CmsPluginOptionsSchema>`. |
+
+## Implementation Notes
+
+The schema is the only Zod surface exposed by the package, so the
+conformance script's "schemas at boundaries" check is satisfied by the
+single `.safeParse(...)` call inside `src/plugin/plugin.ts`. The
+`unknown` typing of `clock` / `idGenerator` is deliberate; Zod
+`z.function()` requires arg/return schemas at parse-time which would
+force callers to construct a Zod-wrapped function — a worse ergonomics
+trade than the inline `typeof` check inside the factory.