@materializecms/server 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ Ogni versione, dalla più recente. Le novità in arrivo si scrivono sotto «Pros
 
 ## Prossima versione
 
+## 0.4.0 — 2026-11-03
+
+- **Immagini di riferimento nell'assistente**: allega, incolla (⌘V) o trascina nella chat lo screenshot di un sito che ti piace, un mockup o uno schizzo, e l'assistente ne riprende impaginazione e atmosfera con le sezioni e lo stile del tuo sito. Fino a 4 immagini per messaggio; non vanno nella libreria e non finiscono sulla pagina.
+- **Conversazioni con l'assistente più solide**: un secondo messaggio dopo aver cambiato la selezione sulla tela non fallisce più, e ogni nuovo messaggio rilegge dalla cache tutta la conversazione precedente, così costa una frazione.
+- **L'assistente costa meno**: con Claude usa la cache dei prompt, così istruzioni, strumenti e pagina, rimandati a ogni passaggio, si pagano a una frazione del prezzo dopo il primo.
+- **Azioni rapide più economiche**: ✨ sui testi, SEO e testo alternativo usano Claude Haiku 5.5, molto più economico di Opus; l'assistente e le traduzioni delle pagine restano sul modello principale. Si può scegliere un altro modello in Impostazioni → AI e MCP.
+- **Uso dell'AI del mese** in Impostazioni → AI e MCP: richieste, token letti (e quanti dalla cache) e scritti, per tenere d'occhio la spesa.
+- **AI sul testo formattato**: il pulsante ✨ c'è anche nel corpo degli articoli, e riscrive, accorcia o traduce mantenendo titoli, elenchi, grassetti, link e immagini.
+- **✨ sulla tela mantiene grassetti, corsivi e link** di un testo, nell'Inspector e in modalità Contenuto.
+- **Accorcia e Allunga più affidabili**: chiedono una lunghezza precisa (circa un terzo in meno, circa la metà in più), così un testo breve non torna quasi uguale e uno da allungare non diventa sette volte più lungo.
+- **L'AI rispetta la lunghezza dei campi**: un testo riscritto non supera più il massimo del campo (prima, per esempio, un sommario di 220 caratteri poteva arrivare a 234 e bloccare la pubblicazione).
+- **Descrivi con l'AI conserva i crediti**: il testo alternativo nuovo mantiene il credito della foto già scritto, come «foto di … su Unsplash», e la sua lingua.
+- **Nastri con i bordi sfumati**: le lettere che scendono sotto la riga (g, p, y) non vengono più tagliate in basso.
+- **Indirizzi del pannello scritti a mano**: `/admin/media`, `/admin/persone` e `/admin/impostazioni` portano alla sezione giusta, se nessuna raccolta ha quel nome.
+
+## 0.3.0 — 2026-11-01
+
+- **Backup fuori dal server**, ogni notte e cifrati, su uno spazio S3 compatibile (Cloudflare R2, Backblaze B2, Hetzner, Amazon S3…) o in una cartella WebDAV (Nextcloud, NAS Synology e QNAP…). Si attiva in Impostazioni → Backup; `materialize decrypt` rende di nuovo leggibili i file scaricati.
+- **Email più facile da configurare**: si sceglie il fornitore (Brevo, Postmark, Mailgun, Amazon SES, Gmail…) e il server si compila da solo; se la prova non riesce, il pannello spiega perché (porta bloccata, password rifiutata, mittente non verificato…); **Controlla il dominio** verifica SPF, DKIM e DMARC.
+- **Pannello più chiaro**: Impostazioni → Protezione divisa in Sicurezza, Backup e Registro attività; barra dell'editor a gruppi, con gli elementi meno usati in **⋯**; pannello sinistro dell'editor allargabile; menu a tendina, intestazioni e testi d'aiuto uniformi e più leggibili; pagina dedicata per gli indirizzi del pannello che non esistono; in Persone, chi entra con la sola password si riconosce a colpo d'occhio; accesso e installazione con l'aspetto del pannello.
+- **Chi ha fatto ogni versione**: la cronologia mostra il nome dell'autore accanto alla data.
+- **Informazioni su Materialize** in Impostazioni: versione, autore, licenza, novità, guida e licenze di terzi.
+
 ## 0.2.0 — 2026-11-01
 
 - **Password dimenticata?** nella pagina di accesso: un link per email, valido un'ora. Senza email configurata, il comando `materialize reset-password` stampa il link sul server, anche per l'unico amministratore.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Cristiano Casazza
+Copyright (c) 2026 Cristiano Casazza Consulting
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@materializecms/server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Il server di Materialize: API, accessi, media, backup, aggiornamenti dal pannello e server MCP.",
   "type": "module",
   "license": "MIT",
@@ -20,9 +20,9 @@
   "dependencies": {
     "@anthropic-ai/sdk": "1.3.0",
     "@hono/node-server": "2.1.5",
-    "@materializecms/admin": "0.2.0",
-    "@materializecms/core": "0.2.0",
-    "@materializecms/db": "0.2.0",
+    "@materializecms/admin": "0.4.0",
+    "@materializecms/core": "0.4.0",
+    "@materializecms/db": "0.4.0",
     "@modelcontextprotocol/sdk": "1.32.2",
     "hono": "4.13.14",
     "htmlparser2": "12.0.0",

package/src/ai.d.ts

@@ -11,9 +11,29 @@ export interface AiSettings {
     baseUrl: string;
     /** Empty: the default (Claude Opus 5.5 for Anthropic). */
     model: string;
+    /**
+     * For the quick actions (✨ on a text, SEO, alternative text). Empty: Claude Haiku 5.5 for
+     * Anthropic, the main model for a compatible server.
+     */
+    fastModel?: string;
+    /** Told the tokens of every request (never saved). */
+    onUsage?: (usage: AiUsage) => void;
+}
+/** The tokens of one or more requests: what the provider bills. */
+export interface AiUsage {
+    requests: number;
+    /** Read at full price. */
+    input: number;
+    output: number;
+    /** Read from the prompt cache, at a fraction of the price. */
+    cacheRead: number;
+    /** Written to the prompt cache, at a little more than the full price. */
+    cacheWrite: number;
 }
 export declare const EMPTY_AI: AiSettings;
 export declare const DEFAULT_CLAUDE = "claude-opus-5-5";
+/** Short, one-shot texts: a fraction of Opus's price, quality enough for them. */
+export declare const DEFAULT_CLAUDE_FAST = "claude-haiku-5-5";
 /** Raised when the AI cannot answer: not set up, refused, or the provider failed. */
 export declare class AiError extends Error {
 }
@@ -22,12 +42,19 @@ export declare function publicAi(s: AiSettings | null): {
     provider: 'anthropic' | 'openai';
     baseUrl: string;
     model: string;
+    fastModel?: string;
+    onUsage?: (usage: AiUsage) => void;
     hasKey: boolean;
     envKey: boolean;
     ready: boolean;
 };
 /** Claude needs a key (saved, or ANTHROPIC_API_KEY); a compatible server needs an address and a model. */
 export declare function isReady(s: AiSettings | null): s is AiSettings;
+/** A picture sent to the model: base64, in one of the formats every provider reads. */
+export interface AiImage {
+    mime: 'image/png' | 'image/jpeg' | 'image/webp';
+    data: string;
+}
 /** Progress of an assistant turn, sent to the panel as it happens. */
 export type AiEvent = {
     type: 'status';
@@ -45,7 +72,10 @@ export interface Conversation {
     provider: AiSettings['provider'];
     messages: unknown[];
 }
-/** Text in, text out: a rewrite, a translation, an alt text (with an image). */
+/**
+ * Text in, text out: a rewrite, a translation, an alt text (with an image). `fast`: on the model
+ * for the quick actions.
+ */
 export declare function complete(s: AiSettings, input: {
     system: string;
     prompt: string;
@@ -53,6 +83,7 @@ export declare function complete(s: AiSettings, input: {
         data: string;
         mime: string;
     };
+    fast?: boolean;
 }): Promise<string>;
 /**
  * One turn of the assistant: the person's message, then as many tool calls as the model needs
@@ -61,10 +92,13 @@ export declare function complete(s: AiSettings, input: {
 export declare function runTurn(s: AiSettings, conv: Conversation, input: {
     system: string;
     text: string;
+    /** Pictures attached to the message: references to look at, not files for the site. */
+    images?: AiImage[];
     tools: SiteTool[];
     onEvent: (e: AiEvent) => void;
     maxSteps?: number;
 }): Promise<string>;
+export declare const fastModelOf: (s: AiSettings) => string;
 /**
  * Translates a page's texts in batches, keeping their order: each batch goes out as a JSON list
  * and must come back as a list of the same length. Marks like <b>, <i> and <a1> stay in place.

package/src/ai.js

@@ -1,8 +1,10 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { z } from 'zod';
 import { ToolError } from './tools.js';
-export const EMPTY_AI = { provider: 'anthropic', apiKey: '', baseUrl: '', model: '' };
+export const EMPTY_AI = { provider: 'anthropic', apiKey: '', baseUrl: '', model: '', fastModel: '' };
 export const DEFAULT_CLAUDE = 'claude-opus-5-5';
+/** Short, one-shot texts: a fraction of Opus's price, quality enough for them. */
+export const DEFAULT_CLAUDE_FAST = 'claude-haiku-5-5';
 /** Raised when the AI cannot answer: not set up, refused, or the provider failed. */
 export class AiError extends Error {
 }
@@ -18,8 +20,13 @@ export function isReady(s) {
         return !!process.env.ANTHROPIC_API_KEY;
     return s.provider === 'anthropic' ? !!(s.apiKey || process.env.ANTHROPIC_API_KEY) : !!(s.baseUrl && s.model);
 }
-/** Text in, text out: a rewrite, a translation, an alt text (with an image). */
+/**
+ * Text in, text out: a rewrite, a translation, an alt text (with an image). `fast`: on the model
+ * for the quick actions.
+ */
 export async function complete(s, input) {
+    if (input.fast)
+        s = { ...s, model: fastModelOf(s) };
     if (s.provider === 'openai') {
         const content = input.image
             ? [
@@ -54,6 +61,8 @@ export async function complete(s, input) {
             },
         ],
     });
+    if (message.stop_reason === 'refusal')
+        throw new AiError('La richiesta è stata rifiutata dal modello.');
     return textOf(message).trim();
 }
 /**
@@ -61,6 +70,7 @@ export async function complete(s, input) {
  * (at most `maxSteps`), then its answer. The conversation keeps everything for the next turn.
  */
 export async function runTurn(s, conv, input) {
+    const images = input.images ?? [];
     const byName = new Map(input.tools.map((t) => [t.name, t]));
     const runTool = async (name, raw) => {
         const t = byName.get(name);
@@ -87,7 +97,15 @@ export async function runTurn(s, conv, input) {
             function: { name: t.name, description: t.description, parameters: schemaOf(t) },
         }));
         const messages = conv.messages;
-        messages.push({ role: 'user', content: input.text });
+        messages.push({
+            role: 'user',
+            content: images.length
+                ? [
+                    ...images.map((i) => ({ type: 'image_url', image_url: { url: `data:${i.mime};base64,${i.data}` } })),
+                    { type: 'text', text: input.text },
+                ]
+                : input.text,
+        });
         for (let step = 0; step < maxSteps; step++) {
             const reply = await openaiChat(s, { messages: [{ role: 'system', content: input.system }, ...messages], tools });
             messages.push(reply);
@@ -117,14 +135,31 @@ export async function runTurn(s, conv, input) {
         input_schema: schemaOf(t),
     }));
     const messages = conv.messages;
-    messages.push({ role: 'user', content: input.text });
+    messages.push({
+        role: 'user',
+        content: images.length
+            ? [
+                ...images.map((i) => ({
+                    type: 'image',
+                    source: { type: 'base64', media_type: i.mime, data: i.data },
+                })),
+                { type: 'text', text: input.text },
+            ]
+            : input.text,
+    });
+    // Each step sends the instructions, the tools and the whole conversation again (the page read
+    // with get_page included): from the cache they cost a fraction. A fixed point after the
+    // instructions and tools, and the automatic one at the end of the conversation, which moves
+    // forward step by step.
+    const system = [{ type: 'text', text: input.system, cache_control: { type: 'ephemeral' } }];
     for (let step = 0; step < maxSteps; step++) {
         const message = await claude(s, {
             max_tokens: 16000,
             output_config: { effort: 'medium' },
             // Progress notes between tool calls, so the panel can say what is happening.
             ...(updatesSupported(s) ? { thinking: { type: 'adaptive', display: 'updates' } } : {}),
-            system: input.system,
+            cache_control: { type: 'ephemeral' },
+            system,
             tools,
             messages,
         });
@@ -151,6 +186,7 @@ export async function runTurn(s, conv, input) {
 /** Models that take the server-side fallback on a refusal and progress notes between tool calls. */
 const CURRENT = /^claude-(opus-5-5|opus-5|sonnet-5-5|fable-5-1)$/;
 const modelOf = (s) => s.model.trim() || DEFAULT_CLAUDE;
+export const fastModelOf = (s) => s.fastModel?.trim() || (s.provider === 'anthropic' ? DEFAULT_CLAUDE_FAST : s.model.trim());
 const updatesSupported = (s) => /^claude-(opus-5-5|sonnet-5-5|fable-5-1|fable-5)$/.test(modelOf(s));
 async function claude(s, params) {
     const client = new Anthropic({ apiKey: s.apiKey || undefined, baseURL: s.baseUrl || undefined });
@@ -163,12 +199,20 @@ async function claude(s, params) {
     if ('thinking' in params && params.thinking?.display === 'updates')
         betas.push('thinking-display-updates-2026-08-18');
     try {
-        return await client.beta.messages.create({
+        const message = await client.beta.messages.create({
             ...params,
             model,
             ...(betas.length ? { betas } : {}),
             ...(fallback ? { fallbacks: 'default' } : {}),
         });
+        s.onUsage?.({
+            requests: 1,
+            input: message.usage.input_tokens,
+            output: message.usage.output_tokens,
+            cacheRead: message.usage.cache_read_input_tokens ?? 0,
+            cacheWrite: message.usage.cache_creation_input_tokens ?? 0,
+        });
+        return message;
     }
     catch (error) {
         if (error instanceof Anthropic.AuthenticationError)
@@ -179,6 +223,9 @@ async function claude(s, params) {
             throw new AiError(`Il modello “${model}” non esiste.`);
         if (error instanceof Anthropic.RateLimitError)
             throw new AiError('Troppe richieste ad Anthropic: riprova tra poco.');
+        // The reasoning of earlier turns no longer fits the conversation (it was changed underneath).
+        if (error instanceof Anthropic.BadRequestError && /thinking/i.test(error.message))
+            throw new AiError('Questa conversazione non può continuare: iniziane una nuova con ↺ in alto.');
         if (error instanceof Anthropic.BadRequestError)
             throw new AiError(`Richiesta non valida: ${error.message}`);
         if (error instanceof Anthropic.APIError)
@@ -214,6 +261,17 @@ async function openaiChat(s, body) {
     const json = (await res.json().catch(() => null));
     if (!res.ok)
         throw new AiError(json?.error?.message ?? `Il server AI ha risposto ${res.status}.`);
+    if (json?.usage) {
+        // Cached tokens are part of the prompt tokens here: the rest is the full-price part.
+        const cached = json.usage.prompt_tokens_details?.cached_tokens ?? 0;
+        s.onUsage?.({
+            requests: 1,
+            input: (json.usage.prompt_tokens ?? 0) - cached,
+            output: json.usage.completion_tokens ?? 0,
+            cacheRead: cached,
+            cacheWrite: 0,
+        });
+    }
     const message = json?.choices?.[0]?.message;
     if (!message)
         throw new AiError('Il server AI ha dato una risposta vuota.');