@voltro/cli 0.28.0 → 0.29.0

package/templates/apps/api-cms/README.md

@@ -0,0 +1,104 @@
+# {{capProjectName}} {{capAppName}} — headless CMS backend
+
+A headless CMS composed from [`@voltro/cms`](https://voltro.cloud/docs): content
+types declared as **code**, compiled to draft/published tables, driven by the
+write pipeline, and exposed as a typed rpc surface an editor consumes. Content is
+tenant-scoped and gated by real editor auth. Boots **zero-infra** (`store:
+'memory'`, in-process users).
+
+Pair it with the **frontend-cms** editor web template:
+
+```bash
+voltro init my-cms --api=api-cms --web=frontend-cms
+```
+
+## Content types as code
+
+Each `content/*.contentType.ts` file declares a type with the CMS `Schema` field
+DSL. `@voltro/cms` is a **library, not a plugin** — there is no discovery of
+`*.contentType.ts`; `database/schema.ts` imports the types and registers their
+derived tables, and THAT is what makes them migrate.
+
+```ts
+// content/blogPost.contentType.ts
+export const blogPost = defineContentType({
+  name: 'blogPost', displayName: 'Blog post', pluralName: 'Blog posts',
+  fields: {
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    slug:  Schema.String.pipe(Schema.pattern(/^[a-z0-9-]+$/), Schema.unique(), derivedFrom('title', slugify)),
+    body:  Schema.RichText({ allowImages: true }),
+  },
+})
+```
+
+`contentTypeToEntities(blogPost)` compiles this to a `blogPost_drafts` +
+`blogPost_published` table pair — both tenant-scoped (`tenant()`), both carrying
+the lifecycle `status` column, both reactive so a publish wakes subscriptions.
+
+## The rpc surface
+
+| Procedure | Kind | Does |
+|---|---|---|
+| `content.types` | action | the registered types, wire-safe — the editor renders forms from this |
+| `content.list` | query (live) | one type's rows, tenant-scoped; `status` picks drafts vs published |
+| `content.get` | action | one row by id, for the edit form |
+| `content.saveDraft` | mutation | derive → validate → upsert `<type>_drafts`; invalid input → typed `{ ok: false, violations }` |
+| `content.publish` | mutation | copy draft → published (atomic); wakes consumer subscriptions |
+| `content.unpublish` | mutation | remove the published copy, keep the draft |
+| `session.me` | action | the resolved Subject (the editor's SSR gate reads it) |
+
+Validation and not-found are RESULT UNIONS, not thrown errors — `saveDraft`
+returns `{ ok: false, violations }` so the editor annotates the form, and
+`publish` returns `{ ok: false }` for a missing/foreign draft. The descriptors
+stay pure effect/Schema (browser-safe with nothing extra pulled in).
+
+## Run it
+
+```bash
+voltro dev .
+# → http://localhost:4000   (rpc + /auth/* HTTP routes)
+```
+
+`voltro dev` mints a unique `VOLTRO_SESSION_SECRET` into a gitignored
+`.env.local` on first boot — no secret ships with the template. It signs both
+the session cookie and CMS preview tokens.
+
+## Files
+
+```
+app.config.ts                 authRoutesPlugin + voltroPasswordStrategy (editor auth)
+content/
+  blogPost.contentType.ts     a content type as code (derived slug, rich text)
+  page.contentType.ts         a second type (Literal layout → <select>)
+  index.ts                    the type registry + name lookup
+database/schema.ts            core actors/tenants + contentTypeToEntities(...) tables
+actions/
+  content.types.*             the wire-safe type descriptors the editor renders
+  content.get.*               one row by id
+  me.action.*                 session.me
+queries/content.list.*        live, tenant-scoped, drafts-or-published
+mutations/
+  content.saveDraft.*         derive + validate + upsert draft
+  content.publish.*           draft → published
+  content.unpublish.*         take a published row down
+tests/                        write pipeline vs a real store + descriptor pins
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Durable content + editors | `store: 'postgres'` + `postgresUserStore({ sql })` |
+| A REST read API for consumers | mount `handleCmsRest(...)` (from `@voltro/cms`) — `GET /v1/cms/<type>`, API-key scoped |
+| Draft preview from a consumer app | `previewToken(type, id)` / `verifyPreviewToken` (HMAC over `VOLTRO_SESSION_SECRET`) |
+| Media fields | `Schema.Media()` + `@voltro/plugin-storage`; resolve keys with `resolveMedia(...)` |
+| A real rich-text editor | swap the `richText` widget via `<ContentForm widgets={{ richText: … }} />` in the editor |
+
+## Anti-patterns
+
+- **Expecting `*.contentType.ts` to be auto-discovered.** It isn't — register the
+  derived entities in `database/schema.ts` or the tables never migrate.
+- **Importing a content-type file into the browser.** The editor fetches
+  `content.types` instead; content-type files import the server `@voltro/cms`.
+- **Reusing a reserved field name** (`status`, `tenantId`, `publishAt`, the audit
+  columns). `defineContentType` throws — rename the field.

package/templates/apps/api-cms/actions/content.get.action.server.ts

@@ -0,0 +1,27 @@
+// Executor for `content.get`. Reads one row by id from the requested lifecycle
+// table. `ctx.store.query` runs through the tenant-scoped store spine, so the
+// read is automatically confined to the caller's tenant — a foreign id returns
+// nothing.
+import { eq } from '@voltro/database'
+import type { AppContext } from '@voltro/runtime'
+import { contentTypeByName } from '../content'
+
+const execute = async (
+  input: { type: string; id: string; status?: 'draft' | 'published' },
+  ctx: AppContext,
+) => {
+  const ct = contentTypeByName.get(input.type)
+  if (ct === undefined) return { row: null }
+  const table = `${ct.name}_${input.status === 'published' ? 'published' : 'drafts'}`
+  const rows = await ctx.store.query({
+    table,
+    predicate:  eq('id', input.id),
+    order:      [],
+    take:       1,
+    skip:       undefined,
+    projection: undefined,
+  })
+  return { row: rows[0] ?? null }
+}
+
+export default execute

package/templates/apps/api-cms/actions/content.get.action.ts

@@ -0,0 +1,19 @@
+// `content.get` — one content row by id, for the edit form. Returns the full
+// row (arbitrary per-type fields), so the output is a loose record rather than a
+// closed struct. `status` selects the table: 'draft' (the editor's in-progress
+// copy, the default) or 'published' (the live copy). A row outside the caller's
+// tenant reads as absent (null) — the store scope never returns it.
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const getContent = defineAction({
+  name:  'content.get',
+  input: Schema.Struct({
+    type:   Schema.NonEmptyString,
+    id:     Schema.NonEmptyString,
+    status: Schema.optional(Schema.Literal('draft', 'published')),
+  }),
+  output: Schema.Struct({
+    row: Schema.NullOr(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  }),
+})

package/templates/apps/api-cms/actions/content.types.action.server.ts

@@ -0,0 +1,26 @@
+// Executor for `content.types`. Projects the registered content types down to
+// the wire-safe descriptor the editor renders forms from (dropping the
+// server-only `derived.transform` function + nested element/struct depth — the
+// two shipped types are flat, and deep widgets fall back to a placeholder).
+import type { AppContext } from '@voltro/runtime'
+import { contentTypes as registered } from '../content'
+
+const execute = async (_input: Record<string, never>, _ctx: AppContext) => ({
+  types: registered.map((ct) => ({
+    name:        ct.name,
+    displayName: ct.displayName,
+    pluralName:  ct.pluralName,
+    columns:     ct.list?.columns ?? Object.keys(ct.fields),
+    fields: Object.entries(ct.fields).map(([name, field]) => ({
+      name,
+      kind:       field.kind,
+      editorHint: field.editorHint,
+      isOptional: field.isOptional,
+      ...(field.maxLength !== undefined ? { maxLength: field.maxLength } : {}),
+      ...(field.literals !== undefined ? { literals: field.literals } : {}),
+      ...(field.referenceType !== undefined ? { referenceType: field.referenceType } : {}),
+    })),
+  })),
+})
+
+export default execute

package/templates/apps/api-cms/actions/content.types.action.ts

@@ -0,0 +1,40 @@
+// `content.types` — the registered content-type descriptors, in a WIRE-SAFE
+// shape. The editor calls this once and renders a `<ContentForm>` per field
+// purely from `editorHint` + the field metadata — no content-type file is
+// imported into the browser bundle, so adding a type on the server surfaces in
+// the editor with zero client changes.
+//
+// A field's `derived.transform` is a FUNCTION (not serialisable) and the editor
+// doesn't need it — the transform runs server-side on save — so the executor
+// projects each field down to the data the form widgets read.
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+// The browser-facing view of one field: enough to pick + configure a widget.
+const FieldWire = Schema.Struct({
+  name:          Schema.String,
+  kind:          Schema.String,
+  editorHint:    Schema.String,
+  isOptional:    Schema.Boolean,
+  maxLength:     Schema.optional(Schema.Number),
+  literals:      Schema.optional(Schema.Array(Schema.String)),
+  referenceType: Schema.optional(Schema.String),
+})
+
+export const contentTypes = defineAction({
+  name:  'content.types',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    types: Schema.Array(
+      Schema.Struct({
+        name:        Schema.String,
+        displayName: Schema.String,
+        pluralName:  Schema.String,
+        // An ORDERED list (not a Record) so the editor renders fields in
+        // declaration order.
+        fields:  Schema.Array(FieldWire),
+        columns: Schema.Array(Schema.String),
+      }),
+    ),
+  }),
+})

package/templates/apps/api-cms/actions/me.action.server.ts

@@ -0,0 +1,18 @@
+// Executor for `session.me`. Reads the Subject the AuthMiddleware resolved (via
+// voltroPasswordStrategy reading the session cookie) and returns it.
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (_input: Record<string, never>, ctx: AppContext) => {
+  const subject = ctx.request.subject as {
+    readonly type: string
+    readonly id: string | null
+    readonly tenantId: string | null
+  }
+  return {
+    type:     subject.type,
+    id:       subject.id ?? null,
+    tenantId: subject.tenantId ?? null,
+  }
+}
+
+export default execute

package/templates/apps/api-cms/actions/me.action.ts

@@ -0,0 +1,16 @@
+// `session.me` — the caller's resolved identity. The editor's SSR gate reads it
+// to decide render-vs-redirect-to-login, and it proves the auth loop end to end:
+// no cookie → anonymous Subject; sign in via POST /auth/sign-in → a `user`
+// Subject. Browser-safe descriptor — no server imports here.
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const me = defineAction({
+  name:  'session.me',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    type:     Schema.String,
+    id:       Schema.NullOr(Schema.String),
+    tenantId: Schema.NullOr(Schema.String),
+  }),
+})

package/templates/apps/api-cms/app.config.ts

@@ -0,0 +1,61 @@
+// The headless CMS backend for the {{projectName}} project. Read by `voltro dev`.
+//
+// It composes @voltro/cms — a LIBRARY, not a plugin — with real editor auth:
+//
+//   • @voltro/cms — content types declared as code (`content/*.contentType.ts`
+//     via `defineContentType` + the `Schema` field DSL). `contentTypeToEntities`
+//     compiles each to a `<type>_drafts` + `<type>_published` table pair (see
+//     database/schema.ts), and the write pipeline (`saveDraft` → derive+validate,
+//     `publish`/`unpublish`) drives the lifecycle. There is NO framework
+//     discovery of `*.contentType.ts` — the schema file imports the types and
+//     registers their tables, which is what makes them migrate.
+//   • @voltro/plugin-auth — password sign-up/in/out over an HttpOnly session
+//     cookie so only signed-in editors reach the write surface, and
+//     `voltroPasswordStrategy` resolving that cookie into a typed `Subject`.
+//
+// Content is tenant-scoped: every derived content table carries `tenant()`, so
+// the runtime AND-merges `tenantId = subject.tenantId` into reads and stamps it
+// on writes — one tenant's drafts never leak to another. Boots ZERO-infra
+// (`store: 'memory'`, in-process users); the README shows the production swaps.
+import { defineEnv, envVar } from '@voltro/env'
+import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // HMAC key that signs + verifies the session cookie AND the CMS preview
+  // tokens (`previewToken` reads VOLTRO_SESSION_SECRET). `generate` means this
+  // project mints its OWN key into a gitignored `.env.local` on first boot — no
+  // value ships with the template (a shipped placeholder would be a signing key
+  // published to everyone who downloads it). Production mints its own the same
+  // way; a missing secret is a hard boot failure in serve/build/start.
+  VOLTRO_SESSION_SECRET: envVar.secret({
+    generate: 'base64url',
+    description: 'HMAC key that signs session cookies and CMS preview tokens.',
+  }),
+})
+
+// In-process user store — zero infra. `postgresUserStore({ sql })` for durable
+// editor accounts (it manages its own `_voltro_auth_*` tables, auto-migrated).
+const userStore = memoryUserStore()
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    authRoutesPlugin({
+      store: userStore,
+      // New editor sign-ups land in this tenant; all content they author is
+      // scoped to it.
+      defaultTenantId: 'acme',
+      successRedirect: '/',
+      cookieSecure: process.env.NODE_ENV === 'production',
+    }),
+  ],
+  auth: {
+    // Resolves the session cookie into the request Subject the handlers read
+    // (`ctx.request.subject`) and the store spine scopes writes by.
+    strategies: [voltroPasswordStrategy()],
+  },
+}

package/templates/apps/api-cms/content/blogPost.contentType.ts

@@ -0,0 +1,39 @@
+// A content type declared as CODE — typesafe, version-controlled, PR-reviewed.
+//
+// Each field uses the CMS `Schema` field DSL (distinct from the @voltro/database
+// column DSL). `defineContentType` resolves this to a descriptor the editor
+// introspects to generate its form, and `contentTypeToEntities` (in
+// database/schema.ts) compiles the fields DOWN to real `blogPost_drafts` +
+// `blogPost_published` columns.
+//
+// Imported from the MAIN `@voltro/cms` entry because it runs server-side at
+// discovery time (schema.ts imports it). The browser-safe field DSL is the same
+// object either way — the editor page never imports this file; it fetches the
+// resolved descriptor over rpc (content.types).
+import { Schema, defineContentType, derivedFrom, slugify } from '@voltro/cms'
+
+export const blogPost = defineContentType({
+  name:        'blogPost',
+  displayName: 'Blog post',
+  pluralName:  'Blog posts',
+  fields: {
+    // Single-line text, capped at 200 chars (validated at save time).
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    // Computed-on-save from `title` (a caller value is overwritten), constrained
+    // to url-safe chars, and UNIQUE per tenant — the derived tables get a real
+    // composite (tenantId, slug) DB UNIQUE.
+    slug: Schema.String.pipe(
+      Schema.pattern(/^[a-z0-9-]+$/),
+      Schema.unique(),
+      derivedFrom('title', slugify),
+    ),
+    // Rich text stored as a JSON document (e.g. a TipTap doc). Images allowed.
+    body: Schema.RichText({ allowImages: true }),
+    // Optional short summary → nullable column + non-required editor input.
+    excerpt: Schema.String.pipe(Schema.maxLength(280)).optional(),
+    // Optional publish date the consumer app can order/filter by.
+    publishedAt: Schema.DateTime.optional(),
+  },
+  // Which columns the editor's list view shows + its default sort.
+  list: { columns: ['title', 'slug', 'status'], defaultSort: { field: 'updatedAt', dir: 'desc' } },
+})

package/templates/apps/api-cms/content/index.ts

@@ -0,0 +1,18 @@
+// The registry of content types this CMS serves. Adding a type = declaring it
+// in a `*.contentType.ts` file and adding it here (+ its entities in
+// database/schema.ts). The handlers look a type up by name through
+// `contentTypeByName`; the editor lists them via the content.types action.
+import type { ContentType } from '@voltro/cms'
+import { blogPost } from './blogPost.contentType'
+import { page } from './page.contentType'
+
+export { blogPost, page }
+
+export const contentTypes: ReadonlyArray<ContentType> = [blogPost, page]
+
+/** Look a content type up by name — the guard the dynamic handlers run before
+ *  touching a `<type>_drafts` / `<type>_published` table (an unknown name never
+ *  reaches a table string). */
+export const contentTypeByName: ReadonlyMap<string, ContentType> = new Map(
+  contentTypes.map((t) => [t.name, t]),
+)

package/templates/apps/api-cms/content/page.contentType.ts

@@ -0,0 +1,24 @@
+// A second content type — a generic marketing/site page. Shows that adding a
+// content type is a single file: declare it here, register its entities in
+// database/schema.ts, and the editor picks it up automatically (it fetches the
+// registered types over content.types).
+import { Schema, defineContentType, derivedFrom, slugify } from '@voltro/cms'
+
+export const page = defineContentType({
+  name:        'page',
+  displayName: 'Page',
+  pluralName:  'Pages',
+  fields: {
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    slug: Schema.String.pipe(
+      Schema.pattern(/^[a-z0-9-]+$/),
+      Schema.unique(),
+      derivedFrom('title', slugify),
+    ),
+    body: Schema.RichText(),
+    // A closed value set → `<select>` in the editor + a CHECK constraint.
+    layout: Schema.Literal('default', 'wide', 'landing'),
+    seoTitle: Schema.String.pipe(Schema.maxLength(70)).optional(),
+  },
+  list: { columns: ['title', 'slug', 'layout', 'status'], defaultSort: { field: 'updatedAt', dir: 'desc' } },
+})

package/templates/apps/api-cms/database/schema.ts

@@ -0,0 +1,64 @@
+// Schema for the {{projectName}} CMS backend.
+//
+// The content TABLES aren't hand-declared — they're COMPILED from the content
+// types. `contentTypeToEntities(blogPost)` returns a `{ draft, published }` pair
+// (`blogPost_drafts` + `blogPost_published`), each already tenant-scoped
+// (`tenant()`, which pulls `audit()` transitively) and carrying the lifecycle
+// `status` column. Registering them in `databaseHandle` is what makes the
+// framework's auto-migrate create them across every dialect. There is no
+// discovery of `*.contentType.ts`; THIS import is the wiring.
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type ColumnDefinition,
+  type InferRow,
+  type Table,
+  type TableLike,
+} from '@voltro/database'
+import { contentTypeToEntities } from '@voltro/cms'
+import { blogPost, page } from '../content'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Derived content tables ----------
+
+// Compile each content type to its draft/published table pair. Exported so the
+// tests can build a schema registry over the SAME tables the app registers.
+export const blogEntities = contentTypeToEntities(blogPost)
+export const pageEntities = contentTypeToEntities(page)
+
+export type BlogPostDraft = InferRow<typeof blogEntities.draft>
+export type PageDraft = InferRow<typeof pageEntities.draft>
+
+// `contentTypeToEntities` returns the structural `TableLike` type (it hides the
+// concrete generic), but each value IS a real `table(...).with(tenant())` at
+// runtime — exactly what `databaseHandle` registers. This boundary cast bridges
+// the two: no `any`, no behavioural change, just the concrete table type the
+// handle's inference expects.
+const asTable = (t: TableLike): Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string> =>
+  t as unknown as Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>
+
+export const database = databaseHandle({
+  actors,
+  tenants,
+  blogPostDrafts:    asTable(blogEntities.draft),
+  blogPostPublished: asTable(blogEntities.published),
+  pageDrafts:        asTable(pageEntities.draft),
+  pagePublished:     asTable(pageEntities.published),
+})

package/templates/apps/api-cms/mutations/content.publish.mutation.server.ts

@@ -0,0 +1,19 @@
+// Effect-mode executor. `publishEffect` runs `publish` inside `store.transactional`
+// (draft copy + status flip land atomically) and fails typed `ContentNotFound`
+// when the id has no draft in the caller's scope — caught into `{ ok: false }`.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { publishEffect } from '@voltro/cms'
+import { contentTypeByName } from '../content'
+
+const execute = (input: { type: string; id: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const ct = contentTypeByName.get(input.type)
+    if (ct === undefined) return { ok: false as const }
+    return yield* publishEffect(ctx.store, ct, input.id).pipe(
+      Effect.map((row) => ({ ok: true as const, id: row['id'] as string, status: row['status'] as string })),
+      Effect.catchTag('ContentNotFound', () => Effect.succeed({ ok: false as const })),
+    )
+  })
+
+export default execute

package/templates/apps/api-cms/mutations/content.publish.mutation.ts

@@ -0,0 +1,15 @@
+// `content.publish` — copy a draft into `<type>_published` (atomic per row) and
+// mark the draft published. Both tables are reactive, so a publish wakes live
+// consumer subscriptions. A missing draft (including another tenant's, which
+// reads as absent) comes back as `{ ok: false }` rather than an error.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const publishContent = defineMutation({
+  name: 'content.publish',
+  input: Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString }),
+  output: Schema.Union(
+    Schema.Struct({ ok: Schema.Literal(true), id: Schema.String, status: Schema.String }),
+    Schema.Struct({ ok: Schema.Literal(false) }),
+  ),
+})

package/templates/apps/api-cms/mutations/content.saveDraft.mutation.server.ts

@@ -0,0 +1,36 @@
+// Effect-mode executor. `saveDraftEffect` runs the pipeline over the
+// request-scoped `ctx.store` (a DataStore): it derives the computed fields,
+// validates, and writes to `<type>_drafts` — the tenant/audit columns stamped
+// by the store spine. Its typed failures ride the Effect error channel, so we
+// `catchTag` them into the result union instead of letting them become a 500.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { saveDraftEffect } from '@voltro/cms'
+import { contentTypeByName } from '../content'
+
+const execute = (input: { type: string; values: Record<string, unknown> }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const ct = contentTypeByName.get(input.type)
+    if (ct === undefined) {
+      return {
+        ok: false as const,
+        violations: [{ field: 'type', rule: 'unknown', message: `unknown content type '${input.type}'` }],
+      }
+    }
+    return yield* saveDraftEffect(ctx.store, ct, input.values).pipe(
+      Effect.map((row) => ({ ok: true as const, id: row['id'] as string, status: row['status'] as string })),
+      // A rule violation → annotate the form; not an error.
+      Effect.catchTag('ContentValidationFailed', (e) =>
+        Effect.succeed({ ok: false as const, violations: [...e.violations] }),
+      ),
+      // A caller-pinned id owned by another tenant → refuse, surfaced the same way.
+      Effect.catchTag('ContentIdConflict', (e) =>
+        Effect.succeed({
+          ok: false as const,
+          violations: [{ field: 'id', rule: 'conflict', message: `id '${e.id}' belongs to another tenant` }],
+        }),
+      ),
+    )
+  })
+
+export default execute

package/templates/apps/api-cms/mutations/content.saveDraft.mutation.ts

@@ -0,0 +1,32 @@
+// `content.saveDraft` — upsert a draft. The executor runs the CMS pipeline
+// (derive `slug` from `title`, validate every field rule, write to
+// `<type>_drafts`). Validation failures don't crash: they come back as a typed
+// RESULT union (`{ ok: false, violations }`) the editor annotates the form from,
+// mirroring `contentViolations` on the client. Omit `values.id` to create; pass
+// it to update your own draft in place.
+//
+// The descriptor stays pure effect/Schema (no @voltro/cms import) so it is
+// browser-safe with nothing extra to pull into the bundle — the result union is
+// what carries the validation outcome across the wire.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+const Violation = Schema.Struct({
+  field:   Schema.String,
+  rule:    Schema.String,
+  message: Schema.String,
+})
+
+export const saveDraft = defineMutation({
+  name: 'content.saveDraft',
+  input: Schema.Struct({
+    type:   Schema.NonEmptyString,
+    // Arbitrary per-type field values (may carry `id` to update an existing
+    // draft). Validated on the server against the content type's rules.
+    values: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+  }),
+  output: Schema.Union(
+    Schema.Struct({ ok: Schema.Literal(true), id: Schema.String, status: Schema.String }),
+    Schema.Struct({ ok: Schema.Literal(false), violations: Schema.Array(Violation) }),
+  ),
+})

package/templates/apps/api-cms/mutations/content.unpublish.mutation.server.ts

@@ -0,0 +1,19 @@
+// Effect-mode executor. `unpublishEffect` deletes the published row + reverts
+// the draft inside a transaction; `ContentNotFound` (no published row in scope)
+// is caught into `{ ok: false }`.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { unpublishEffect } from '@voltro/cms'
+import { contentTypeByName } from '../content'
+
+const execute = (input: { type: string; id: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const ct = contentTypeByName.get(input.type)
+    if (ct === undefined) return { ok: false }
+    return yield* unpublishEffect(ctx.store, ct, input.id).pipe(
+      Effect.map(() => ({ ok: true })),
+      Effect.catchTag('ContentNotFound', () => Effect.succeed({ ok: false })),
+    )
+  })
+
+export default execute

package/templates/apps/api-cms/mutations/content.unpublish.mutation.ts

@@ -0,0 +1,11 @@
+// `content.unpublish` — take a published row down: delete it from
+// `<type>_published` and flip the draft back to `status: 'draft'` (atomic per
+// row). A row with no published copy in the caller's scope → `{ ok: false }`.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const unpublishContent = defineMutation({
+  name: 'content.unpublish',
+  input: Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString }),
+  output: Schema.Struct({ ok: Schema.Boolean }),
+})

package/templates/apps/api-cms/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.97.0",
+    "@effect/rpc": "^0.76.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/cms": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-auth": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
+    "@voltro/sql-postgres": "0.29.0",
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.29.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}