@materializecms/server 0.5.0 → 0.7.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/mail.d.ts

@@ -30,7 +30,9 @@ export declare function sendMail(m: MailSettings, message: {
     to: string;
     subject: string;
     text: string;
+    html?: string;
     replyTo?: string;
+    headers?: Record<string, string>;
 }): Promise<void>;
 /** A message from a site form as plain text: one "Label: value" per field. */
 export declare function submissionText(page: string, data: Record<string, string>): string;

package/src/newsletter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The newsletter as an email: an HTML version that reads well in every email app (one column,
+ * inline styles, absolute addresses) and a plain text one. With statistics on, a tiny picture
+ * tells when it is opened and links pass through the site, signed so they cannot be bent to
+ * send people elsewhere.
+ */
+type Lang = 'it' | 'en';
+export declare const langOf: (locale: string | null | undefined) => Lang;
+export interface NewsletterContent {
+    site: string;
+    /** The site's public address, for links and pictures. */
+    siteUrl: string;
+    subject: string;
+    preheader: string;
+    body: unknown[];
+    /** The site's accent color, for links and buttons. */
+    accent: string;
+    /** The sender's details, shown at the bottom (often required by law: a postal address). */
+    footer: string;
+    unsubscribeUrl: string;
+    /** Statistics: the picture that tells the email was opened, and each link through the site. */
+    openUrl?: string;
+    link?: (href: string) => string;
+    locale?: string | null;
+}
+export declare function newsletterHtml(c: NewsletterContent): string;
+/** The same newsletter as plain text, for email apps that show no HTML. */
+export declare function newsletterText(c: NewsletterContent): string;
+/** The email that asks a new subscriber to confirm. */
+export declare function confirmEmail(input: {
+    site: string;
+    url: string;
+    accent: string;
+    locale?: string | null;
+}): {
+    subject: string;
+    text: string;
+    html: string;
+};
+/** The signature of a tracked link: without it, the address would redirect anywhere. */
+export declare function linkSignature(sendId: string, url: string, secret: string): string;
+export declare function validLink(sendId: string, url: string, signature: string, secret: string): boolean;
+/** A 1×1 transparent GIF: the "opened" picture. */
+export declare const PIXEL: Buffer<ArrayBuffer>;
+/** Addresses out of a CSV export (Mailchimp, Brevo, a spreadsheet): the email column, and a name if there is one. */
+export declare function parseSubscribersCsv(text: string): {
+    email: string;
+    name?: string;
+}[];
+export {};

package/src/newsletter.js

@@ -0,0 +1,192 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { richTextHtml } from '@materializecms/core/page';
+const WORDS = {
+    it: {
+        unsubscribe: 'Non vuoi più ricevere queste email? Disiscriviti',
+        why: 'Ricevi questa email perché ti sei iscritto alla newsletter di {site}.',
+        confirmSubject: 'Conferma l’iscrizione alla newsletter di {site}',
+        confirmIntro: 'Ciao! Per ricevere la newsletter di {site} conferma il tuo indirizzo:',
+        confirmButton: 'Confermo l’iscrizione',
+        confirmIgnore: 'Se non ti sei iscritto tu, ignora questa email: senza conferma non riceverai niente.',
+        view: 'Apri nel browser',
+    },
+    en: {
+        unsubscribe: 'Don’t want these emails any more? Unsubscribe',
+        why: 'You get this email because you signed up for the {site} newsletter.',
+        confirmSubject: 'Confirm your subscription to the {site} newsletter',
+        confirmIntro: 'Hi! To get the {site} newsletter, confirm your address:',
+        confirmButton: 'Confirm my subscription',
+        confirmIgnore: 'If you did not sign up, ignore this email: without confirming you will get nothing.',
+        view: 'Open in your browser',
+    },
+};
+export const langOf = (locale) => locale?.toLowerCase().startsWith('it') ? 'it' : 'en';
+const say = (lang, key, site) => (WORDS[lang][key] ?? key).replace('{site}', site);
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** An address on the site made absolute; others stay as they are. */
+const absolute = (href, base) => {
+    try {
+        return new URL(href, `${base.replace(/\/$/, '')}/`).toString();
+    }
+    catch {
+        return href;
+    }
+};
+/** Inline styles: email apps drop style sheets. */
+const STYLE = {
+    p: 'margin:0 0 16px;font-size:16px;line-height:1.6;',
+    h2: 'margin:28px 0 12px;font-size:22px;line-height:1.3;font-weight:700;',
+    h3: 'margin:24px 0 10px;font-size:18px;line-height:1.35;font-weight:700;',
+    h4: 'margin:20px 0 8px;font-size:16px;line-height:1.4;font-weight:700;',
+    ul: 'margin:0 0 16px;padding-left:22px;font-size:16px;line-height:1.6;',
+    li: 'margin:0 0 6px;',
+    blockquote: 'margin:0 0 16px;padding:4px 0 4px 16px;border-left:3px solid #d4d4d8;color:#52525b;font-style:italic;',
+    figure: 'margin:0 0 16px;',
+    img: 'display:block;max-width:100%;height:auto;border:0;border-radius:8px;',
+};
+export function newsletterHtml(c) {
+    const lang = langOf(c.locale);
+    let body = richTextHtml(c.body);
+    body = body.replace(/(src|href)="([^"]*)"/g, (_, attr, value) => {
+        const raw = value.replace(/&amp;/g, '&');
+        const abs = absolute(raw, c.siteUrl);
+        const out = attr === 'href' && c.link && /^https?:/i.test(abs) ? c.link(abs) : abs;
+        return `${attr}="${esc(out)}"`;
+    });
+    body = body.replace(/<(p|h2|h3|h4|ul|li|blockquote|figure|img)(\s|>)/g, (_, tag, after) => {
+        return `<${tag} style="${STYLE[tag]}"${after}`;
+    });
+    body = body.replace(/<a /g, `<a style="color:${esc(c.accent)};text-decoration:underline;" `);
+    body = body.replace(/ loading="lazy" decoding="async"/g, '');
+    const footer = c.footer.trim() ? `<p style="margin:0 0 8px;">${esc(c.footer.trim()).replace(/\n/g, '<br>')}</p>` : '';
+    return `<!doctype html>
+<html lang="${lang}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(c.subject)}</title></head>
+<body style="margin:0;padding:0;background:#f4f4f5;">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0;">${esc(c.preheader)}</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#f4f4f5;">
+<tr><td align="center" style="padding:32px 16px;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:600px;background:#ffffff;border-radius:12px;">
+<tr><td style="padding:28px 32px 8px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:14px;font-weight:700;color:#18181b;">${esc(c.site)}</td></tr>
+<tr><td style="padding:8px 32px 24px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b;">
+<h1 style="margin:0 0 20px;font-size:26px;line-height:1.25;font-weight:700;">${esc(c.subject)}</h1>
+${body}
+</td></tr>
+</table>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:600px;">
+<tr><td style="padding:20px 32px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:12px;line-height:1.6;color:#71717a;text-align:center;">
+${footer}<p style="margin:0 0 8px;">${esc(say(lang, 'why', c.site))}</p>
+<p style="margin:0;"><a href="${esc(c.unsubscribeUrl)}" style="color:#71717a;text-decoration:underline;">${esc(say(lang, 'unsubscribe', c.site))}</a></p>
+</td></tr>
+</table>
+</td></tr>
+</table>
+${c.openUrl ? `<img src="${esc(c.openUrl)}" width="1" height="1" alt="" style="display:block;border:0;width:1px;height:1px;">` : ''}
+</body>
+</html>`;
+}
+/** The same newsletter as plain text, for email apps that show no HTML. */
+export function newsletterText(c) {
+    const lang = langOf(c.locale);
+    const lines = [c.subject, ''];
+    const runs = (b) => (b.children ?? [])
+        .map((r) => (r.href ? `${r.text ?? ''} (${absolute(r.href, c.siteUrl)})` : (r.text ?? '')))
+        .join('');
+    for (const b of c.body) {
+        if (b.type === 'image')
+            continue;
+        const text = runs(b).trim();
+        if (!text)
+            continue;
+        if (b.type === 'listItem')
+            lines.push(`- ${text}`);
+        else if (b.type === 'heading')
+            lines.push('', text.toUpperCase(), '');
+        else
+            lines.push(text, '');
+    }
+    lines.push('—', ...(c.footer.trim() ? [c.footer.trim()] : []), say(lang, 'why', c.site));
+    lines.push(`${say(lang, 'unsubscribe', c.site)}: ${c.unsubscribeUrl}`);
+    return lines.join('\n');
+}
+/** The email that asks a new subscriber to confirm. */
+export function confirmEmail(input) {
+    const lang = langOf(input.locale);
+    const subject = say(lang, 'confirmSubject', input.site);
+    const text = [say(lang, 'confirmIntro', input.site), '', input.url, '', say(lang, 'confirmIgnore', input.site)].join('\n');
+    const html = `<!doctype html><html lang="${lang}"><body style="margin:0;padding:32px 16px;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:520px;margin:0 auto;background:#ffffff;border-radius:12px;"><tr><td style="padding:28px 32px;">
+<p style="margin:0 0 20px;font-size:16px;line-height:1.6;">${esc(say(lang, 'confirmIntro', input.site))}</p>
+<p style="margin:0 0 24px;"><a href="${esc(input.url)}" style="display:inline-block;padding:12px 20px;border-radius:8px;background:${esc(input.accent)};color:#ffffff;font-weight:600;text-decoration:none;">${esc(say(lang, 'confirmButton', input.site))}</a></p>
+<p style="margin:0;font-size:13px;line-height:1.6;color:#71717a;">${esc(say(lang, 'confirmIgnore', input.site))}</p>
+</td></tr></table></body></html>`;
+    return { subject, text, html };
+}
+/** The signature of a tracked link: without it, the address would redirect anywhere. */
+export function linkSignature(sendId, url, secret) {
+    return createHmac('sha256', secret).update(`${sendId}\n${url}`).digest('base64url').slice(0, 22);
+}
+export function validLink(sendId, url, signature, secret) {
+    const expected = Buffer.from(linkSignature(sendId, url, secret));
+    const given = Buffer.from(signature);
+    return expected.length === given.length && timingSafeEqual(expected, given);
+}
+/** A 1×1 transparent GIF: the "opened" picture. */
+export const PIXEL = Buffer.from('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7', 'base64');
+/** Addresses out of a CSV export (Mailchimp, Brevo, a spreadsheet): the email column, and a name if there is one. */
+export function parseSubscribersCsv(text) {
+    const lines = text
+        .replace(/^/, '')
+        .split(/\r?\n/)
+        .filter((l) => l.trim());
+    if (!lines.length)
+        return [];
+    const sep = [';', ',', '\t'].sort((a, b) => (lines[0]?.split(b).length ?? 0) - (lines[0]?.split(a).length ?? 0))[0] ?? ',';
+    const cells = (l) => {
+        const out = [];
+        let cur = '';
+        let quoted = false;
+        for (let i = 0; i < l.length; i++) {
+            const ch = l[i];
+            if (ch === '"') {
+                if (quoted && l[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else
+                    quoted = !quoted;
+            }
+            else if (ch === sep && !quoted) {
+                out.push(cur);
+                cur = '';
+            }
+            else
+                cur += ch;
+        }
+        out.push(cur);
+        return out.map((c) => c.trim());
+    };
+    const head = cells(lines[0] ?? '').map((h) => h.toLowerCase());
+    const isEmail = (v) => /^[^\s@,;]+@[^\s@,;]+\.[^\s@,;]+$/.test(v);
+    let emailCol = head.findIndex((h) => /e-?mail/.test(h));
+    const nameCol = head.findIndex((h) => /^(name|nome|first name|nome e cognome|full name)$/.test(h));
+    let rows = lines.slice(1);
+    // No header: the column holding addresses, from the first line on.
+    if (emailCol < 0) {
+        emailCol = cells(lines[0] ?? '').findIndex(isEmail);
+        rows = lines;
+    }
+    if (emailCol < 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const l of rows) {
+        const c = cells(l);
+        const email = (c[emailCol] ?? '').toLowerCase();
+        if (!isEmail(email) || seen.has(email))
+            continue;
+        seen.add(email);
+        out.push({ email, ...(nameCol >= 0 && c[nameCol] ? { name: c[nameCol] } : {}) });
+    }
+    return out;
+}

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;