@plutocms/pluto 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
 
+## [0.6.0](https://github.com/plutocms/pluto/compare/v0.5.0...v0.6.0) (2026-09-12)
+
+
+### Features
+
+* **content:** add content-model contracts (wave 1) ([#131](https://github.com/plutocms/pluto/issues/131)) ([95e157b](https://github.com/plutocms/pluto/commit/95e157b41a60b17ae8311878eb2ef79356feef43))
+
 ## [0.5.0](https://github.com/plutocms/pluto/compare/v0.4.0...v0.5.0) (2026-09-12)
 
 

package/FEATURES.md

@@ -12,3 +12,7 @@ policies shared by every project here.
 - Permissions: a typed capability registry and a `usePlutoPermissions()` composable that let a
   layer declare capabilities and check what the current user holds, backed by a registered
   permissions driver. @.claude/skills/permissions/SKILL.md
+- Content model: a typed content-type contract (`defineContentType`, field types, payload
+  validation, field-to-column mapping) and a media-adapter contract, with registry wiring and
+  consumer composables. Client-side contracts only; no server registry or generated UI yet.
+  @.claude/skills/content-model/SKILL.md

package/app/composables/pluto-content-fields.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolves the component that renders `field` in the generic content form
+ * (a later wave). Matches an exact `widget` name first — a field can force
+ * a specific widget through `PlutoFieldBase.widget` — then falls back to
+ * the last-registered entry for the field's `type`. Returns `undefined`
+ * when nothing matches: this wave adds no fallback placeholder component,
+ * that is later, UI-wave work.
+ */
+export function usePlutoContentFieldWidget(field: PlutoField) {
+  const registry = usePlutoRegistry()
+
+  return computed<Component | undefined>(() => {
+    const entries = registry.contentFieldWidgets.list.value
+
+    if (field.widget) {
+      const exact = entries.find((entry) => entry.widget === field.widget)
+      if (exact) {
+        return exact.component
+      }
+    }
+
+    return entries.filter((entry) => entry.fieldType === field.type).at(-1)?.component
+  })
+}

package/app/composables/pluto-content-types.ts

@@ -0,0 +1,11 @@
+/** Content types declared by every layer, in registry order. */
+export function usePlutoContentTypes() {
+  const registry = usePlutoRegistry()
+
+  /** Looks up a content type by its own `name`, not the registry entry `id`. */
+  function byName(name: string): PlutoContentType | undefined {
+    return registry.contentTypes.list.value.find((entry) => entry.type.name === name)?.type
+  }
+
+  return { items: registry.contentTypes.list, byName }
+}

package/app/composables/pluto-extension.ts

@@ -26,4 +26,7 @@ export function definePlutoExtension(definition: PlutoExtension): void {
     definition.id,
     definition.permissionsDriver ? [definition.permissionsDriver] : []
   )
+  registry.contentTypes.set(definition.id, definition.contentTypes ?? [])
+  registry.contentFieldWidgets.set(definition.id, definition.contentFieldWidgets ?? [])
+  registry.mediaAdapters.set(definition.id, definition.mediaAdapters ?? [])
 }

package/app/composables/pluto-media-adapter.ts

@@ -0,0 +1,15 @@
+/**
+ * The registered media adapter. Only one is meaningful per app: when more
+ * than one layer registers one, the last-registered entry wins, the same
+ * "last wins" rule `usePlutoSettings`/`usePlutoPermissions` use to resolve
+ * their driver.
+ */
+export function usePlutoMediaAdapter() {
+  const registry = usePlutoRegistry()
+
+  const adapter = computed<PlutoMediaAdapter | undefined>(
+    () => registry.mediaAdapters.list.value.at(-1)?.adapter
+  )
+
+  return { adapter }
+}

package/app/composables/pluto-registry.ts

@@ -23,6 +23,9 @@ export function usePlutoRegistry(): PlutoRegistry {
       dashboardWidgets: createOwnedRegistry<PlutoDashboardWidget>(),
       capabilities: createOwnedRegistry<PlutoCapability>(),
       permissionsDrivers: createOwnedRegistry<PlutoPermissionsDriver>(),
+      contentTypes: createOwnedRegistry<PlutoContentTypeEntry>(),
+      contentFieldWidgets: createOwnedRegistry<PlutoContentFieldWidget>(),
+      mediaAdapters: createOwnedRegistry<PlutoMediaAdapterEntry>(),
     }
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/pluto",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The layerable CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",

package/shared/types/content.ts

@@ -0,0 +1,196 @@
+export type PlutoFieldType =
+  | 'text'
+  | 'textarea'
+  | 'richtext'
+  | 'slug'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'select'
+  | 'reference'
+  | 'media'
+
+/**
+ * Fields every `PlutoField` shares, regardless of `type`. A concrete field
+ * (`PlutoTextField`, `PlutoSlugField`, and so on) narrows `type` to one
+ * literal and adds its own type-specific options on top of this base.
+ */
+export interface PlutoFieldBase {
+  /** Field key. Used as the object key on a `PlutoContentItem`, and as the default storage column (see `fieldColumn` in `shared/utils/content-map.ts`). */
+  name: string
+  type: PlutoFieldType
+  label: string
+  description?: string
+  /** Storage column, when it differs from `name`. Falls back to `name` when unset. */
+  column?: string
+  required?: boolean
+  /** Show this field as a column in the generic list view. Default false. */
+  inList?: boolean
+  /** Show this field in the generic form view. Default true. */
+  inForm?: boolean
+  /** Lower comes first, in both the list and the form. Default 100. */
+  order?: number
+  default?: unknown
+  /** Name of a registered `PlutoContentFieldWidget` to force, overriding the default resolved by `type`. */
+  widget?: string
+  /** Which column of the generic form this field renders in. Default 'main'. */
+  region?: 'main' | 'side'
+}
+
+export interface PlutoTextField extends PlutoFieldBase {
+  type: 'text' | 'textarea' | 'richtext'
+  maxLength?: number
+  placeholder?: string
+}
+
+export interface PlutoSlugField extends PlutoFieldBase {
+  type: 'slug'
+  /** Name of the field this slug is generated from, for example 'title'. */
+  from?: string
+  preview?: string
+}
+
+export interface PlutoNumberField extends PlutoFieldBase {
+  type: 'number'
+  integer?: boolean
+  min?: number
+  max?: number
+}
+
+export interface PlutoSelectField extends PlutoFieldBase {
+  type: 'select'
+  options: Array<{
+    label: string
+    value: string | number
+  }>
+}
+
+export interface PlutoReferenceField extends PlutoFieldBase {
+  type: 'reference'
+  /** Name of the referenced content type, for example 'category'. */
+  target?: string
+  optionsUrl?: string
+  labelKey?: string
+  valueKey?: string
+}
+
+export interface PlutoMediaField extends PlutoFieldBase {
+  type: 'media'
+  multiple?: boolean
+}
+
+export interface PlutoBooleanField extends PlutoFieldBase {
+  type: 'boolean'
+}
+
+export interface PlutoDateField extends PlutoFieldBase {
+  type: 'date'
+}
+
+export type PlutoField =
+  | PlutoTextField
+  | PlutoSlugField
+  | PlutoNumberField
+  | PlutoSelectField
+  | PlutoReferenceField
+  | PlutoMediaField
+  | PlutoBooleanField
+  | PlutoDateField
+
+/**
+ * Capability keys a content-type adapter checks before it reads, writes, or
+ * deletes a row. Plain strings, not registered `PlutoCapability` entries —
+ * see the permissions skill for the format (`<namespace>:<action>`).
+ */
+export interface PlutoContentTypeCapabilities {
+  read?: string
+  write?: string
+  delete?: string
+}
+
+export interface PlutoContentStatus {
+  /** Storage column. Falls back to 'status' when unset. */
+  column?: string
+  values: Array<{
+    label: string
+    value: string
+  }>
+  default?: string
+  /** The `values[].value` that counts as published, for example 'published'. */
+  publishedValue?: string
+  publishedAtColumn?: string
+}
+
+export interface PlutoContentTimestamps {
+  /** Storage column, or `false` to disable this timestamp. Falls back to 'created_at' when unset. */
+  created?: string | false
+  /** Storage column, or `false` to disable this timestamp. Falls back to 'updated_at' when unset. */
+  updated?: string | false
+}
+
+export interface PlutoContentI18n {
+  /** Reserved for a future release. Only 'row' will ever be supported: one row per locale. Not implemented yet — declaring it costs nothing and avoids a breaking rename later. */
+  strategy: 'row'
+  localeColumn?: string
+  groupColumn?: string
+}
+
+/**
+ * The contract for one content type: what fields it has, where it is
+ * stored, and how the generic list/form UI (a later wave) should render it.
+ * A layer declares one of these per content type it owns, through
+ * `defineContentType`.
+ */
+export interface PlutoContentType {
+  /**
+   * The content type's own identifier, for example 'post'. Kept separate
+   * from a registered `PlutoContentTypeEntry.id` for the exact same reason
+   * `PlutoCapability.key` is kept separate from `id` (see
+   * `shared/types/registry.ts`): the registry rewrites `id` to
+   * `'<extensionId>:<id>'`, which would corrupt a name used in a URL path
+   * segment or as a lookup key. Always read `name` for the real content
+   * type identity, never the registry entry's `id`.
+   */
+  name: string
+  label: string
+  labelPlural: string
+  icon?: string
+  /** Table or view name this content type reads and writes. */
+  source: string
+  /** Storage column for the primary key. Falls back to 'id' when unset. */
+  primaryKey?: string
+  /** Name of the field shown as the row's title in lists and breadcrumbs. */
+  titleField: string
+  fields: PlutoField[]
+  /** Name of the field that holds the slug, or `false` to disable slugging entirely. */
+  slug?: {
+    field: string
+  } | false
+  /** `false` disables status/publish workflow entirely for this content type. */
+  status?: PlutoContentStatus | false
+  /** `false` disables created/updated timestamps entirely for this content type. */
+  timestamps?: PlutoContentTimestamps | false
+  capabilities?: PlutoContentTypeCapabilities
+  defaultSort?: {
+    field: string
+    direction: 'asc' | 'desc'
+  }
+  /** Whether a later wave should generate list/edit/create admin routes for this content type. */
+  autoRoutes?: boolean
+  /** Base admin path for generated routes, for example '/admin/posts'. Only meaningful when `autoRoutes` is true. */
+  basePath?: string
+  navOrder?: number
+  i18n?: PlutoContentI18n
+}
+
+/**
+ * One stored content row, keyed by field name (not column name — see
+ * `mapColumnsToFields` in `shared/utils/content-map.ts` for the
+ * column-to-field translation). Named `PlutoContentItem`, not
+ * `PlutoEntryRecord`, to avoid visual confusion with `PlutoEntry` (a
+ * registry bucket item, see `shared/types/registry.ts`) — this type has
+ * nothing to do with the registry.
+ */
+export type PlutoContentItem = Record<string, unknown> & {
+  id: string | number
+}

package/shared/types/media.ts

@@ -0,0 +1,34 @@
+export interface PlutoMediaItem {
+  id: string
+  name: string
+  url: string
+  mimeType?: string
+  size?: number
+  alt?: string
+}
+
+export interface PlutoMediaListOptions {
+  limit?: number
+  offset?: number
+  search?: string
+}
+
+/**
+ * Lets a storage layer (Supabase Storage, S3, R2, local disk...) plug into
+ * one shared media picker UI and one `media` field widget, without core
+ * knowing which backend is in use. Exactly one adapter is registered per
+ * app — see the `mediaAdapters` registry bucket, which keeps only the
+ * last-registered one, the same "last wins" rule as `settingsDrivers`.
+ */
+export interface PlutoMediaAdapter {
+  id: string
+  list: (options: PlutoMediaListOptions) => Promise<{
+    data: PlutoMediaItem[]
+    total?: number
+  }>
+  upload: (file: File, meta?: {
+    alt?: string
+  }) => Promise<PlutoMediaItem>
+  remove: (id: string) => Promise<void>
+  getUrl: (id: string) => string
+}

package/shared/types/registry.ts

@@ -1,4 +1,6 @@
 import type { Component, ComputedRef } from 'vue'
+import type { PlutoContentType, PlutoFieldType } from './content'
+import type { PlutoMediaAdapter } from './media'
 
 export interface PlutoEntry {
   /** Unique inside this extension. Stored as `<extensionId>:<id>`. */
@@ -85,6 +87,32 @@ export interface PlutoPermissionsDriver extends PlutoEntry {
   load: () => Promise<string[]>
 }
 
+/**
+ * A content type a layer declares, wrapped for the registry. `type.name`
+ * is the content type's real identity — see the doc comment on
+ * `PlutoContentType.name` in `shared/types/content.ts` for why it is kept
+ * separate from this entry's `id`.
+ */
+export interface PlutoContentTypeEntry extends PlutoEntry {
+  type: PlutoContentType
+}
+
+/**
+ * A component that renders one field type, or one named `widget`, in the
+ * generic content form (a later wave). `fieldType` and `widget` are both
+ * optional so an entry can match by either — see
+ * `usePlutoContentFieldWidget` for the resolution order.
+ */
+export interface PlutoContentFieldWidget extends PlutoEntry {
+  fieldType?: PlutoFieldType
+  widget?: string
+  component: Component
+}
+
+export interface PlutoMediaAdapterEntry extends PlutoEntry {
+  adapter: PlutoMediaAdapter
+}
+
 export interface PlutoExtension {
   /** Layer name. Use the package's $meta.name, e.g. 'supabase-blog'. */
   id: string
@@ -97,6 +125,9 @@ export interface PlutoExtension {
   settingsDriver?: PlutoSettingsDriver
   capabilities?: PlutoCapability[]
   permissionsDriver?: PlutoPermissionsDriver
+  contentTypes?: PlutoContentTypeEntry[]
+  contentFieldWidgets?: PlutoContentFieldWidget[]
+  mediaAdapters?: PlutoMediaAdapterEntry[]
 }
 
 /**
@@ -121,4 +152,7 @@ export interface PlutoRegistry {
   dashboardWidgets: PlutoRegistryBucket<PlutoDashboardWidget>
   capabilities: PlutoRegistryBucket<PlutoCapability>
   permissionsDrivers: PlutoRegistryBucket<PlutoPermissionsDriver>
+  contentTypes: PlutoRegistryBucket<PlutoContentTypeEntry>
+  contentFieldWidgets: PlutoRegistryBucket<PlutoContentFieldWidget>
+  mediaAdapters: PlutoRegistryBucket<PlutoMediaAdapterEntry>
 }

package/shared/utils/content-map.ts

@@ -0,0 +1,49 @@
+/** Resolves the storage column for a field. Falls back to `field.name` when `field.column` is unset. */
+export function fieldColumn(field: PlutoField): string {
+  return field.column ?? field.name
+}
+
+/**
+ * Converts a field-keyed payload into a column-keyed one, for every field
+ * in `type.fields` present in `payload`. A field absent from `payload` is
+ * left out of the result, so a partial update payload stays partial after
+ * mapping. An adapter (a later wave) sends the result straight to its
+ * storage layer.
+ */
+export function mapFieldsToColumns(
+  type: PlutoContentType,
+  payload: Record<string, unknown>
+): Record<string, unknown> {
+  const columns: Record<string, unknown> = {}
+
+  for (const field of type.fields) {
+    if (Object.hasOwn(payload, field.name)) {
+      columns[fieldColumn(field)] = payload[field.name]
+    }
+  }
+
+  return columns
+}
+
+/**
+ * Converts a column-keyed row into a field-keyed `PlutoContentItem`, for
+ * every field in `type.fields`, plus the primary key column (`type.primaryKey`,
+ * default `'id'`) mapped to `item.id`. A column absent from `row` is left
+ * out of the result field.
+ */
+export function mapColumnsToFields(
+  type: PlutoContentType,
+  row: Record<string, unknown>
+): PlutoContentItem {
+  const primaryKey = type.primaryKey ?? 'id'
+  const item: Record<string, unknown> = { id: row[primaryKey] }
+
+  for (const field of type.fields) {
+    const column = fieldColumn(field)
+    if (Object.hasOwn(row, column)) {
+      item[field.name] = row[column]
+    }
+  }
+
+  return item as PlutoContentItem
+}

package/shared/utils/content-validate.ts

@@ -0,0 +1,100 @@
+export interface ContentValidationError {
+  field: string
+  message: string
+}
+
+/**
+ * Checks a field-keyed payload against a content type's field rules. Pure
+ * TypeScript, no I/O and no Nuxt/Vue dependency, so a server route (a later
+ * wave) and an app composable can both call it and get the same answer.
+ *
+ * Pass `{ partial: true }` for a partial update (for example a PATCH):
+ * a required field missing from `payload` entirely is not an error, because
+ * omitting a field is not the same as clearing it. A required field present
+ * in `payload` with an empty value is still an error, partial or not.
+ */
+export function validateContentPayload(
+  type: PlutoContentType,
+  payload: Record<string, unknown>,
+  options?: {
+    partial?: boolean
+  }
+): ContentValidationError[] {
+  const errors: ContentValidationError[] = []
+
+  for (const field of type.fields) {
+    const present = Object.hasOwn(payload, field.name)
+    const value = payload[field.name]
+
+    if (field.required) {
+      const skipBecausePartial = options?.partial === true && !present
+      const empty = value === undefined || value === null || value === ''
+      if (!skipBecausePartial && empty) {
+        errors.push({ field: field.name, message: `"${field.label}" is required.` })
+        continue
+      }
+    }
+
+    // Nothing more to check when the field was not supplied at all.
+    if (!present || value === undefined || value === null) {
+      continue
+    }
+
+    switch (field.type) {
+      case 'number': {
+        const numeric = typeof value === 'number' ? value : Number(value)
+        if ((typeof value !== 'number' && typeof value !== 'string') || Number.isNaN(numeric)) {
+          errors.push({ field: field.name, message: `"${field.label}" must be a number.` })
+          break
+        }
+        if (field.integer && !Number.isInteger(numeric)) {
+          errors.push({ field: field.name, message: `"${field.label}" must be an integer.` })
+        }
+        if (field.min !== undefined && numeric < field.min) {
+          errors.push({ field: field.name, message: `"${field.label}" must be at least ${field.min}.` })
+        }
+        if (field.max !== undefined && numeric > field.max) {
+          errors.push({ field: field.name, message: `"${field.label}" must be at most ${field.max}.` })
+        }
+        break
+      }
+
+      case 'boolean': {
+        if (typeof value !== 'boolean') {
+          errors.push({ field: field.name, message: `"${field.label}" must be a boolean.` })
+        }
+        break
+      }
+
+      case 'select': {
+        if (!field.options.some((option) => option.value === value)) {
+          errors.push({ field: field.name, message: `"${field.label}" must be one of the allowed options.` })
+        }
+        break
+      }
+
+      case 'text':
+      case 'textarea':
+      case 'richtext':
+      case 'slug': {
+        // Only PlutoTextField carries maxLength; PlutoSlugField never does,
+        // so the 'in' check both narrows the type and skips slug fields.
+        const maxLength = 'maxLength' in field ? field.maxLength : undefined
+        if (maxLength !== undefined && typeof value === 'string' && value.length > maxLength) {
+          errors.push({
+            field: field.name,
+            message: `"${field.label}" must be at most ${maxLength} characters.`,
+          })
+        }
+        break
+      }
+
+      // 'date' | 'reference' | 'media': no format check in this wave, only
+      // the required check above.
+      default:
+        break
+    }
+  }
+
+  return errors
+}

package/shared/utils/content.ts

@@ -0,0 +1,49 @@
+/**
+ * Declares a content type. This is an identity function: it returns `type`
+ * unchanged. Its only job is type inference at the call site — wrapping a
+ * content type literal in `defineContentType` lets TypeScript narrow each
+ * `PlutoField`'s `type` correctly — plus a handful of dev-only sanity
+ * checks below. This mirrors `definePlutoExtension`'s role: a thin, typed
+ * entry point, not a place that does real work.
+ *
+ * The checks only warn, and only in dev (`import.meta.dev` strips them
+ * from a production build). A content type with a typo still loads. The
+ * warning exists to catch the typo before it reaches a later wave's
+ * generic list/form UI or server adapter, where it would fail silently or
+ * confusingly instead.
+ */
+export function defineContentType(type: PlutoContentType): PlutoContentType {
+  if (import.meta.dev) {
+    const prefix = `[pluto] content type "${type.name}":`
+    const seen = new Set<string>()
+
+    for (const field of type.fields) {
+      if (seen.has(field.name)) {
+        console.warn(`${prefix} duplicate field name "${field.name}".`)
+      }
+      seen.add(field.name)
+
+      if (field.type === 'select' && field.options.length === 0) {
+        console.warn(`${prefix} select field "${field.name}" has no options.`)
+      }
+    }
+
+    if (!type.fields.some((field) => field.name === type.titleField)) {
+      console.warn(`${prefix} titleField "${type.titleField}" does not match any field.`)
+    }
+
+    if (type.slug) {
+      const slug = type.slug
+      const field = type.fields.find((candidate) => candidate.name === slug.field)
+      if (!field || field.type !== 'slug') {
+        console.warn(`${prefix} slug.field "${slug.field}" does not name a field of type "slug".`)
+      }
+    }
+
+    if (type.status && type.status.values.length === 0) {
+      console.warn(`${prefix} status has no values.`)
+    }
+  }
+
+  return type
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  define: {
+    'import.meta.dev': 'true',
+  },
+})