@phtngyn/cms 0.1.0-beta.5 → 0.2.0-beta.1

package/README.md

@@ -40,7 +40,10 @@ function env(name: string): string {
 
 export default defineCmsConfig({
   baseUrl: env('CMS_BASE_URL'), // Website origin, e.g. http://localhost:3000
-  databaseUrl: env('DATABASE_URL'),
+  database: {
+    url: env('DATABASE_URL'),
+    schema: 'cms',
+  },
   secret: env('CMS_SECRET'),
   initializationToken: env('CMS_INITIALIZATION_TOKEN'),
   documents: {
@@ -57,6 +60,7 @@ export default defineCmsConfig({
     publicBaseUrl: env('S3_PUBLIC_URL'),
     storage: {
       bucket: env('S3_BUCKET'),
+      prefix: 'cms/',
       region: env('S3_REGION'),
       credentials: {
         accessKeyId: env('S3_ACCESS_KEY_ID'),
@@ -74,6 +78,23 @@ 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.
 
+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.
+
+## Local development lifecycle
+
+Use the supported lifecycle before starting Nuxt:
+
+```sh
+cms dev doctor
+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
+```
+
+`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.
+
 ## 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.
@@ -93,6 +114,30 @@ For a folder without `.cms-content.json`, the CLI reads nested `.md` and `.mdc`
 
 The command tree is intentionally shared: future CMS operations can be added beside `content` without separate executables.
 
+The same workflow is available to Node scripts without parsing CLI output:
+
+```ts
+import { createCmsContentClient, readCmsContentDirectory } from '@phtngyn/cms/Content'
+
+const source = await readCmsContentDirectory('./content')
+const client = createCmsContentClient({
+  baseUrl: 'http://localhost:3000',
+  credentials: {
+    email: process.env.CMS_EMAIL!,
+    password: process.env.CMS_PASSWORD!,
+  },
+})
+
+const plan = await client.plan(source, { overwrite: false, publish: true })
+
+if (plan.valid) await client.apply(plan)
+
+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.
+
 ## 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.
@@ -130,6 +175,24 @@ Keep raw robots directives and Nuxt module configuration in application code. Th
 
 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.
 
+The public standards types come directly from `@standard-schema/spec`. For a validator whose JSON Schema adapter is separate, `defineCmsSchema()` combines both contracts and applies library-neutral presentation to nested field paths:
+
+```ts
+import { defineCmsSchema } from '@phtngyn/cms/DocumentModel'
+
+const pageSchema = defineCmsSchema({
+  validator: page,
+  jsonSchema: {
+    input: () => createInputSchema(page),
+    output: () => createOutputSchema(page),
+  },
+  fields: {
+    description: { label: 'Description', input: 'textarea' },
+    'seo.description': { input: 'textarea' },
+  },
+})
+```
+
 For a validator that already implements both standards, pass it directly as `schema`. Otherwise, adapt its validator and input/output JSON Schema converters:
 
 ```ts
@@ -186,6 +249,20 @@ 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'>`.
+
+```ts
+import type { CmsCollection, CmsFormDefinition, CmsLocale } from '#cms/types'
+
+const page: CmsCollection<'pages'> | null = useDocument<'pages'>('/').data.value
+const locale: CmsLocale = 'de'
+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()`.
+
 ## Studio and authoring during development
 
 Studio at `/_cms/app` is a separate HTML document, Vue application, and Tailwind build. It owns its Nuxt UI settings, styles, and overlays independently of the website. Your app root and layouts apply only to the website. Both applications use the same Nuxt server; no separate Studio server or port is required.
@@ -293,11 +370,14 @@ const {
   stepIndex,
   isFirstStep,
   isLastStep,
-  isSubmitting,
+  submitting,
   isSuccess,
   isPreview,
-  error,
-  fieldState,
+  submitError,
+  canSubmit,
+  invalidFields,
+  firstInvalidFieldId,
+  field,
   next,
   previous,
   validate,
@@ -306,7 +386,7 @@ const {
 } = 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.
+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.
 
 `next()` validates the current step, `previous()` preserves answers, and `submit()` validates every step and returns whether submission succeeded. A required checkbox must be checked.
 

package/package.json

@@ -17,7 +17,7 @@
     "directory": "packages/nuxt"
   },
   "name": "@phtngyn/cms",
-  "version": "0.1.0-beta.5",
+  "version": "0.2.0-beta.1",
   "type": "module",
   "files": [
     "bin",
@@ -43,6 +43,10 @@
       "types": "./src/DocumentModel.d.ts",
       "import": "./src/DocumentModel.js"
     },
+    "./ApplicationTypes": {
+      "types": "./src/ApplicationTypes.d.ts",
+      "import": "./src/ApplicationTypes.js"
+    },
     "./I18n": {
       "types": "./src/I18n.d.ts",
       "import": "./src/I18n.js"
@@ -50,6 +54,10 @@
     "./Forms": {
       "types": "./src/Forms.d.ts",
       "import": "./src/Forms.js"
+    },
+    "./Content": {
+      "types": "./src/Content.d.ts",
+      "import": "./src/Content.js"
     }
   },
   "dependencies": {
@@ -63,6 +71,7 @@
     "@nuxt/schema": "^4.5.2",
     "@nuxtjs/robots": "^6.2.2",
     "@nuxtjs/sitemap": "^8.5.1",
+    "@standard-schema/spec": "^1.1.0",
     "@tiptap/core": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",
     "@tiptap/y-tiptap": "^3.0.9",
@@ -77,6 +86,7 @@
     "nitropack": "^2.13.4",
     "nuxt-schema-org": "^6.3.1",
     "nuxt-seo-utils": "^8.5.0",
+    "nuxt-site-config": "^4.2.3",
     "pg": "^8.23.0",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
     "vite": "^8.3.0",

package/src/ApplicationTypes.d.ts

@@ -0,0 +1,82 @@
+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 { n as DeliveryDocumentPage, t as DeliveryDocument } from "./types-DutFRtaG.js";
+import { Schema } from "effect";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/ApplicationTypes.d.ts
+/** Nuxt augments this registry from the authored CMS configuration and component catalog. */
+export interface CmsApplicationRegistry {}
+type AuthoredConfiguration = CmsApplicationRegistry extends {
+  configuration: infer Configuration;
+} ? Configuration : never;
+type AuthoredCollections = AuthoredConfiguration extends {
+  documents: {
+    collections: infer Collections;
+  };
+} ? Collections : Record<string, never>;
+type AuthoredForms = AuthoredConfiguration extends {
+  forms: infer Forms;
+} ? NonNullable<Forms> : Record<string, never>;
+type CollectionSchema<Name extends keyof AuthoredCollections> = AuthoredCollections[Name] extends {
+  schema: infer CollectionSchema;
+} ? CollectionSchema : never;
+type SchemaOutput<Value> = Value extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Value> : Value extends Schema.Top ? Value['Type'] : never;
+type JsonOutput<Value> = Value extends object ? Value : Record<string, never>;
+export type CmsCollectionName = Extract<keyof AuthoredCollections, string>;
+export type CmsFormName = Extract<keyof AuthoredForms, string>;
+export type CmsBlockName = CmsApplicationRegistry extends {
+  blockName: infer Name extends string;
+} ? Name : string;
+export type CmsCollection<Name extends CmsCollectionName> = Omit<DeliveryDocument, 'body' | 'collection' | 'data' | 'locale'> & {
+  readonly body: Omit<DeliveryDocument['body'], 'frontmatter'> & {
+    readonly frontmatter: JsonOutput<SchemaOutput<CollectionSchema<Name>>>;
+  };
+  readonly collection: Name;
+  readonly data: JsonOutput<SchemaOutput<CollectionSchema<Name>>>;
+  readonly locale?: CmsLocale;
+};
+type FormCapabilities<Name extends CmsFormName> = AuthoredForms[Name] extends {
+  definition: infer Capabilities;
+} ? Capabilities : never;
+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 {
+  rules: ReadonlyArray<infer Rule>;
+} ? Rule : never>> & {
+  readonly type: FormFieldType<Name>;
+};
+type CmsFormStep<Name extends CmsFormName> = Omit<FormStep, 'fields'> & {
+  readonly fields: ReadonlyArray<CmsFormField<Name>>;
+};
+export type CmsFormDefinition<Name extends CmsFormName = CmsFormName> = Omit<FormDefinition, 'name' | 'steps'> & {
+  readonly name: Name;
+  readonly steps: ReadonlyArray<CmsFormStep<Name>>;
+};
+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 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> {
+  readonly direction?: 'asc' | 'desc';
+  readonly field: DocumentField<Name>;
+}
+export interface CmsDocumentQuery<Name extends CmsCollectionName = CmsCollectionName> {
+  readonly collection?: Name;
+  readonly locale?: CmsLocale;
+  readonly limit: number;
+  readonly offset?: number;
+  readonly sort?: CmsDocumentQuerySort<Name> | ReadonlyArray<CmsDocumentQuerySort<Name>>;
+  readonly where?: CmsDocumentQueryWhere<Name>;
+}
+export interface CmsDocumentPage<Name extends CmsCollectionName> extends Omit<DeliveryDocumentPage, 'items'> {
+  readonly items: ReadonlyArray<CmsCollection<Name>>;
+}
+//#endregion
+export type { CmsLocale, CmsMessageKey, CmsMessageParameters };
+//# sourceMappingURL=ApplicationTypes.d.ts.map

package/src/ApplicationTypes.js

@@ -0,0 +1 @@
+export {  };

package/src/{Configuration-CDMYfTre.js → Configuration-CjVUBBwa.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-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 { c as resolveCmsComarkAttributes, d as createCmsComarkRenderData, l as withCmsComarkProps, r as formStructureIssues, s as projectCmsEditorComponentAttributes } from "./Forms-02-p8qEw.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-CDMYfTre.js.map
+//# sourceMappingURL=Configuration-CjVUBBwa.js.map