@materializecms/server 0.4.0 → 0.6.0

package/src/brief.d.ts

@@ -0,0 +1,43 @@
+import { type PageNode, type Theme } from '@materializecms/core/page';
+import type { BrandVoice } from '@materializecms/core/voice';
+import { type ApiCall, type SiteTool } from './tools.ts';
+/**
+ * A site from a brief: the AI reads a few lines about the business and builds the first pages
+ * with the section library. Everything it makes is a new draft: it never changes pages that
+ * already exist, shared sections or anything live. Colors, fonts and the brand voice are only
+ * proposed; the person applies them with a click.
+ */
+/** At most this many new drafts in one run. */
+export declare const BRIEF_MAX_PAGES = 8;
+export interface BriefResult {
+    created: {
+        id: string;
+        collection: string;
+        title: string;
+        url: string | null;
+    }[];
+    /** The whole theme as it would be with the proposal applied. */
+    theme: Theme | null;
+    voice: BrandVoice | null;
+}
+/** What a page may not carry when the AI makes it: links to shared content that is live. */
+export declare function plain(n: PageNode): PageNode;
+export declare function briefTools(call: ApiCall, options: {
+    onCreated: (doc: BriefResult['created'][number]) => void;
+    askVoice: boolean;
+    /** What the run made so far: a reply to the AI goes on from there. */
+    result?: BriefResult;
+}): {
+    tools: SiteTool[];
+    result: BriefResult;
+};
+/** The instructions for a run, in English like the other prompts; the pages are written in the site's language. */
+export declare function briefSystem(input: {
+    site: string;
+    language: string;
+    collections: string;
+    existing: string;
+    voice: string;
+    askVoice: boolean;
+    theme: boolean;
+}): string;

package/src/brief.js

@@ -0,0 +1,172 @@
+import { normalizeTheme } from '@materializecms/core/page';
+import { z } from 'zod';
+import { contentTools, pageTools, ToolError } from './tools.js';
+/**
+ * A site from a brief: the AI reads a few lines about the business and builds the first pages
+ * with the section library. Everything it makes is a new draft: it never changes pages that
+ * already exist, shared sections or anything live. Colors, fonts and the brand voice are only
+ * proposed; the person applies them with a click.
+ */
+/** At most this many new drafts in one run. */
+export const BRIEF_MAX_PAGES = 8;
+/** What a page may not carry when the AI makes it: links to shared content that is live. */
+export function plain(n) {
+    const { global: _g, component: _c, overrides: _o, ...rest } = n;
+    return { ...rest, children: n.children?.map(plain) };
+}
+const color = z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a hex color like #1a2b3c');
+const colors = z
+    .object({
+    bg: color,
+    surface: color,
+    text: color,
+    muted: color,
+    accent: color,
+    onAccent: color,
+    inverse: color,
+    onInverse: color,
+})
+    .partial();
+export function briefTools(call, options) {
+    const result = options.result ?? { created: [], theme: null, voice: null };
+    let schema = null;
+    const getSchema = async () => (schema ??= await call('GET', '/api/schema'));
+    const mine = (id) => {
+        if (!id || !result.created.some((d) => d.id === id))
+            throw new ToolError('You may change only the drafts you created in this run (create_entry); pages that already exist stay as they are.');
+        return id;
+    };
+    const pageFieldOf = async (collection) => (await getSchema()).collections.find((c) => c.name === collection)?.fields.find((f) => f.kind === 'page')?.name;
+    const base = contentTools(call, getSchema);
+    const pick = (name) => {
+        const t = base.find((x) => x.name === name);
+        if (!t)
+            throw new Error(`missing tool ${name}`);
+        return t;
+    };
+    const tools = [
+        ...['get_site', 'list_entries', 'get_entry', 'list_library', 'get_theme', 'list_media'].map(pick),
+        {
+            ...pick('create_entry'),
+            description: 'A new draft in a collection, with the fields given (see get_site for their names). The address (slug) follows the title when left out. For a page built on the canvas, leave the page field out and fill it afterwards with edit_page.',
+            run: async (input) => {
+                if (result.created.length >= BRIEF_MAX_PAGES)
+                    throw new ToolError(`At most ${BRIEF_MAX_PAGES} new drafts in one run: stop here.`);
+                const field = await pageFieldOf(input.collection);
+                const data = { ...input.data };
+                if (field)
+                    data[field] = Array.isArray(data[field]) ? data[field].map(plain) : [];
+                const doc = await call('POST', `/api/collections/${encodeURIComponent(input.collection)}`, { data, locale: input.locale });
+                const created = { id: doc.id, collection: doc.collection, title: doc.title, url: doc.url };
+                result.created.push(created);
+                options.onCreated(created);
+                return { id: doc.id, title: doc.title, url: doc.url, issues: doc.issues };
+            },
+        },
+        {
+            ...pick('update_entry'),
+            run: async (input) => {
+                const doc = await call('GET', `/api/documents/${encodeURIComponent(mine(input.id))}`);
+                const field = await pageFieldOf(doc.collection);
+                const data = { ...doc.data, ...input.data };
+                if (field && Array.isArray(data[field]))
+                    data[field] = data[field].map(plain);
+                const saved = await call('PUT', `/api/documents/${encodeURIComponent(doc.id)}`, {
+                    data,
+                });
+                const entry = result.created.find((d) => d.id === doc.id);
+                if (entry)
+                    Object.assign(entry, { title: saved.title, url: saved.url });
+                return { id: saved.id, title: saved.title, url: saved.url, issues: saved.issues };
+            },
+        },
+        ...pageTools({
+            withId: true,
+            brand: async () => (await getSchema()).site.name,
+            source: async (id) => {
+                const doc = await call('GET', `/api/documents/${encodeURIComponent(mine(id))}`);
+                const field = await pageFieldOf(doc.collection);
+                if (!field)
+                    throw new ToolError(`"${doc.title}" is not a page built on the canvas`);
+                let data = doc.data;
+                return {
+                    load: async () => (Array.isArray(data[field]) ? data[field] : []),
+                    save: async (nodes) => {
+                        data = { ...data, [field]: nodes.map(plain) };
+                        await call('PUT', `/api/documents/${encodeURIComponent(doc.id)}`, { data });
+                    },
+                };
+            },
+        }),
+        {
+            name: 'propose_theme',
+            title: 'Propongo colori e caratteri',
+            description: 'Proposes the site’s colors (light and dark), fonts (Google Fonts names) and roundness. Nothing changes now: the person sees the proposal at the end and applies it if they like it. Call it once, with the whole palette; pages built meanwhile use the theme tokens, so they follow it.',
+            input: z.object({
+                display: z.string().max(60).optional().describe('Font for titles'),
+                body: z.string().max(60).optional().describe('Font for text'),
+                colors: z.object({ light: colors.optional(), dark: colors.optional() }).optional(),
+                btnRadius: z.number().int().min(0).max(999).optional(),
+                cardRadius: z.number().int().min(0).max(64).optional(),
+            }),
+            run: async (input) => {
+                const { theme } = await call('GET', '/api/theme');
+                const next = normalizeTheme({
+                    ...theme,
+                    ...(input.display ? { display: input.display, displayCategory: undefined } : {}),
+                    ...(input.body ? { body: input.body, bodyCategory: undefined } : {}),
+                    ...(input.btnRadius !== undefined ? { btnRadius: input.btnRadius } : {}),
+                    ...(input.cardRadius !== undefined ? { cardRadius: input.cardRadius } : {}),
+                    colors: {
+                        light: { ...theme.colors.light, ...input.colors?.light },
+                        dark: { ...theme.colors.dark, ...input.colors?.dark },
+                    },
+                });
+                result.theme = next;
+                return 'Proposal kept: the person will choose whether to apply it.';
+            },
+        },
+    ];
+    if (options.askVoice)
+        tools.push({
+            name: 'propose_voice',
+            title: 'Propongo la voce del brand',
+            description: 'Proposes how the site speaks, from the brief: who the brand is and who it writes for, up to three tones, how readers are addressed, words to prefer and to avoid, other rules. Nothing is saved now: the person sees it at the end. Call it once.',
+            input: z.object({
+                about: z.string().max(1000).optional(),
+                tones: z.array(z.string().max(40)).max(3).optional(),
+                address: z.enum(['tu', 'voi', 'lei']).optional(),
+                prefer: z.string().max(500).optional(),
+                avoid: z.string().max(500).optional(),
+                rules: z.string().max(1000).optional(),
+            }),
+            run: async (input) => {
+                result.voice = input;
+                return 'Proposal kept: the person will choose whether to save it.';
+            },
+        });
+    return { tools, result };
+}
+/** The instructions for a run, in English like the other prompts; the pages are written in the site's language. */
+export function briefSystem(input) {
+    return `${input.voice ? `${input.voice}\n\n` : ''}You are building the first version of the website "${input.site}" in Materialize, a visual CMS. The person describes the business in a brief; you make the pages as drafts they will review, change and publish themselves.
+
+How to work:
+1. Read the site (get_site) and the section library (list_library). ${input.theme ? 'Look at the theme (get_theme) and propose colors and fonts that suit the business (propose_theme), once, before building: keep text and background contrast readable (WCAG AA) in light and dark.' : 'Keep the current theme: do not propose another one.'}${input.askVoice ? ' Propose the brand voice (propose_voice), once.' : ''}
+2. Plan a small site that fits the brief: usually a home and 2–4 more pages (at most ${BRIEF_MAX_PAGES}), only the ones the business needs.
+3. For each page: create the draft (create_entry, page field left empty, slug "home" for the home page when the address is free), then fill it with edit_page: add sections from the library (add_section) and rewrite every text for this business. Every page gets the same navigation at the top and footer at the bottom, with links to the pages you make (href "/" for the home, "/slug" for the others). Remove library placeholder texts you do not use; never leave "Lorem ipsum" or invented sample names.
+4. Fill the search engine field of each page when its collection has one (kind "seo", see get_site) with update_entry: {"title": up to 60 characters, "description": 120–160 characters}.
+5. Read each page once more (get_page) and fix what is left.
+
+Rules:
+- Write every text in ${input.language}, for real readers: concrete, short, no clichés.
+- Use only facts from the brief. Where a fact is missing (prices, addresses, phone numbers, names, numbers, testimonials), write a clear placeholder in square brackets, e.g. "[Indirizzo dello studio]", so the person sees what to fill in. Never invent reviews, clients, awards or figures.
+- Images: use pictures already in the media library (list_media) when they fit; otherwise keep the library's placeholder images and write a useful alt text describing the picture to add.
+- Pages that already exist stay untouched; do not create a page whose address is already taken (existing pages are listed below).
+- Reference pictures, when attached, show a look the person likes: take their mood, layout and colors, never their brand, logos or texts.
+
+Collections with pages built on the canvas: ${input.collections}
+Existing entries: ${input.existing}
+
+When done, reply with a short summary in ${input.language}: the pages made and what the person should complete (the bracketed placeholders, images). No lists of technical steps.`;
+}

package/src/forms.d.ts

@@ -0,0 +1,47 @@
+import { type FormDefinition } from '@materializecms/core/page';
+import type { SubmissionFile } from '@materializecms/db';
+/** Settings for every form, kept in the "forms" setting. */
+export interface FormsSettings {
+    /** Messages older than this many months are deleted with their files; unset keeps them. */
+    keepMonths?: number;
+    /** Signs webhook calls, so the receiver can tell they come from this site. */
+    webhookSecret?: string;
+}
+export interface FieldIssue {
+    field: string;
+    message: string;
+}
+/** A sent file, before it is saved. */
+export interface IncomingFile {
+    field: string;
+    name: string;
+    type: string;
+    bytes: Uint8Array;
+}
+/**
+ * What a form sent, checked against the form on the page: only its fields, the required ones
+ * filled in, emails that look like emails, choices from the list, files of the right kind and
+ * size. Without a definition (a form the site built by hand) the values are taken as they come.
+ */
+export declare function readSubmission(raw: Record<string, unknown>, def: FormDefinition | null): Promise<{
+    data: Record<string, string>;
+    files: IncomingFile[];
+    issues: FieldIssue[];
+}>;
+/**
+ * Why a message looks like spam, without a CAPTCHA: filled in at once, too many links, links
+ * hidden in markup. Null for a message that looks real. Repeats are checked by the caller.
+ */
+export declare function spamReason(data: Record<string, string>, elapsedMs: number | null): string | null;
+/** The same words from the same form: two identical messages in a day are a repeat. */
+export declare const fingerprintOf: (form: string, data: Record<string, string>) => string;
+/** Saves a message's files in its own folder, out of reach of the public site. */
+export declare function saveFiles(dir: string, id: string, files: IncomingFile[]): Promise<SubmissionFile[]>;
+export declare const removeFiles: (dir: string, id: string) => Promise<void>;
+/** The signature of a webhook body: `sha256=` and the HMAC of the body with the site's secret. */
+export declare const webhookSignature: (secret: string, body: string) => string;
+/**
+ * Posts a message to a webhook (Zapier, Make, n8n…), signed; tries three times, waiting a little
+ * longer each time. Resolves with whether it was taken.
+ */
+export declare function sendWebhook(url: string, payload: unknown, secret: string, wait?: (ms: number) => Promise<void>): Promise<boolean>;

package/src/forms.js

@@ -0,0 +1,153 @@
+import { createHash, createHmac } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { FILE_TYPES, FORM_FILE_MAX } from '@materializecms/core/page';
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const isFile = (v) => typeof v === 'object' && v !== null && 'arrayBuffer' in v && typeof v.name === 'string';
+/**
+ * What a form sent, checked against the form on the page: only its fields, the required ones
+ * filled in, emails that look like emails, choices from the list, files of the right kind and
+ * size. Without a definition (a form the site built by hand) the values are taken as they come.
+ */
+export async function readSubmission(raw, def) {
+    const data = {};
+    const files = [];
+    const issues = [];
+    if (!def) {
+        for (const [k, v] of Object.entries(raw)) {
+            if (k.startsWith('_') || typeof v !== 'string' || Object.keys(data).length >= 30)
+                continue;
+            data[k.slice(0, 80)] = v.slice(0, 5000);
+        }
+        return { data, files, issues };
+    }
+    for (const field of def.fields) {
+        const value = raw[field.name];
+        if (field.kind === 'file') {
+            const file = isFile(value) && value.size > 0 ? value : null;
+            if (!file) {
+                if (field.required)
+                    issues.push({ field: field.name, message: 'Allega un file' });
+                continue;
+            }
+            const allowed = FILE_TYPES[field.accept ?? 'any'];
+            if (!allowed.includes(extname(file.name).toLowerCase())) {
+                issues.push({ field: field.name, message: `Questo tipo di file non è accettato (${allowed.join(', ')})` });
+                continue;
+            }
+            if (file.size > FORM_FILE_MAX) {
+                issues.push({ field: field.name, message: `Il file supera ${FORM_FILE_MAX / 1024 / 1024} MB` });
+                continue;
+            }
+            files.push({
+                field: field.name,
+                name: file.name,
+                type: file.type,
+                bytes: new Uint8Array(await file.arrayBuffer()),
+            });
+            data[field.name] = file.name;
+            continue;
+        }
+        const text = typeof value === 'string' ? value.trim().slice(0, 5000) : '';
+        if (field.kind === 'checkbox') {
+            if (text)
+                data[field.name] = 'sì';
+            else if (field.required)
+                issues.push({ field: field.name, message: 'Va spuntata per inviare' });
+            continue;
+        }
+        if (!text) {
+            if (field.required)
+                issues.push({ field: field.name, message: 'Campo obbligatorio' });
+            continue;
+        }
+        if (field.kind === 'email' && !EMAIL.test(text)) {
+            issues.push({ field: field.name, message: 'Scrivi un indirizzo email valido' });
+            continue;
+        }
+        if (field.kind === 'select' && field.options?.length && !field.options.includes(text)) {
+            issues.push({ field: field.name, message: 'Scegli una delle voci dell’elenco' });
+            continue;
+        }
+        data[field.name] = text;
+    }
+    return { data, files, issues };
+}
+/** A form filled in faster than this is a bot (people need a few seconds at least). */
+const MIN_FILL_MS = 2500;
+/**
+ * Why a message looks like spam, without a CAPTCHA: filled in at once, too many links, links
+ * hidden in markup. Null for a message that looks real. Repeats are checked by the caller.
+ */
+export function spamReason(data, elapsedMs) {
+    if (elapsedMs !== null && elapsedMs >= 0 && elapsedMs < MIN_FILL_MS)
+        return 'Compilato in meno di 3 secondi';
+    const text = Object.values(data).join('\n');
+    if (/\[url=|<a\s+href|\[link=/i.test(text))
+        return 'Link nascosti nel testo';
+    const links = text.match(/https?:\/\/|www\./gi)?.length ?? 0;
+    if (links > 3)
+        return `Troppi link (${links})`;
+    return null;
+}
+/** The same words from the same form: two identical messages in a day are a repeat. */
+export const fingerprintOf = (form, data) => createHash('sha256')
+    .update(form)
+    .update(JSON.stringify(Object.entries(data)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => [k, v.toLowerCase().replace(/\s+/g, ' ')])))
+    .digest('hex');
+/** A file name safe on any disk, keeping its extension. */
+const safeName = (name) => name
+    .normalize('NFKD')
+    .replace(/[^\w.-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(-80) || 'file';
+/** Saves a message's files in its own folder, out of reach of the public site. */
+export async function saveFiles(dir, id, files) {
+    if (!files.length)
+        return [];
+    const folder = join(dir, id);
+    await mkdir(folder, { recursive: true });
+    const saved = [];
+    for (const [i, f] of files.entries()) {
+        const path = `${id}/${i + 1}-${safeName(f.name)}`;
+        await writeFile(join(dir, path), f.bytes);
+        saved.push({ field: f.field, name: f.name, size: f.bytes.length, type: f.type, path });
+    }
+    return saved;
+}
+export const removeFiles = (dir, id) => rm(join(dir, id), { recursive: true, force: true }).catch(() => { });
+/** The signature of a webhook body: `sha256=` and the HMAC of the body with the site's secret. */
+export const webhookSignature = (secret, body) => `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`;
+/**
+ * Posts a message to a webhook (Zapier, Make, n8n…), signed; tries three times, waiting a little
+ * longer each time. Resolves with whether it was taken.
+ */
+export async function sendWebhook(url, payload, secret, wait = (ms) => new Promise((r) => setTimeout(r, ms))) {
+    const body = JSON.stringify(payload);
+    for (const delay of [0, 20_000, 120_000]) {
+        if (delay)
+            await wait(delay);
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'user-agent': 'Materialize-Webhook',
+                    'x-materialize-signature': webhookSignature(secret, body),
+                },
+                body,
+                redirect: 'error',
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (res.ok)
+                return true;
+            // The receiver refused it on purpose: trying again would not help.
+            if (res.status >= 400 && res.status < 500 && res.status !== 429)
+                return false;
+        }
+        catch { }
+    }
+    return false;
+}

package/src/studio.d.ts

@@ -0,0 +1,13 @@
+import { type ApiCall, type SiteTool } from './tools.ts';
+export interface Touched {
+    id: string;
+    collection: string;
+    title: string;
+}
+export declare function studioTools(call: ApiCall, onTouched: (doc: Touched) => void): SiteTool[];
+export declare function studioSystem(input: {
+    site: string;
+    user: string;
+    voice: string;
+    limited: boolean;
+}): string;

package/src/studio.js

@@ -0,0 +1,75 @@
+import { collapseComponents, collapseGlobals, expandComponents, expandGlobals, } from '@materializecms/core/page';
+import { contentTools, pageTools, ToolError } from './tools.js';
+/**
+ * The request on the dashboard: the AI works on the whole site, in drafts only. It cannot
+ * publish, schedule, share or change what is live at once (the theme, shared sections,
+ * components): those stay with the person, in the panel.
+ */
+/** Tools that act on the live site at once: left out. */
+const LIVE = new Set([
+    'publish_entry',
+    'unpublish_entry',
+    'schedule_entry',
+    'share_preview',
+    'update_theme',
+    'publish_release',
+    'schedule_release',
+]);
+export function studioTools(call, onTouched) {
+    let schema = null;
+    const getSchema = async () => (schema ??= await call('GET', '/api/schema'));
+    const touched = (doc) => doc.collection && onTouched({ id: doc.id, collection: doc.collection, title: doc.title });
+    const base = contentTools(call, getSchema)
+        .filter((t) => !LIVE.has(t.name))
+        .map((t) => ['create_entry', 'update_entry', 'translate_entry'].includes(t.name)
+        ? {
+            ...t,
+            run: async (input) => {
+                const out = (await t.run(input));
+                if (out?.id) {
+                    const doc = await call('GET', `/api/documents/${encodeURIComponent(out.id)}`);
+                    touched(doc);
+                }
+                return out;
+            },
+        }
+        : t);
+    const page = pageTools({
+        withId: true,
+        brand: async () => (await getSchema()).site.name,
+        source: async (id) => {
+            if (!id)
+                throw new ToolError('Say which page: its id');
+            const doc = await call('GET', `/api/documents/${encodeURIComponent(id)}`);
+            const def = (await getSchema()).collections.find((c) => c.name === doc.collection);
+            const field = def?.fields.find((f) => f.kind === 'page')?.name;
+            if (!field)
+                throw new ToolError(`"${doc.title}" is not a page built on the canvas`);
+            const { globals } = await call('GET', '/api/globals');
+            const { components } = await call('GET', '/api/components');
+            return {
+                load: async () => expandComponents(expandGlobals(Array.isArray(doc.data[field]) ? doc.data[field] : [], globals), components),
+                save: async (nodes) => {
+                    const withRefs = collapseComponents(nodes, components);
+                    const collapsed = collapseGlobals(withRefs.nodes);
+                    const changedShared = JSON.stringify(withRefs.components) !== JSON.stringify(components) ||
+                        Object.entries(collapsed.globals).some(([k, v]) => JSON.stringify(v) !== JSON.stringify(globals[k]));
+                    if (changedShared)
+                        throw new ToolError('That changes a shared section or a component, which is live on every page at once: leave it as it is and tell the person to change it in the editor. Nothing was saved.');
+                    await call('PUT', `/api/documents/${encodeURIComponent(doc.id)}`, {
+                        data: { ...doc.data, [field]: collapsed.nodes },
+                    });
+                    touched(doc);
+                },
+            };
+        },
+    });
+    return [...base, ...page];
+}
+export function studioSystem(input) {
+    return `${input.voice ? `${input.voice}\n\n` : ''}You are the assistant on the dashboard of Materialize, the CMS of the website "${input.site}". ${input.user} asks you for something about the site: pages, articles, texts, translations, the search engine fields.
+
+Work with the tools: look first (get_site, list_entries, get_entry, get_page), then change. Every change goes into drafts: you cannot publish, schedule, share or change the theme, shared sections (menus, footers) or components. When something needs those, do the rest and say what the person should do in the panel.
+Change only what was asked; keep the design and the ids of existing nodes; prefer library sections for new ones. Use only facts you find on the site or in the request: where one is missing, write a placeholder in square brackets.
+${input.limited ? 'This person may change only contents (texts, links, images), not layout or design.\n' : ''}When done, reply in the person's language in two or three short sentences: what you changed and what to check before publishing. If you could not do something, say so.`;
+}

package/src/tools.d.ts

@@ -38,6 +38,7 @@ type CollectionInfo = {
     titleField?: string;
     slugField?: string;
 };
+export type SiteSchema = Schema;
 type Schema = {
     site: {
         name: string;

package/src/tools.js

@@ -1,5 +1,6 @@
 import { buildSection, LIBRARY } from '@materializecms/core/library';
 import { cloneNode, collapseComponents, collapseGlobals, expandComponents, expandGlobals, findNode, insertNode, newId, plainText, removeNode, updateNode, } from '@materializecms/core/page';
+import { voicePrompt } from '@materializecms/core/voice';
 import { z } from 'zod';
 /** An answer the model can act on: what went wrong, in words. */
 export class ToolError extends Error {
@@ -257,7 +258,14 @@ export function assistantTools(call, page, brand) {
         },
     });
     return [
-        ...contentTools(call, getSchema).filter((t) => t.name !== 'publish_entry' && t.name !== 'unpublish_entry'),
+        ...contentTools(call, getSchema).filter((t) => ![
+            'publish_entry',
+            'unpublish_entry',
+            'schedule_entry',
+            'share_preview',
+            'publish_release',
+            'schedule_release',
+        ].includes(t.name)),
         ...pageTools({ source, withId: false, brand: async () => brand }),
     ];
 }
@@ -267,13 +275,15 @@ export function contentTools(call, getSchema) {
         tool({
             name: 'get_site',
             title: 'Guardo il sito',
-            description: 'The site: its name, languages and collections (pages, articles, projects…) with their fields. Start here.',
+            description: 'The site: its name, languages, collections (pages, articles, projects…) with their fields, and its brand voice: follow it in every text you write. Start here.',
             input: z.object({}),
             readOnly: true,
             run: async () => {
                 const s = await getSchema();
+                const voice = voicePrompt((await call('GET', '/api/voice').catch(() => null))?.voice);
                 return {
                     site: s.site,
+                    ...(voice ? { brandVoice: voice } : {}),
                     locales: s.locales,
                     collections: s.collections.map((c) => ({
                         name: c.name,
@@ -368,6 +378,83 @@ export function contentTools(call, getSchema) {
                 return { id: doc.id, title: doc.title, published: false };
             },
         }),
+        tool({
+            name: 'schedule_entry',
+            title: 'Programmo',
+            description: 'Sets when an entry goes on the public site (publish) or comes off it (unpublish) by itself, as an ISO date with time zone, e.g. 2026-11-10T09:00:00+01:00. at null cancels. The draft as it is at that moment is what gets published.',
+            input: z.object({
+                id: z.string(),
+                action: z.enum(['publish', 'unpublish']),
+                at: z.string().nullable(),
+            }),
+            run: async (input) => {
+                const doc = await call('PUT', `/api/documents/${encodeURIComponent(input.id)}/schedule`, { action: input.action, at: input.at });
+                return {
+                    id: doc.id,
+                    title: doc.title,
+                    publishAt: doc.schedule.publish?.runAt ?? null,
+                    unpublishAt: doc.schedule.unpublish?.runAt ?? null,
+                };
+            },
+        }),
+        tool({
+            name: 'share_preview',
+            title: 'Creo un link di anteprima',
+            description: 'A secret link that shows an entry’s latest saved draft with the site’s design to someone without an account (a client, a colleague). It follows later edits. days: how long it works (default 7), null until revoked.',
+            input: z.object({
+                id: z.string(),
+                days: z.number().int().min(1).max(365).nullable().optional(),
+            }),
+            run: async (input) => {
+                const link = await call('POST', `/api/documents/${encodeURIComponent(input.id)}/previews`, { days: input.days === undefined ? 7 : input.days });
+                return { url: link.url, expiresAt: link.expiresAt };
+            },
+        }),
+        tool({
+            name: 'list_releases',
+            title: 'Guardo i rilasci',
+            description: 'Releases: groups of entries that go on (or off) the site together, all or nothing, by hand or at a set time. Each with its entries, whether it is ready and what stops it.',
+            input: z.object({}),
+            readOnly: true,
+            run: () => call('GET', '/api/releases'),
+        }),
+        tool({
+            name: 'create_release',
+            title: 'Creo un rilascio',
+            description: 'A new, empty release with a name (e.g. "Collezione inverno"). Add entries with add_to_release.',
+            input: z.object({ name: z.string().min(1).max(120) }),
+            run: (input) => call('POST', '/api/releases', input),
+        }),
+        tool({
+            name: 'add_to_release',
+            title: 'Aggiungo al rilascio',
+            description: 'Puts an entry in a release: its draft is published when the release goes out (action "publish"), or it is taken off the site (action "unpublish"). An entry is in one release at a time. remove: true takes it out of the release.',
+            input: z.object({
+                release: z.string().describe('The release id'),
+                id: z.string().describe('The entry id'),
+                action: z.enum(['publish', 'unpublish']).default('publish'),
+                remove: z.boolean().optional(),
+            }),
+            run: (input) => input.remove
+                ? call('DELETE', `/api/releases/${encodeURIComponent(input.release)}/items/${encodeURIComponent(input.id)}`)
+                : call('PUT', `/api/releases/${encodeURIComponent(input.release)}/items/${encodeURIComponent(input.id)}`, {
+                    action: input.action,
+                }),
+        }),
+        tool({
+            name: 'publish_release',
+            title: 'Pubblico il rilascio',
+            description: 'Puts everything in a release on the public site now. All entries must be ready, or nothing goes out and the reasons come back.',
+            input: z.object({ release: z.string() }),
+            run: (input) => call('POST', `/api/releases/${encodeURIComponent(input.release)}/publish`),
+        }),
+        tool({
+            name: 'schedule_release',
+            title: 'Programmo il rilascio',
+            description: 'Sets when a release goes out by itself, as an ISO date with time zone, e.g. 2026-11-10T09:00:00+01:00; at null: only by hand. The drafts as they are at that moment go out.',
+            input: z.object({ release: z.string(), at: z.string().nullable() }),
+            run: (input) => call('PUT', `/api/releases/${encodeURIComponent(input.release)}/schedule`, { at: input.at }),
+        }),
         tool({
             name: 'list_translations',
             title: 'Guardo le lingue',

package/src/wordpress.d.ts

@@ -75,6 +75,8 @@ export interface ConvertContext {
 }
 /** Every image address in some HTML, the original size first (WordPress adds "-1024x768"). */
 export declare function imagesIn(html: string): string[];
+/** Each image address in some HTML with its alternative text, for the library. */
+export declare function imageAltsIn(html: string): Map<string, string>;
 /** The full-size original of a resized WordPress image: "foto-1024x768.jpg" → "foto.jpg". */
 export declare const originalOf: (url: string) => string;
 /** HTML to Materialize rich text: paragraphs, titles, lists, quotes and images (from the library). */