@phtngyn/cms 0.2.0-beta.4 → 0.2.0-beta.6

package/README.md

@@ -39,7 +39,6 @@ export default defineCmsConfig({
         label: 'Page',
         route: '/:path*',
         schema: pageSchema,
-        source: '.',
       },
     },
   },
@@ -80,6 +79,8 @@ Use the supported lifecycle before starting Nuxt:
 
 ```sh
 cms dev doctor
+cms configuration check
+cms --json configuration check > configuration-report.json
 CMS_EMAIL=admin@example.test CMS_PASSWORD=admin@example.test cms dev bootstrap --content ./content --publish
 cms dev reset --database --media
 cms dev reset --database --media --yes --bootstrap --content ./content --publish
@@ -91,6 +92,10 @@ All lifecycle commands accept `--root <directory>`, `--env-file <path>`, `--verb
 
 `reset` is a dry run unless `--yes` is present. It refuses to run while the configured CMS is live and can remove only the configured PostgreSQL schema and S3 prefix. Choose `--database`, `--media`, or both.
 
+`configuration check` is the read-only local and CI gate for authored configuration changes. It compares `cms.config.ts` plus discovered blocks and forms with the installation's accepted serializable catalog, validates every authored and published Document, and emits the same underlying report used during startup. Human output names each required remediation; `--json` emits the versioned report without presentation text. Compatible reports exit successfully. Reports with affected Documents exit unsuccessfully, so CI can use the command directly.
+
+Runtime startup records the first valid catalog and later compatible candidates. It never rewrites Documents to make a candidate fit. Field renames or removals, route or locale changes, unavailable blocks, narrower block permissions, and narrower form capabilities must be resolved through a separate explicit content change before startup can adopt the candidate.
+
 ## Content CLI
 
 The installed package provides a `cms` command for importing a plain Markdown folder, exporting Studio-authored Markdown, and moving content between running CMS installations. Create the first administrator in Studio, then sign in to the CLI with that administrator's email and password. The CLI prompts for the site URL, administrator email, and password when they are missing. For noninteractive use, set `CMS_URL`, `CMS_EMAIL`, and `CMS_PASSWORD`; `--url` and `--email` can replace the first two variables. Use HTTPS outside localhost.
@@ -104,11 +109,11 @@ CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content plan
 CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content apply ./seed --publish
 ```
 
-Export writes each authored source at its CMS path and a `.cms-content.json` index with content hashes and the exact-revision publication state. Commit both to Git to review changes. Export refuses to replace locally edited Markdown or index entries. It does not delete files that disappeared from the CMS; remove stale files and index entries yourself after review. `diff` compares local Markdown and publication state with the current target and reports target-only documents. `plan` validates the whole incoming set and lists creates, updates, publications, and conflicts without writing. `apply` plans again, then commits the batch atomically against the generation it just inspected. Run `plan` and `diff` before applying, especially when targeting another environment.
+Export chooses deterministic filesystem paths and writes a version 2 `.cms-content.json` index containing each document's stable identity, revisioned placement, revision ID, publication state, and content hash. Filesystem paths are only an import/export concern; moving a document in Studio does not rename anything in core document state. Commit the Markdown and index together to review changes. Export preserves indexed paths when possible, refuses to replace locally edited Markdown or index entries, and does not delete files that disappeared from the CMS. Remove stale files and index entries yourself after review. `diff` compares local Markdown, placement, and publication state with the current target and reports target-only documents. `plan` validates the whole incoming set and lists creates, updates, publications, unpublications, and conflicts without writing. `apply` plans again, then commits the batch atomically against the generation it just inspected. Run `plan` and `diff` before applying, especially when targeting another environment.
 
 The export index and every indexed Markdown path must stay inside the selected content directory without symlinked path components. Import and export reject symlinks at those boundaries.
 
-For a folder without `.cms-content.json`, the CLI reads nested `.md` and `.mdc` files and uses folder-relative document paths. These sources are eligible for publication with `--publish`. Imports create drafts by default. Existing content with different Markdown is a conflict until you pass `--overwrite` to `plan` and `apply`. For an exported folder, `--publish` publishes only index entries marked `published: true`; without it, they remain drafts on the target. A newly imported draft does not unpublish an older target revision. The CLI does not delete target documents or move a target-only document. A concurrent change after planning causes `apply` to fail; review and retry.
+For a folder without `.cms-content.json`, the CLI reads nested `.md` and `.mdc` files and infers an initial collection, locale, parent, and slug from folders. A collection or locale directory is optional when configuration makes it unambiguous; `index.md` represents the home document or the entry represented by its containing folder. This inference happens only on the first unindexed import. These sources are eligible for publication with `--publish`. Imports create drafts by default. Existing content with different Markdown is a conflict until you pass `--overwrite` to `plan` and `apply`. For an exported folder, `--publish` synchronizes the indexed publication state: entries marked `published: true` are published and entries marked `published: false` are unpublished. Without it, imported changes remain drafts and existing target publication stays unchanged. The CLI does not delete target documents or move a target-only document. A concurrent change after planning causes `apply` to fail; review and retry.
 
 The command tree is intentionally shared: future CMS operations can be added beside `content` without separate executables.
 
@@ -134,7 +139,7 @@ const document = await client.readDocument('8c62d2a7-b839-450a-bc08-5eccb420dc60
 await client.export({ directory: './content' })
 ```
 
-Plans expose creates, updates, publications, conflicts, issues, unchanged entries, and target-only sources. They are bound to their client, source, options, and generation; `apply(plan)` never replans. `readDocument(id)` returns the authored Markdown and exact publication state. `CmsContentError.code` provides stable authentication, not-found, conflict, validation, generation, filesystem, response, and network failure categories.
+Plans expose creates, updates, publications, unpublications, conflicts, issues, unchanged entries, and target-only sources. They are bound to their client, source, options, and generation; `apply(plan)` never replans. `readDocument(id)` returns the authored Markdown and exact publication state. `CmsContentError.code` provides stable authentication, not-found, conflict, validation, generation, filesystem, response, and network failure categories.
 
 ## Search and sharing
 
@@ -205,24 +210,35 @@ const pageSchema = {
 }
 ```
 
-Supply actual draft 2020-12 schemas from the chosen library, using its input and output conversion modes respectively. Studio reads the input structure; the validator remains responsible for execution. A missing input converter produces a configuration error naming Standard JSON Schema V1. Foreign schemas use JSON Schema `title`, `description`, `default`, and `x-cms-input` for presentation.
+Supply actual draft 2020-12 schemas from the chosen library, using its input and output conversion modes respectively. Studio reads the input structure; the validator remains responsible for execution. A missing input converter produces a configuration error naming Standard JSON Schema V1. Foreign schemas use JSON Schema `title`, `description`, `default`, `x-cms-input`, and `x-cms-options` for presentation.
 
 Effect schemas are also accepted directly. The CMS derives Studio inputs from their encoded structure and runs the original decoder, preserving defaults, transformations, and asynchronous validation. Decoders must not require external Effect services, and their output must be a JSON-compatible object.
 
 ```ts
 import { Schema } from 'effect'
-import { CalendarDate, field } from '@phtngyn/cms/DocumentModel'
+import { CalendarDate, field, managedMediaReference } from '@phtngyn/cms/DocumentModel'
 
 const pageSchema = Schema.Struct({
   description: field(Schema.String, { default: '', input: 'textarea' }),
   publishedAt: Schema.optionalKey(field(CalendarDate, { label: 'Published on' })),
+  contributors: field(
+    Schema.Array(
+      Schema.Struct({
+        id: Schema.String,
+        name: Schema.NonEmptyString,
+        role: field(Schema.String, { default: 'Contributor' }),
+      }),
+    ),
+    { default: [], label: 'Contributors' },
+  ),
+  socialImage: Schema.optionalKey(managedMediaReference),
   title: Schema.NonEmptyString,
 })
 ```
 
-Use `Schema.optionalKey` for optional fields and `Schema.Finite` for numeric fields. A `field` default supplies Studio's initial value and applies only when the containing key is absent; invalid explicit values still fail. `CalendarDate` validates calendar dates stored as `YYYY-MM-DD` strings. Advanced Effect schemas, transformations, and defaults remain supported directly. `effect` is an intentional runtime dependency and is installed explicitly because authored schemas expose its public types.
+Use `Schema.optionalKey` for optional fields, `Schema.NullOr` for explicit nulls, and `Schema.Finite` for numeric fields. A `field` default supplies Studio's initial value and applies only when the containing key is absent; invalid explicit values still fail. `field` can also give enum values distinct human labels through `options`. `CalendarDate` validates calendar dates stored as `YYYY-MM-DD` strings. Advanced Effect schemas, transformations, and defaults remain supported directly. `effect` is an intentional runtime dependency and is installed explicitly because authored schemas expose its public types.
 
-Studio supports strings, calendar dates, finite numbers, booleans, string arrays, choices, and nested objects. Non-recursive local references are resolved. Ambiguous unions, structural intersections, recursive schemas, and unsupported field shapes fail configuration rather than producing incomplete forms.
+Studio supports strings, calendar dates, finite numbers, booleans, string arrays, choices, nested objects, repeatable objects, document references, and managed-media references. Repeatable object schemas must contain a required string `id`; Studio owns that identity and provides add, duplicate, remove, and reorder operations. `documentReference` and `managedMediaReference` store identity-backed source strings and project them to current routes or URLs for preview and delivery. Non-recursive local references are resolved. Ambiguous unions, structural intersections, recursive schemas, and unsupported field shapes fail configuration rather than producing incomplete forms.
 
 ## Start editing
 
@@ -245,7 +261,7 @@ Draft delivery requires the current Studio session and document access permissio
 - Import `defineCmsBlock` from `@phtngyn/cms/Authoring` to declare editable props and slots in your Nuxt Vue components.
 - Import Markdown folders with `cms content plan` and `cms content apply` after creating the first administrator.
 
-Nuxt generates `#cms/types` whenever configuration, collection schemas, or authored blocks change. It includes collection, form, block, locale, message-key, and interpolation-parameter types. Collection schema outputs flow through `useDocument<'pages'>()` and `useDocumentQuery()`, including typed filter and sort paths. Registered form names and configured capabilities narrow `CmsFormDefinition<'contact-form'>`.
+Nuxt generates `#cms/types` whenever configuration, collection schemas, or authored blocks change. It includes collection, form, block, locale, message-key, and interpolation-parameter types. Collection schema outputs, including repeatable objects and references, flow through `useDocument<'pages'>()` and `useDocumentQuery()`. Filtering and sorting remain limited to typed scalar paths and scalar lists; repeatable-object predicates are intentionally excluded. Registered form names and configured capabilities narrow `CmsFormDefinition<'contact-form'>`.
 
 ```ts
 import type { CmsCollection, CmsFormDefinition, CmsLocale } from '#cms/types'
@@ -269,7 +285,9 @@ An open editor reads the new catalog without reseeding content or replacing its
 
 ## Component authoring and collection permissions
 
-Keep the Vue props, slots, defaults, and `defineCmsBlock` declaration together in the component's `<script setup lang="ts">`. Only declared fields and regions appear in Studio. Text regions accept plain text; rich-text regions offer only their declared `features`. Optional slots can be removed and added again. Initial content seeds new blocks; it never overwrites existing content when a declaration changes. Render optional slot wrappers conditionally to avoid empty layout space.
+Keep the Vue props, slots, defaults, and `defineCmsBlock` declaration together in the component's `<script setup lang="ts">`. Only declared fields and regions appear in Studio. Text regions accept one plain paragraph. Inline-text regions keep that single-paragraph shape while offering their declared inline formatting `features`. Rich-text regions accept multiple paragraphs and offer only their declared inline and list `features`. Optional slots can be removed and added again. Initial content seeds new blocks; it never overwrites existing content when a declaration changes. Render optional slot wrappers conditionally to avoid empty layout space.
+
+Render declared fields through ordinary Vue slot outlets. Studio follows each slot's rendered content through application components automatically: clicking a card title selects its title content, clicking its description selects the description, and clicking the remaining card surface selects the card block. Nuxt rejects an authored block when a declared slot has no matching outlet, so rendered fields cannot silently disappear from preview selection.
 
 A collection can restrict available component blocks:
 
@@ -291,7 +309,7 @@ Clearing an optional property removes its stored override, so a Vue default can
 
 ### Images, links, and composition
 
-String props can declare `input: 'image'` or `input: 'link'`. Studio uses the existing media library for image selection/upload and the document catalog for page links. Values remain ordinary URL strings: internal links store the selected document's public path. Image descriptions belong to a separate Vue prop; Studio does not invent an alt-text field or change your component's rendering. URL syntax and allowed schemes are checked before publication, and semantic props participate in the existing document/media reference index, including inside objects and lists. Changing a target's public path requires updating its links; references do not silently retarget by title.
+String props can declare `input: 'image'` or `input: 'link'`. Studio uses the existing media library for image selection/upload and the document catalog for internal links. Internal selections are stored as `cms-document:<uuid>?route=<last-known-route>`: identity remains authoritative while the readable route provides a fallback when the target is unavailable. Studio resolves these references against authored documents and website delivery resolves them against published documents, so moving a target changes rendered links without rewriting Markdown. External links remain ordinary URLs. Image descriptions belong to a separate Vue prop; Studio does not invent an alt-text field or change your component's rendering. URL syntax and allowed schemes are checked before publication, and semantic props participate in the existing document/media reference index, including inside objects and lists.
 
 Slots with `input: 'blocks'` accept nested components. Optional `blocks` and `groups` selectors restrict direct children; omitting both permits all collection-allowed blocks. Collection permissions apply at every depth. Studio offers insertion, selection, deletion and sibling reordering inside each region. Existing content is retained when a schema change makes it invalid.
 
@@ -414,7 +432,7 @@ i18n: {
 },
 ```
 
-Locale codes also define the first directory of document source paths: `en/index.md` serves `/`, and `de/index.md` serves `/de`. Collection source matching starts after that directory. Markdown contains the editor-authored language already; it needs no translation key. Markdown and source paths remain stored in document revisions, with collaborative working edits checkpointed into Markdown. Import a Markdown folder with the admin CLI; subsequent changes require another plan and apply, with `--overwrite` for different Markdown.
+Locale is part of stable document identity and route derivation. For an unindexed import, locale codes may be inferred from the first directory (`en/index.md`, `de/index.md`); the generated export index preserves the identity afterward. Markdown contains the editor-authored language already and needs no translation key. Revisions store identity, placement, and Markdown, while collaborative working edits checkpoint into Markdown. Import a Markdown folder with the admin CLI; subsequent changes require another plan and apply, with `--overwrite` for different Markdown.
 
 Use the auto-imported composable in website components:
 
@@ -429,7 +447,7 @@ t('footer.copyright', { year: 2026 })
 
 Message keys receive generated TypeScript completion. Dictionaries contain nested plain strings; dots are reserved for key paths. Named `{parameters}` accept strings and numbers; missing parameters remain visible. Messages fall back from the URL locale to `fallbackLocale`, then to the key. Omit `fallbackLocale` (or set it to `null`) to disable fallback. The same explicit fallback policy applies to document lookup. Development warns about missing requested-locale messages. Render messages as text, and use native `Intl` for date and number formatting.
 
-Only validated public i18n data enters the website bundle. Installation credentials and handlers stay server-side. Small dictionaries can stay inline; larger ones can be imported into the same config. Configuration changes restart Nuxt. Omitting `i18n` preserves unlocalized source paths; the composable returns an empty locale and untranslated keys.
+Only validated public i18n data enters the website bundle. Installation credentials and handlers stay server-side. Small dictionaries can stay inline; larger ones can be imported into the same config. Configuration changes restart Nuxt. Omitting `i18n` creates unlocalized document identities; the composable returns an empty locale and untranslated keys.
 
 ## License
 

package/package.json

@@ -17,7 +17,7 @@
     "directory": "packages/nuxt"
   },
   "name": "@phtngyn/cms",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.6",
   "type": "module",
   "files": [
     "bin",
@@ -62,11 +62,11 @@
     }
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1131.0",
+    "@aws-sdk/client-s3": "^3.1136.0",
     "@comark/nuxt": "^0.7.0",
     "@comark/vue": "^0.7.0",
-    "@effect/platform-node-shared": "^4.0.0-rc.115",
-    "@effect/sql-pg": "^4.0.0-rc.115",
+    "@effect/platform-node-shared": "^4.0.0-rc.116",
+    "@effect/sql-pg": "^4.0.0-rc.116",
     "@hocuspocus/server": "^4.7.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/schema": "^4.5.2",
@@ -76,13 +76,13 @@
     "@tiptap/core": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",
     "@tiptap/y-tiptap": "^3.0.9",
-    "@vue/compiler-sfc": "^3.6.0-rc.8",
-    "better-auth": "^1.7.4",
+    "@vue/compiler-sfc": "^3.6.0-rc.9",
+    "better-auth": "^1.7.5",
     "c12": "^4.0.0-rc.1",
     "comark": "^0.7.0",
     "diff": "^9.0.0",
     "drizzle-orm": "^1.0.0-rc.5-169397b",
-    "effect": "^4.0.0-rc.115",
+    "effect": "^4.0.0-rc.116",
     "h3": "^1.15.11",
     "jiti": "^2.7.0",
     "nitropack": "^2.13.4",

package/src/ApplicationTypes.d.ts

@@ -1,6 +1,6 @@
 import { a as FormStep, n as FormDefinition, r as FormField } from "./Forms-R0HoTR-o.js";
 import { a as CmsMessageParameters, i as CmsMessageKey, r as CmsLocale } from "./I18n-zbqpWxki.js";
-import { n as DeliveryDocumentPage, t as DeliveryDocument } from "./types-DutFRtaG.js";
+import { n as DeliveryDocumentPage, t as DeliveryDocument } from "./types-DZ0IV-Ow.js";
 import { Schema } from "effect";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/ApplicationTypes.d.ts
@@ -60,8 +60,8 @@ type Scalar = boolean | number | string | null;
 type FieldPaths<Value> = Value extends ReadonlyArray<unknown> ? never : Value extends object ? { [Key in Extract<keyof Value, string>]: NonNullable<Value[Key]> extends Scalar | ReadonlyArray<Scalar> ? Key : `${Key}.${FieldPaths<NonNullable<Value[Key]>>}`; }[Extract<keyof Value, string>] : never;
 type CollectionDataField<Name extends CmsCollectionName> = Extract<FieldPaths<CmsCollection<Name>['data']>, string>;
 type FieldValue<Value, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Value ? FieldValue<NonNullable<Value[Head]>, Tail> : never : Path extends keyof Value ? Value[Path] : never;
-type DocumentField<Name extends CmsCollectionName> = 'collection' | 'description' | 'id' | 'key' | 'locale' | 'path' | 'source.path' | 'title' | CollectionDataField<Name> | `data.${CollectionDataField<Name>}`;
-type DocumentFieldValue<Name extends CmsCollectionName, Field extends DocumentField<Name>> = Field extends `data.${infer Path}` ? FieldValue<CmsCollection<Name>['data'], Path> : Field extends CollectionDataField<Name> ? FieldValue<CmsCollection<Name>['data'], Field> : Field extends 'collection' ? Name : Field extends 'locale' ? CmsLocale : Field extends 'source.path' ? CmsCollection<Name>['source']['path'] : Field extends keyof CmsCollection<Name> ? CmsCollection<Name>[Field] : never;
+type DocumentField<Name extends CmsCollectionName> = 'collection' | 'description' | 'id' | 'key' | 'locale' | 'path' | 'title' | CollectionDataField<Name> | `data.${CollectionDataField<Name>}`;
+type DocumentFieldValue<Name extends CmsCollectionName, Field extends DocumentField<Name>> = Field extends `data.${infer Path}` ? FieldValue<CmsCollection<Name>['data'], Path> : Field extends CollectionDataField<Name> ? FieldValue<CmsCollection<Name>['data'], Field> : Field extends 'collection' ? Name : Field extends 'locale' ? CmsLocale : Field extends keyof CmsCollection<Name> ? CmsCollection<Name>[Field] : never;
 type FilterValue<Value> = NonNullable<Value> extends ReadonlyArray<infer Item> ? Extract<NonNullable<Item>, Scalar> | ReadonlyArray<Extract<NonNullable<Item>, Scalar>> : Extract<NonNullable<Value>, Scalar> | ReadonlyArray<Extract<NonNullable<Value>, Scalar>>;
 type CmsDocumentQueryWhere<Name extends CmsCollectionName> = { readonly [Field in DocumentField<Name>]?: FilterValue<DocumentFieldValue<Name, Field>>; };
 export interface CmsDocumentQuerySort<Name extends CmsCollectionName> {

package/src/Authoring.d.ts

@@ -4,13 +4,16 @@ export type CmsBlockProp<Value> = {
   readonly label: string;
   readonly help?: string;
 } & ([NonNullable<Value>] extends [never] ? never : [NonNullable<Value>] extends [string] ? {
-  readonly input: 'text' | 'textarea' | 'select' | 'image' | 'link';
+  readonly input: 'text' | 'textarea' | 'select' | 'image' | 'link' | 'document' | 'media';
   readonly optionLabels?: Partial<Record<Extract<Value, string>, string>>;
 } : [NonNullable<Value>] extends [number] ? {
   readonly input: 'number';
 } : [NonNullable<Value>] extends [boolean] ? {
   readonly input: 'toggle';
-} : [NonNullable<Value>] extends [ReadonlyArray<infer Item>] ? Item extends {
+} : [NonNullable<Value>] extends [ReadonlyArray<infer Item>] ? [Item] extends [string] ? {
+  readonly input: 'multiselect';
+  readonly optionLabels?: Partial<Record<Extract<Item, string>, string>>;
+} : Item extends {
   readonly id: string;
 } ? {
   readonly input: 'list';
@@ -19,18 +22,23 @@ export type CmsBlockProp<Value> = {
   readonly input: 'object';
   readonly fields: { readonly [Key in keyof NonNullable<Value>]?: CmsBlockProp<NonNullable<Value>[Key]>; };
 } : never);
+export type CmsInlineTextFeature = 'bold' | 'italic' | 'link' | 'code';
+export type CmsRichTextFeature = CmsInlineTextFeature | 'bullet-list';
 export type CmsBlockSlot = {
   readonly label: string;
   readonly help?: string;
 } & ({
   readonly input: 'text';
+} | {
+  readonly input: 'inline-text';
+  readonly features: ReadonlyArray<CmsInlineTextFeature>;
 } | {
   readonly input: 'blocks';
   readonly blocks?: ReadonlyArray<string>;
   readonly groups?: ReadonlyArray<string>;
 } | {
   readonly input: 'rich-text';
-  readonly features: ReadonlyArray<'bold' | 'italic' | 'link' | 'bullet-list' | 'code'>;
+  readonly features: ReadonlyArray<CmsRichTextFeature>;
 });
 export interface CmsBlockDeclaration<Props, Slots> {
   readonly label: string;