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

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.0-beta.2
+
+This beta replaces the earlier installation and form interfaces directly.
+
+- Runtime installation: move database URLs, origins, authentication secrets, initialization tokens, and S3 connection values out of `cms.config.ts` and into Nuxt `runtimeConfig.cms` / `NUXT_CMS_*`. Keep only the PostgreSQL schema and S3 prefix under `installation`. Rebuild once; no database migration, content import, or reset is required.
+- CLI: `cms dev` now loads `<root>/.env`, supports `--root`, `--env-file`, `--verbose`, and `--json`, and reports stable phase diagnostics. No data operation is required.
+- Forms: handlers must return `accepted`, `invalid`, or `unavailable`; `void` is no longer accepted. The handler receives request metadata. Replace `field()` and nested controller refs with `control()` / `visibleControls` and plain reactive properties. Rebuild the application; no stored form migration is required.
+- Generated types: Nuxt renderers should import named `CmsFormDefinition<'form-name'>` from `#cms/types` and use the auto-imported `useCmsForm`. Regenerate Nuxt types with `nuxt prepare` or a normal build.
+- Collection fields: `field(schema, { default })` replaces routine `Schema.withDecodingDefaultKey(Effect.succeed(...))` plumbing. Existing advanced Effect schemas remain valid. No data operation is required.
+- Locale metadata: `i18n.siteConfig` chooses `documents` (default) or `localized-routes`. Studio groups locale variants and can create blank or copied independent translations. No database migration or content rewrite is required.
+- Studio density: Overview previews are visibility-gated and serialized; the form builder edits one selected step at a time. Rebuild to update the embedded Studio.

package/README.md

@@ -24,7 +24,7 @@ export default defineNuxtConfig({
 
 ## Configure
 
-Create a PostgreSQL database and an S3-compatible bucket. The database user must be able to create and migrate CMS tables. Storage credentials need bucket access and object read, write, copy, list, and delete permissions. Configure public reads through your bucket or CDN and use that URL as `publicBaseUrl`; the module does not configure public access policies.
+Create a PostgreSQL database and an S3-compatible bucket. The database user must be able to create and migrate CMS tables. Storage credentials need bucket access and object read, write, copy, list, and delete permissions. Configure public reads through your bucket or CDN; the module does not configure public access policies.
 
 Create `cms.config.ts` beside `nuxt.config.ts`:
 
@@ -32,20 +32,7 @@ Create `cms.config.ts` beside `nuxt.config.ts`:
 import { defineCmsConfig } from '@phtngyn/cms/Configuration'
 import { pageSchema } from './page.schema'
 
-function env(name: string): string {
-  const value = process.env[name]
-  if (!value) throw new Error(`Missing ${name}`)
-  return value
-}
-
 export default defineCmsConfig({
-  baseUrl: env('CMS_BASE_URL'), // Website origin, e.g. http://localhost:3000
-  database: {
-    url: env('DATABASE_URL'),
-    schema: 'cms',
-  },
-  secret: env('CMS_SECRET'),
-  initializationToken: env('CMS_INITIALIZATION_TOKEN'),
   documents: {
     collections: {
       pages: {
@@ -56,27 +43,34 @@ export default defineCmsConfig({
       },
     },
   },
-  media: {
-    publicBaseUrl: env('S3_PUBLIC_URL'),
-    storage: {
-      bucket: env('S3_BUCKET'),
+  installation: {
+    database: { schema: 'cms' },
+    media: {
       prefix: 'cms/',
-      region: env('S3_REGION'),
-      credentials: {
-        accessKeyId: env('S3_ACCESS_KEY_ID'),
-        secretAccessKey: env('S3_SECRET_ACCESS_KEY'),
-      },
-      // For an S3-compatible provider, add its endpoint and, if required:
-      // endpoint: env('S3_ENDPOINT'),
-      // forcePathStyle: true,
     },
   },
 })
 ```
 
-These environment variable names are examples; configuration is executable TypeScript, so you can use your own configuration source. Supply values during Nuxt development/build and to the deployed server. Generate distinct random values of at least 32 characters for `secret` and `initializationToken`, and keep them server-side. For example, run `node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"` separately for each.
+Keep environment-specific values in Nuxt runtime configuration. The module supplies empty `runtimeConfig.cms` defaults, so a production build needs no credentials. Nitro reads these values only when the built server starts:
+
+```dotenv
+NUXT_CMS_BASE_URL=http://localhost:3000
+NUXT_CMS_DATABASE_URL=postgres://cms:cms@localhost:5432/cms
+NUXT_CMS_INITIALIZATION_TOKEN=replace-with-a-distinct-32-character-random-token
+NUXT_CMS_SECRET=replace-with-at-least-32-random-characters
+NUXT_CMS_MEDIA_BUCKET=cms-media
+NUXT_CMS_MEDIA_PUBLIC_BASE_URL=http://localhost:8333/cms-media
+NUXT_CMS_MEDIA_REGION=us-east-1
+NUXT_CMS_MEDIA_ENDPOINT=http://localhost:8333
+NUXT_CMS_MEDIA_FORCE_PATH_STYLE=true
+NUXT_CMS_MEDIA_ACCESS_KEY_ID=cms-media
+NUXT_CMS_MEDIA_SECRET_ACCESS_KEY=cms-media-secret
+```
+
+Generate distinct random values of at least 32 characters for the secret and initialization token, and keep them server-side. The same built artifact can be started against another environment by changing only these runtime values.
 
-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.
+For storage using the AWS credential chain, omit both credential variables. Set `NUXT_CMS_MEDIA_PROVISION_BUCKET=true` to create a missing bucket automatically and grant bucket-creation permission. Set authored `installation.media: false` to build without uploads.
 
 The PostgreSQL schema and S3 prefix are the installation's ownership boundary. CMS creates and migrates only the configured schema, and every media object stays under the configured prefix.
 
@@ -91,6 +85,8 @@ cms dev reset --database --media
 cms dev reset --database --media --yes --bootstrap --content ./content --publish
 ```
 
+All lifecycle commands accept `--root <directory>`, `--env-file <path>`, `--verbose`, and `--json`. Values already present in the process override the explicit environment file, which overrides `<root>/.env`, which overrides Nuxt runtime-config defaults.
+
 `doctor` is read-only and reports pass, fail, or not-verified for configuration, PostgreSQL, migrations, S3, public media, packaged assets, readiness, and WebSockets. Add `--full` to validate pending migrations in a rolled-back transaction and probe database writes plus an actual publicly readable S3 object, or `--json` for editor and CI integrations. `bootstrap` prepares the Nuxt authoring catalog, provisions infrastructure, runs migrations, creates or updates the requested local administrator, and optionally plans and applies content without requiring a running server. Passwords come from `CMS_PASSWORD` or a private prompt.
 
 `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.
@@ -110,6 +106,8 @@ CMS_URL=https://target.example.com CMS_EMAIL=admin@example.com cms content apply
 
 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.
 
+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.
 
 The command tree is intentionally shared: future CMS operations can be added beside `content` without separate executables.
@@ -212,19 +210,17 @@ Supply actual draft 2020-12 schemas from the chosen library, using its input and
 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 { 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('')),
-  ),
+  description: field(Schema.String, { default: '', input: 'textarea' }),
   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.
+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.
 
 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.
 
@@ -261,7 +257,7 @@ const form = {} as CmsFormDefinition<'contact-form'>
 
 `useCmsI18n().t()` autocompletes configured keys and requires the exact placeholders in each message. Nuxt preparation rejects extra locale keys and inconsistent placeholders. Missing translations are allowed only when the configured fallback locale supplies the canonical message.
 
-CMS also synchronizes owned document routes with Nuxt Site Config. The delivered document locale wins, the route prefix applies while delivery resolves, and non-CMS routes retain the application's Site Config. The locale drives `<html lang>`, Open Graph locale, structured-data language, canonical and alternate links, sitemap alternatives, and `useCmsI18n()`.
+CMS also synchronizes owned document routes with Nuxt Site Config. The delivered document locale wins, the route prefix applies while delivery resolves, and non-CMS routes retain the application's Site Config. Set `i18n.siteConfig: 'localized-routes'` to give CMS-derived language metadata to custom localized routes too; document canonical URLs, alternates, and SEO remain document-only. The default `documents` scope avoids conflicts with another application i18n module.
 
 ## Studio and authoring during development
 
@@ -344,9 +340,10 @@ forms: {
       fieldTypes: ['text', 'email', 'textarea', 'number', 'checkbox', 'select'],
       rules: ['required', 'minLength', 'maxLength', 'min', 'max'],
     }),
-    onSubmit: async ({ form, values }) => {
+    onSubmit: async ({ form, request, values }) => {
       // Server only: deliver or persist validated answers here.
       // values are keyed by stable question IDs; form.steps contains their labels.
+      return { status: 'accepted', reference: request.id }
     },
   },
 },
@@ -357,14 +354,11 @@ Create `ContactForm.vue` with an optional `cmsForm?: CmsFormDefinition` prop. Th
 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'
+import type { CmsFormDefinition } from '#cms/types'
 
-const props = defineProps<{ definition: CmsFormDefinition }>()
+const props = defineProps<{ definition: CmsFormDefinition<'contact-form'> }>()
 const {
-  fields,
   steps,
-  values,
   errors,
   currentStep,
   stepIndex,
@@ -375,9 +369,10 @@ const {
   isPreview,
   submitError,
   canSubmit,
-  invalidFields,
-  firstInvalidFieldId,
-  field,
+  visibleControls,
+  invalidControls,
+  firstInvalidControlId,
+  control,
   next,
   previous,
   validate,
@@ -386,13 +381,13 @@ const {
 } = useCmsForm(() => props.definition)
 ```
 
-The composable accepts a value, ref, or getter and returns destructurable refs and functions. Use `field(id)` for each visible question. The cached controller exposes a writable `value`, `dirty`, `touched`, `valid`, one-item `errors`, `controlAttrs`, `helpAttrs`, `errorAttrs`, and `touch()`. Bind `controlAttrs` to the native control, `helpAttrs` to help text, and `errorAttrs` to the rendered error; CMS keeps their stable IDs and ARIA relationships aligned. 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. `canSubmit`, `invalidFields`, and `firstInvalidFieldId` centralize form-level behavior, while `submitError` and `errors._form` cover transport and server failures.
+The composable accepts a value, ref, or getter and returns destructurable refs and functions. Iterate `visibleControls`; each reactive control exposes plain template properties: `field`, writable `value`, `dirty`, `touched`, `valid`, `error`, `attrs`, `helpAttrs`, `errorAttrs`, and `touch()`. Bind `attrs` to the native control. CMS keeps stable IDs and ARIA relationships aligned without nested `.value` access inside a `v-for`. Valid number answers become numbers, empty answers become null, and invalid number text remains visible to validation. `canSubmit`, `invalidControls`, and `firstInvalidControlId` centralize form-level behavior, while `submitError` and `errors._form` cover transport and server failures.
 
 `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.
+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. The application handler explicitly returns `accepted`, `invalid`, or `unavailable`; trusted validation errors may target current field IDs or `_form`. Unexpected failures are correlated by request ID in server logs without recording answers and return only a generic public failure.
 
 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.
 

package/package.json

@@ -17,13 +17,14 @@
     "directory": "packages/nuxt"
   },
   "name": "@phtngyn/cms",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "type": "module",
   "files": [
     "bin",
     "studio",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "exports": {
@@ -69,7 +70,7 @@
     "@hocuspocus/server": "^4.7.0",
     "@nuxt/kit": "^4.5.2",
     "@nuxt/schema": "^4.5.2",
-    "@nuxtjs/robots": "^6.2.2",
+    "@nuxtjs/robots": "^6.2.3",
     "@nuxtjs/sitemap": "^8.5.1",
     "@standard-schema/spec": "^1.1.0",
     "@tiptap/core": "^3.31.3",
@@ -77,6 +78,7 @@
     "@tiptap/y-tiptap": "^3.0.9",
     "@vue/compiler-sfc": "^3.6.0-rc.8",
     "better-auth": "^1.7.4",
+    "c12": "^4.0.0-rc.1",
     "comark": "^0.7.0",
     "diff": "^9.0.0",
     "drizzle-orm": "^1.0.0-rc.5-169397b",
@@ -84,8 +86,8 @@
     "h3": "^1.15.11",
     "jiti": "^2.7.0",
     "nitropack": "^2.13.4",
-    "nuxt-schema-org": "^6.3.1",
-    "nuxt-seo-utils": "^8.5.0",
+    "nuxt-schema-org": "^6.3.2",
+    "nuxt-seo-utils": "^8.5.1",
     "nuxt-site-config": "^4.2.3",
     "pg": "^8.23.0",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
@@ -98,4 +100,4 @@
     "nuxt": ">=4.5.0 <5.0.0",
     "vue": ">=3.6.0-rc.6 <4.0.0"
   }
-}
+}

package/src/ApplicationTypes.d.ts

@@ -1,5 +1,5 @@
-import { a as FormStep, n as FormDefinition, r as FormField } from "./Forms-BorTcIlp.js";
-import { a as CmsMessageParameters, i as CmsMessageKey, r as CmsLocale } from "./I18n-BXlVunfa.js";
+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 { Schema } from "effect";
 import { StandardSchemaV1 } from "@standard-schema/spec";
@@ -42,11 +42,13 @@ type FormFieldType<Name extends CmsFormName> = FormCapabilities<Name> extends {
   fieldTypes: ReadonlyArray<infer FieldType>;
 } ? Extract<FieldType, FormField['type']> : never;
 type FormRuleProperty<Rule> = Rule extends 'required' ? 'required' : Rule extends 'minLength' ? 'minLength' : Rule extends 'maxLength' ? 'maxLength' : Rule extends 'min' ? 'min' : Rule extends 'max' ? 'max' : never;
-type CmsFormField<Name extends CmsFormName> = Omit<FormField, 'max' | 'maxLength' | 'min' | 'minLength' | 'required' | 'type'> & Pick<FormField, FormRuleProperty<FormCapabilities<Name> extends {
+type AllowedFormRuleProperty<Name extends CmsFormName> = FormRuleProperty<FormCapabilities<Name> extends {
   rules: ReadonlyArray<infer Rule>;
-} ? Rule : never>> & {
+} ? Rule : never>;
+type RestrictFormRules<Field, Name extends CmsFormName> = Field extends FormField ? Omit<Field, Exclude<'max' | 'maxLength' | 'min' | 'minLength' | 'required', AllowedFormRuleProperty<Name>>> : never;
+type CmsFormField<Name extends CmsFormName> = RestrictFormRules<Extract<FormField, {
   readonly type: FormFieldType<Name>;
-};
+}>, Name>;
 type CmsFormStep<Name extends CmsFormName> = Omit<FormStep, 'fields'> & {
   readonly fields: ReadonlyArray<CmsFormField<Name>>;
 };

package/src/{Configuration-CjVUBBwa.js → Configuration-BU-UyGoH.js}

@@ -1,6 +1,6 @@
-import { Ct as CollectionName, St as AddressPattern, Tt as SourceDirectory, b as MarkdownNode, n as CmsMarkdownDocument, wt as Locale } from "./models-DgkGTFus.js";
-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-02-p8qEw.js";
+import { Ct as CollectionName, St as AddressPattern, Tt as SourceDirectory, b as MarkdownNode, n as CmsMarkdownDocument, wt as Locale } from "./models-ChRxBChy.js";
+import { r as FormCapabilities } from "./Forms-BbkE7QfC.js";
+import { c as resolveCmsComarkAttributes, d as createCmsComarkRenderData, l as withCmsComarkProps, r as formStructureIssues, s as projectCmsEditorComponentAttributes } from "./Forms-DoB56hfe.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-CjVUBBwa.js.map
+//# sourceMappingURL=Configuration-BU-UyGoH.js.map