@phtngyn/cms 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -2,12 +2,16 @@
 
 A CMS for Nuxt with an embedded Studio, collaborative editing, PostgreSQL persistence, and S3-compatible media storage. Install one module, configure your services in `cms.config.ts`, and create your first administrator in Studio. Database migrations and authentication are managed by the module.
 
+## Working on this package
+
+This is the consumer guide. For implementation changes, start at [Module](./src/Module.ts) for Nuxt registration, [Configuration](./src/Configuration.ts) and [configuration compilation](./src/internal/configuration.ts) for setup, [runtime](./src/runtime/) for delivery, and [package exports and scripts](./package.json) for the current public surface. Follow the feature into its owning package and tests before changing behavior; examples below illustrate usage rather than define the current contract. The [canonical example](../../examples/nuxt/README.md) exercises the module end to end.
+
 ## Install
 
 Requires Node.js 24, Nuxt `>=4.5.0 <5`, and Vue `>=3.6.0-rc.6 <4`. Deploy as a Node server with WebSocket support; static hosting is not supported.
 
 ```sh
-pnpm add @phtngyn/cms@beta zod
+pnpm add @phtngyn/cms@beta effect
 ```
 
 Register the module in `nuxt.config.ts`:
@@ -26,7 +30,7 @@ Create `cms.config.ts` beside `nuxt.config.ts`:
 
 ```ts
 import { defineCmsConfig } from '@phtngyn/cms/Configuration'
-import { z } from 'zod'
+import { pageSchema } from './page.schema'
 
 function env(name: string): string {
   const value = process.env[name]
@@ -44,7 +48,7 @@ export default defineCmsConfig({
       pages: {
         label: 'Page',
         route: '/:path*',
-        schema: z.object({ title: z.string().min(1) }),
+        schema: pageSchema,
         source: '.',
       },
     },
@@ -70,9 +74,100 @@ These environment variable names are examples; configuration is executable TypeS
 
 For storage using the AWS credential chain, omit `credentials`. To create a missing bucket automatically, set `provisionBucket: true` and grant bucket-creation permission. Set `media: false` to start without uploads.
 
+## 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.
+
+```sh
+CMS_URL=https://source.example.com CMS_EMAIL=admin@example.com cms content export ./content
+CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content diff ./content
+CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content plan ./content
+CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content apply ./content
+CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content plan ./seed --publish
+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.
+
+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.
+
+The command tree is intentionally shared: future CMS operations can be added beside `content` without separate executables.
+
+## Search and sharing
+
+The module installs the focused Nuxt robots, sitemap, schema.org, and SEO utility modules. Published CMS pages receive canonical, robots, social-sharing, and structured-data metadata automatically. The sitemap contains only published, indexable documents and uses their publication revision time for `lastmod`; localized variants are emitted as alternatives when they share a document key.
+
+Administrators can edit and publish site-wide SEO defaults at `/_cms/app/seo`. Editors can override search and sharing fields per document, while omitted values inherit the site-wide revision. Draft preview uses working SEO settings; ordinary website requests use published settings.
+
+The initial site-wide revision is derived from `baseUrl`. To seed explicit defaults and restrict the structured identity choices Studio offers, add `seo` to `cms.config.ts`:
+
+```ts
+seo: {
+  defaults: {
+    canonicalOrigin: 'https://example.com',
+    siteName: 'Example',
+    titleTemplate: '%s · Example',
+    defaultDescription: 'Example publishes useful things.',
+    index: true,
+    follow: true,
+    identity: {
+      type: 'Organization',
+      name: 'Example',
+      url: 'https://example.com',
+    },
+  },
+  capabilities: {
+    identityTypes: ['Organization'],
+    structuredDataTypes: ['WebPage', 'Article'],
+    generatedSocialImageTemplateIds: [],
+  },
+},
+```
+
+Keep raw robots directives and Nuxt module configuration in application code. The CMS owns semantic index/follow choices and generated page metadata; it does not accept arbitrary JSON-LD or inline HTML.
+
+## Collection schemas
+
+Collections use **Standard Schema V1** for validation and **Standard JSON Schema V1** for the input structure Studio renders. This lets you keep your chosen validation library. Both contracts must be available on the collection schema; Standard Schema validation alone cannot describe controls. Studio requests draft 2020-12 JSON Schema input, resolves non-recursive local references, and runs the original validator when validating documents.
+
+For a validator that already implements both standards, pass it directly as `schema`. Otherwise, adapt its validator and input/output JSON Schema converters:
+
+```ts
+const pageSchema = {
+  '~standard': {
+    ...validator['~standard'],
+    jsonSchema: {
+      input: () => inputJsonSchema,
+      output: () => outputJsonSchema,
+    },
+  },
+}
+```
+
+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.
+
+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 { Effect, Schema } from 'effect'
+import { CalendarDate, field } from '@phtngyn/cms/DocumentModel'
+
+const pageSchema = Schema.Struct({
+  description: field(Schema.String.annotate({ default: '' }), { input: 'textarea' }).pipe(
+    Schema.withDecodingDefaultKey(Effect.succeed('')),
+  ),
+  publishedAt: Schema.optionalKey(field(CalendarDate, { label: 'Published on' })),
+  title: Schema.NonEmptyString,
+})
+```
+
+Use `Schema.optionalKey` for optional fields and `Schema.Finite` for numeric fields. An encoded `default` annotation supplies Studio's initial value; `Schema.withDecodingDefaultKey` applies that default during validation. `CalendarDate` validates calendar dates stored as `YYYY-MM-DD` strings. `field` adds presentation annotations to the encoded side of an Effect schema.
+
+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.
+
 ## Start editing
 
-1. Run `pnpm dev` and open `http://localhost:3000/_cms/app`.
+1. Start your Nuxt application and open its `/_cms/app` route. In this repository, `pnpm dev` runs the canonical example at `http://localhost:3000/_cms/app`.
 2. Enter your initialization token and create the first administrator. Initialization then closes.
 3. Create a page in Studio, edit it, and publish it. The module provides page routing and rendering; your app must render `<NuxtPage />` in `app/app.vue` if it has a custom app shell. Existing app routes can provide custom page layouts.
 
@@ -86,14 +181,10 @@ Draft delivery requires the current Studio session and document access permissio
 
 ## Customize
 
-- Define collections with Zod in `documents.collections`. Import `field` from `@phtngyn/cms/DocumentModel` to add field labels and input hints.
+- Define collections with Effect Schema in `documents.collections`. Import `field` from `@phtngyn/cms/DocumentModel` to add field labels and input hints.
 - Use the auto-imported `useDocument` and `useDocumentQuery` composables and `DocumentRenderer`, `DocumentScope`, and `DocumentField` components for custom rendering.
 - Import `defineCmsBlock` from `@phtngyn/cms/Authoring` to declare editable props and slots in your Nuxt Vue components.
-- Optionally provide `initialSources` to import Markdown documents once when the installation is first claimed.
-
-## License
-
-Proprietary. Copyright (c) 2026 Phat (phtngyn). All rights reserved. Use, copying, modification, and redistribution require prior written permission. Third-party components retain their own licenses.
+- Import Markdown folders with `cms content plan` and `cms content apply` after creating the first administrator.
 
 ## Studio and authoring during development
 
@@ -113,7 +204,7 @@ A collection can restrict available component blocks:
 pages: {
   label: 'Page',
   route: '/:path*',
-  schema: z.object({ title: z.string() }),
+  schema: Schema.Struct({ title: Schema.String }),
   body: {
     blocks: ['content-hero'],
     groups: ['Editorial'],
@@ -131,6 +222,8 @@ String props can declare `input: 'image'` or `input: 'link'`. Studio uses the ex
 
 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.
 
+For repeatable cards or chapters with formatted copy, give the parent a blocks slot restricted to an item block. Declare the item's title, icon, link, and layout choices as props, and its copy as a `rich-text` slot. Studio keeps each child block's identity and order, so the item needs no separate `id` prop. The [example section](../../examples/nuxt/app/components/documents/ContentSection.vue) hosts repeatable [cards](../../examples/nuxt/app/components/documents/ContentCard.vue); the English and German homepages show their Markdown source.
+
 Use object props for structured data and slots for composed content:
 
 ```ts
@@ -158,4 +251,111 @@ Every list item needs a required `id: string` in its Vue type. Studio generates
 
 Collaboration merges object fields and list-item fields independently. List ordering is separate from item values; simultaneous insertions at the same position retain both items in deterministic identity order. Removing an item takes precedence over concurrent edits to it. Competing edits to the same field use Yjs conflict resolution. Authoring schemas and controls update through the existing HMR path without reseeding content.
 
-See the example's `ContentSection.vue` for a complete component-local declaration with images, links, layout settings, repeatable features and nested blocks.
+## Headless forms
+
+Register a form under the kebab-case name of your Nuxt Vue renderer. `defineCmsForm` is a normal TypeScript helper, not a compiler macro. It declares the question types and validation rules editors may use:
+
+```ts
+import { defineCmsConfig } from '@phtngyn/cms/Configuration'
+import { defineCmsForm } from '@phtngyn/cms/Forms'
+
+// Inside your existing defineCmsConfig configuration:
+forms: {
+  'contact-form': {
+    definition: defineCmsForm({
+      label: 'Contact form',
+      fieldTypes: ['text', 'email', 'textarea', 'number', 'checkbox', 'select'],
+      rules: ['required', 'minLength', 'maxLength', 'min', 'max'],
+    }),
+    onSubmit: async ({ form, values }) => {
+      // Server only: deliver or persist validated answers here.
+      // values are keyed by stable question IDs; form.steps contains their labels.
+    },
+  },
+},
+```
+
+Create `ContactForm.vue` with an optional `cmsForm?: CmsFormDefinition` prop. The registration supplies its Studio authoring controls; do not also declare `defineCmsBlock` for that renderer. Forms appear in the Forms block group and follow collection block permissions. Editors add steps, questions, choices and permitted rules in the property panel. One step produces a single-step form. Question and option IDs are managed by Studio; labels can change without changing identities. Select answers contain option IDs. There is no website input markup or CSS supplied by CMS.
+
+A valid authored form receives `cmsForm` from `DocumentRenderer`. Incomplete drafts do not; show a helpful placeholder until the form is valid. Mount your custom form contents only when that definition exists:
+
+```ts
+import type { CmsFormDefinition } from '@phtngyn/cms/Forms'
+import { useCmsForm } from '@phtngyn/cms/Forms'
+
+const props = defineProps<{ definition: CmsFormDefinition }>()
+const {
+  fields,
+  steps,
+  values,
+  errors,
+  currentStep,
+  stepIndex,
+  isFirstStep,
+  isLastStep,
+  isSubmitting,
+  isSuccess,
+  isPreview,
+  error,
+  fieldState,
+  next,
+  previous,
+  validate,
+  submit,
+  reset,
+} = useCmsForm(() => props.definition)
+```
+
+The composable accepts a value, ref, or getter and returns destructurable refs and functions. Use `fieldState(field)` for each visible question. It returns the current `value`, `error`, normalized `setValue(input)`, and `inputAttrs` with an ID, name, required state, and ARIA error/help references. Render help with `id=state.helpId` and errors with `id=state.errorId` so those references have matching elements. For example, a native control can use `v-bind="state.inputAttrs"`, `:value="state.value"`, and `@input="state.setValue($event.target.value)"`. Checkbox controls should pass their checked boolean. Valid number answers become numbers, empty answers become null, and invalid number text remains visible to validation. Empty optional answers reach the server handler as null. `values` and `errors` remain available for custom renderers; `_form` holds a form-wide error. Render accessible labels, error announcements, progress, and focus behavior in your application.
+
+`next()` validates the current step, `previous()` preserves answers, and `submit()` validates every step and returns whether submission succeeded. A required checkbox must be checked.
+
+Definition replacements preserve answers for matching IDs and field types within the same form, clear validation state, and cancel pending client requests. `reset()` clears answers and submission state. The composable prevents overlapping submissions and repeat submission after success until reset. Scope disposal cancels client work. Cancellation cannot undo a server handler that has already started. An optional `submit(payload, signal)` transport override supports advanced integrations; it must return `CmsFormResult` and preserve server-side validation.
+
+The endpoint resolves the current published form and checks its exact serialized revision, including capabilities and question settings. Stale pages must reload. Draft preview validates locally without invoking the handler. Invalid structure prevents publication; invalid answers and unknown answer keys never reach the handler. Dynamic editor-created questions have runtime-validated answer types, not compile-time-known answer keys.
+
+Requests are limited to 128 KiB and 60 submissions per minute per server process, shared across forms. Browser requests with a foreign Origin are rejected. For deployments with multiple replicas or stronger spam protection, enforce a shared limit or challenge at your edge. There is no automatic retry, durable deduplication, inbox, email delivery, upload, branching, or save-and-resume in this release. Application handlers should account for retries after an uncertain network outcome. Configuration changes use Nuxt's restart lifecycle.
+
+See `examples/nuxt/app/components/FormContents.vue` for a Tailwind-rendered example. Its server handler acknowledges submissions without storing answers.
+
+## Website languages
+
+Declare languages and developer-owned website strings together in `cms.config.ts`:
+
+```ts
+i18n: {
+  defaultLocale: 'en',
+  fallbackLocale: 'en',
+  prefixDefaultLocale: false,
+  locales: {
+    en: { name: 'English', messages: {
+      navigation: { home: 'Home' },
+      footer: { copyright: '© {year} Acme' },
+    } },
+    de: { name: 'Deutsch', messages: {
+      navigation: { home: 'Startseite' },
+    } },
+  },
+},
+```
+
+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.
+
+Use the auto-imported composable in website components:
+
+```ts
+const { t, locale, localePath, switchLocalePath } = useCmsI18n()
+const navigation = computed(() => [{ label: t('navigation.home'), to: localePath('/') }])
+const germanVersion = computed(() => switchLocalePath('de'))
+t('footer.copyright', { year: 2026 })
+```
+
+`locale` is a read-only computed value derived from the current URL, including in Studio's website preview. `localePath(path, code?)` builds a path using the configured locale prefix policy; the code defaults to the current locale. `switchLocalePath(code)` changes the current URL's prefix while preserving its query and fragment. For documents with different authored slugs, pass the destination's unprefixed path as the second argument: `switchLocalePath('de', '/ueber-uns')`. The CMS does not infer relationships between different slugs. The Nuxt module sets the document's HTML `lang` automatically. Lists can explicitly pass `locale.value` to `useDocumentQuery`.
+
+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.
+
+## License
+
+Proprietary. Copyright (c) 2026 Phat (phtngyn). All rights reserved. Use, copying, modification, and redistribution require prior written permission. Third-party components retain their own licenses.

package/bin/cms.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js'

package/package.json

@@ -1,5 +1,8 @@
 {
   "author": "Phat (phtngyn)",
+  "bin": {
+    "cms": "./bin/cms.mjs"
+  },
   "description": "A Nuxt CMS with an embedded Studio, collaborative editing, PostgreSQL, and S3-compatible media storage.",
   "homepage": "https://github.com/phtngyn/cms",
   "keywords": [
@@ -14,9 +17,10 @@
     "directory": "packages/nuxt"
   },
   "name": "@phtngyn/cms",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "type": "module",
   "files": [
+    "bin",
     "studio",
     "src",
     "README.md",
@@ -38,38 +42,49 @@
     "./DocumentModel": {
       "types": "./src/DocumentModel.d.ts",
       "import": "./src/DocumentModel.js"
+    },
+    "./I18n": {
+      "types": "./src/I18n.d.ts",
+      "import": "./src/I18n.js"
+    },
+    "./Forms": {
+      "types": "./src/Forms.d.ts",
+      "import": "./src/Forms.js"
     }
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1127.0",
-    "@comark/nuxt": "^0.6.2",
-    "@comark/vue": "^0.6.2",
-    "@effect/platform-node-shared": "^4.0.0-rc.112",
-    "@effect/sql-pg": "^4.0.0-rc.112",
-    "@hocuspocus/server": "^4.6.0",
+    "@aws-sdk/client-s3": "^3.1131.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",
+    "@hocuspocus/server": "^4.7.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/schema": "^4.5.2",
+    "@nuxtjs/robots": "^6.2.2",
+    "@nuxtjs/sitemap": "^8.5.1",
     "@tiptap/core": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",
     "@tiptap/y-tiptap": "^3.0.9",
-    "@vue/compiler-sfc": "^3.6.0-rc.7",
-    "better-auth": "^1.7.3",
-    "comark": "^0.6.2",
+    "@vue/compiler-sfc": "^3.6.0-rc.8",
+    "better-auth": "^1.7.4",
+    "comark": "^0.7.0",
     "diff": "^9.0.0",
     "drizzle-orm": "^1.0.0-rc.5-169397b",
-    "effect": "^4.0.0-rc.112",
+    "effect": "^4.0.0-rc.115",
     "h3": "^1.15.11",
     "jiti": "^2.7.0",
     "nitropack": "^2.13.4",
+    "nuxt-schema-org": "^6.3.1",
+    "nuxt-seo-utils": "^8.5.0",
     "pg": "^8.23.0",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
-    "vite": "^8.2.2",
+    "vite": "^8.3.0",
     "vue-component-meta": "^3.3.11",
-    "yjs": "^13.6.32",
-    "zod": "^4.5.4"
+    "yjs": "^13.6.32"
   },
   "peerDependencies": {
     "nuxt": ">=4.5.0 <5.0.0",
     "vue": ">=3.6.0-rc.6 <4.0.0"
   }
-}
+}