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

package/README.md

@@ -30,7 +30,7 @@ Create `cms.config.ts` beside `nuxt.config.ts`:
 
 ```ts
 import { defineCmsConfig } from '@phtngyn/cms/Configuration'
-import { Schema } from 'effect'
+import { pageSchema } from './page.schema'
 
 function env(name: string): string {
   const value = process.env[name]
@@ -48,7 +48,7 @@ export default defineCmsConfig({
       pages: {
         label: 'Page',
         route: '/:path*',
-        schema: Schema.Struct({ title: Schema.NonEmptyString }),
+        schema: pageSchema,
         source: '.',
       },
     },
@@ -74,6 +74,25 @@ 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.
@@ -109,7 +128,25 @@ Keep raw robots directives and Nuxt module configuration in application code. Th
 
 ## Collection schemas
 
-Effect schemas work directly. The CMS derives Studio inputs from their encoded structure and runs the original decoder when validating documents, preserving defaults, transformations, and asynchronous validation. Decoders must not require external Effect services, and their output must be a JSON-compatible object.
+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'
@@ -126,24 +163,6 @@ const pageSchema = Schema.Struct({
 
 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.
 
-Other libraries are supported through a schema implementing **both Standard Schema V1 and Standard JSON Schema V1**. Standard Schema supplies validation and typed output; Standard JSON Schema's `jsonSchema.input({ target: 'draft-2020-12' })` supplies the editor structure. A library that only implements validation needs an adapter adding JSON Schema conversion; Standard Schema alone cannot generate a form.
-
-For example, an existing Standard Schema validator can be adapted with its library's JSON Schema converters:
-
-```ts
-const collectionSchema = {
-  '~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. Foreign schemas use JSON Schema `title`, `description`, `default`, and `x-cms-input` for presentation. The CMS reads only the input structure and retains the original validator for execution.
-
 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
@@ -165,12 +184,7 @@ Draft delivery requires the current Studio session and document access permissio
 - 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.
-
-For a folder of published Markdown files, import `seedFromDirectory` from `@phtngyn/cms/Seed` and set
-`initialSources: seedFromDirectory(new URL('./seed/', import.meta.url))` in `cms.config.ts`.
-The folder is read when Nuxt loads the configuration. Paths within it become document source paths;
-for example, `seed/en/index.md` becomes `en/index.md`. Files are published on the first claim.
+- Import Markdown folders with `cms content plan` and `cms content apply` after creating the first administrator.
 
 ## Studio and authoring during development
 
@@ -208,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
@@ -235,8 +251,6 @@ 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:
@@ -283,6 +297,7 @@ const {
   isSuccess,
   isPreview,
   error,
+  fieldState,
   next,
   previous,
   validate,
@@ -291,7 +306,9 @@ const {
 } = useCmsForm(() => props.definition)
 ```
 
-The composable accepts a value, ref, or getter and returns destructurable refs and functions. Bind controls to `values[field.id]`. Number answers must be numbers or null, checkbox answers booleans, and other answers strings. Empty optional answers reach the server handler as null; a required checkbox must be checked. `next()` validates the current step, `previous()` preserves answers, and `submit()` validates every step and returns whether submission succeeded. Validation errors are keyed by question ID; `_form` holds a form-wide error. Render accessible labels, error announcements, progress, and focus behavior in your application.
+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.
 
@@ -322,18 +339,18 @@ 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. Seed files import once; changing them does not synchronize an existing database.
+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 } = useCmsI18n()
-const navigation = computed(() => [{ label: t('navigation.home'), to: locale.value === 'de' ? '/de' : '/' }])
+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 })
-useHead({ htmlAttrs: { lang: locale } })
 ```
 
-`locale` is a read-only computed value derived from the current URL, including in Studio's website preview. Switch languages by navigating to a localized URL. For documents with different authored slugs, supply their actual destinations. Lists can explicitly pass `locale.value` to `useDocumentQuery`.
+`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.
 

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.2",
+  "version": "0.1.0-beta.3",
   "type": "module",
   "files": [
+    "bin",
     "studio",
     "src",
     "README.md",
@@ -39,10 +43,6 @@
       "types": "./src/DocumentModel.d.ts",
       "import": "./src/DocumentModel.js"
     },
-    "./Seed": {
-      "types": "./src/Seed.d.ts",
-      "import": "./src/Seed.js"
-    },
     "./I18n": {
       "types": "./src/I18n.d.ts",
       "import": "./src/I18n.js"

package/src/{Configuration-CA_jvQKG.js → Configuration-CDMYfTre.js}

@@ -1,6 +1,6 @@
 import { r as FormCapabilities } from "./Forms-CfcI3tPU.js";
-import { c as resolveCmsComarkAttributes, d as createCmsComarkRenderData, l as withCmsComarkProps, r as formStructureIssues, s as projectCmsEditorComponentAttributes } from "./Forms-DxbkU3_5.js";
-import { C as MarkdownNode, Dt as Locale, Et as CollectionName, Ot as SourceDirectory, Tt as AddressPattern, n as CmsMarkdownDocument } from "./models-DwYioyNV.js";
+import { c as resolveCmsComarkAttributes, d as createCmsComarkRenderData, l as withCmsComarkProps, r as formStructureIssues, s as projectCmsEditorComponentAttributes } from "./Forms-Dj6NuW66.js";
+import { Ct as CollectionName, St as AddressPattern, Tt as SourceDirectory, b as MarkdownNode, n as CmsMarkdownDocument, wt as Locale } from "./models-Bah5B3bT.js";
 import { a as createEditorNodeId, n as editorMetadata, o as editorNodeId } from "./metadata-BEZPWh-3.js";
 import { Effect, Option, Predicate, Schema } from "effect";
 import { Extension } from "@tiptap/core";
@@ -1030,4 +1030,4 @@ const MediaConfiguration = Schema.Struct({
 
 //#endregion
 export { finiteNumberAttribute as C, compactJsonAttributes as S, comarkTagForEditorMark as _, BlockAuthoring as a, encodeEditorImageAttributes as b, parseAuthoringContent as c, EditorRenderFailed as d, DOCUMENT_ENGINE_FINGERPRINT as f, EDITOR_MARK_TYPES as g, comarkToEditor as h, MediaConfiguration as i, validateCollectionBody as l, SOURCE_MAPPINGS_META_KEY as m, ComponentDefinition as n, createAuthoringDocumentValidator as o, createDocumentParser as p, DocumentConfiguration as r, createAuthoringSchema as s, AuthoringCatalog as t, EditorDocumentInvalid as u, isEditorMark as v, nonEmptyStringAttribute as w, normalizeEditorImageLayout as x, EDITOR_IMAGE_LAYOUT_ATTRIBUTE as y };
-//# sourceMappingURL=Configuration-CA_jvQKG.js.map
+//# sourceMappingURL=Configuration-CDMYfTre.js.map