@aeratic/pagetailor 0.4.0 → 0.6.0

package/README.md

@@ -2,14 +2,58 @@
 
 Pages as data. Define your app's pages in YAML, bind them to a typed catalog of components and data sources, tailor them per role and per person with small patches, and let an AI agent compose them through a validation gate. Rendering is done by [json-render](https://github.com/vercel-labs/json-render).
 
-```
-npm init -y
+## Start here
+
+```bash
+# 1. Install and create the project
 npm install @aeratic/pagetailor react react-dom
 npx pagetailor init
+
+# 2. Check that everything fits together
 npx pagetailor validate
-npx pagetailor dev        # http://localhost:4747/?user=giulia&role=marketing
+
+# 3. Run the preview and the Studio
+npx pagetailor dev
+#   http://localhost:4747/?user=giulia&role=marketing   the page as Giulia sees it
+#   http://localhost:4747/?role=magazzino               the same page for the warehouse role
+#   http://localhost:4747/?view=studio                  visual editor of the whole project
+
+# 4. Enable the AI agent with any provider: Anthropic, OpenAI, Gemini, Groq, Mistral, DeepSeek, xAI, OpenRouter, Ollama…
+ANTHROPIC_API_KEY=sk-... npx pagetailor dev
+OPENAI_API_KEY=sk-... npx pagetailor dev
+PAGETAILOR_PROVIDER=ollama PAGETAILOR_MODEL=llama3.3 npx pagetailor dev
+
+# 5. After editing components/registry.yaml, regenerate the component index
+npx pagetailor registry
 ```
 
+Three things to try in the first ten minutes:
+
+- **Change one user's layout.** Open `pagetailor/overrides/user-giulia.yaml`, move a row in `areas`, save: the browser reloads with her new page. Nobody else's page changes.
+- **Break something on purpose.** Put a data source that does not exist in `pages/home.yaml`. `validate` refuses it, and in the preview that widget becomes a red box with the reason while the rest of the page still renders.
+- **Ask the agent.** Type "put the KPI at the top" in the *Change this page…* box. The patch it writes is an ordinary override, checked by the same validator as your own edits.
+
+What pagetailor is not: a CMS, a page builder for end users, or an authenticated server. It is an engine for declarative pages with a gate that humans, the Studio and agents all go through. `pagetailor dev` writes project files over an unauthenticated API and binds to localhost only.
+
+## CLI
+
+| Command | What it does |
+| --- | --- |
+| `pagetailor init [--force]` | create `pagetailor/` with manifest, tokens, data catalog, a sample page, overrides and base components |
+| `pagetailor validate` | check manifest, pages and overrides against the component registry and the data catalog; exit 1 on problems |
+| `pagetailor registry` | write `pagetailor/components/index.js` exporting every component in `registry.yaml` |
+| `pagetailor dev [--port 4747] [--host 127.0.0.1]` | preview server with live reload and the Studio; pass `--host 0.0.0.0` to expose it |
+| `pagetailor help`, `pagetailor --version` | this text, the version |
+
+## Contents
+
+- [What `init` creates](#what-init-creates)
+- [A page](#a-page), [An override](#an-override), [The gate](#the-gate), [Component props](#component-props)
+- [Next.js](#nextjs), [Caching](#caching)
+- [Proposals and approval](#proposals-and-approval), [Reorder editor](#reorder-editor)
+- [The agent](#the-agent), [Pages as answers](#pages-as-answers)
+- [Studio](#studio), [Status](#status)
+
 ## What `init` creates
 
 ```
@@ -106,6 +150,8 @@ Changes go through `propose(root, { name, override, author, role })`, which firs
 - Each page lists the roles allowed to approve it in `manifest.yaml`: `owners: { home: [admin] }`.
 - `approve(root, { name, version, approver, approverRole })` re-runs the gate and commits a new applied version with `approvedFrom`; the proposal is marked `approved`. `reject(root, { name, version, approver, approverRole, reason })` marks it `rejected`. `listPending(root)` lists open proposals, newest first.
 
+Roles named in a proposal (the target role of a `role-*` override, the `role` of a user proposal, the `approverRole` of an approval) must exist in `manifest.roles`.
+
 Dev server routes: `POST /api/propose`, `GET /api/pending`, `POST /api/approve`, `POST /api/reject` (400 with `{ ok: false, errors }` when the gate or owner check fails). `POST /api/override` still commits directly.
 
 ## Reorder editor
@@ -125,9 +171,17 @@ A user asks in natural language ("put the KPI at the top"); the agent turns it i
 3. `runAgent(root, { page, user, role, request, complete })` appends the patches to the user's existing override for that page (same merge rule as the editor) and calls `propose` as `user-<user>`: applied at once for the own user, pending otherwise.
 4. If the gate rejects, the gate errors are sent back once ("The previous patch was rejected: ... Fix it.") and the result is proposed again. The result reports `attempts`.
 
-`complete` is any `async ({ system, user }) => text`, so any model or SDK works; pagetailor depends on none. `anthropicComplete({ apiKey, model })` is a built-in fetch call to the Anthropic Messages API (`claude-sonnet-5-5` by default).
+`complete` is any `async ({ system, user }) => text`, so any model or SDK works; pagetailor depends on none. Built-in adapters over plain `fetch`: `anthropicComplete`, `openaiComplete` (OpenAI and every provider speaking its chat-completions format), `googleComplete` (Gemini). `createComplete({ provider, model, apiKey, baseUrl })` picks one by name: `anthropic`, `openai`, `google`, `groq`, `mistral`, `deepseek`, `xai`, `openrouter`, `ollama` (local, no key) or `compatible` (any URL). `completeFromEnv()` reads the same from the environment and is what `pagetailor dev` uses:
+
+| Variable | Meaning |
+| --- | --- |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `OPENROUTER_API_KEY` | the key of the provider to use; with one key set nothing else is needed |
+| `PAGETAILOR_PROVIDER` | force a provider when several keys are set, or choose `ollama` / `compatible` |
+| `PAGETAILOR_MODEL` | the model; defaults exist for anthropic, openai, google, mistral, deepseek, required for the others |
+| `PAGETAILOR_LLM_URL` | base URL for `compatible`, or to override a provider's URL (a proxy, an Ollama on another host) |
+| `PAGETAILOR_LLM_KEY` | the key for `compatible` |
 
-In `pagetailor dev`, set `ANTHROPIC_API_KEY` (and optionally `PAGETAILOR_MODEL`) and use the "Change this page…" box in the header: `POST /api/agent` with `{ page, user, role, request }` (503 without the key). `GET /api/agent/prompt?page=&user=&role=&request=` returns the built prompt for debugging.
+In `pagetailor dev`, set one of the variables above and use the "Change this page…" box in the header: `POST /api/agent` with `{ page, user, role, request }` (503 when no provider is configured). `GET /api/agent/prompt?page=&user=&role=&request=` returns the built prompt for debugging.
 
 ## Pages as answers
 
@@ -138,7 +192,17 @@ A user asks a question ("how did sales go this week?") and the agent composes a
 3. Keep as page: `keepAnswer(root, { user, role, title, tree, why })` writes `pages/<slug>.yaml` with `owner: <user>` and adds the slug to `manifest.pages` (slugs are made unique with `-2`, `-3`).
 4. Pin to home: `pinAnswer(root, { user, role, title, tree, why })` proposes, as `user-<user>`, an `insert` of a `layout/card` with the answer's widgets into the home's main container; on a grid it gets its own full-width row at the bottom. Same gate and proposal rules as any override.
 
-Both go through the gate with the user's role first. In `pagetailor dev` use the "Ask…" box: `POST /api/ask` `{ user, role, request }` (503 without `ANTHROPIC_API_KEY`), `POST /api/ask/keep` and `POST /api/ask/pin` with `{ user, role, title, tree, why }`.
+Both go through the gate with the user's role first. In `pagetailor dev` use the "Ask…" box: `POST /api/ask` `{ user, role, request }` (503 when no provider is configured), `POST /api/ask/keep` and `POST /api/ask/pin` with `{ user, role, title, tree, why }`.
+
+## Studio
+
+`pagetailor dev` has two views in the top bar: **Preview** (the app as rendered, with the editor and agent boxes) and **Studio**, a visual editor for the whole `pagetailor/` project (`http://localhost:4747/?view=studio`). The first tab, **App**, edits `manifest.yaml`: name, home, navigation position, pages (adding one creates `pages/<slug>.yaml` with an empty `layout/stack`; the home page cannot be removed), roles (a role still used as a page owner or by a data source cannot be removed) and page owners.
+
+The **Pages** tab edits `pages/<slug>.yaml`: a tree of the page's components (with the child name under a grid and the bound data source) and an inspector for the selected node. The component select lists every `name@version` in the registry (switching keeps the props the new schema still declares), props are form fields generated from the registry schema (free JSON when a component has none), the data select offers only the catalog sources whose type the component accepts, with their params. Containers can add, remove and reorder children; a grid renames and removes named children together with their cells in `areas`, and a new child gets a full-width row. The tree is validated live with the same `validateTree` as the server, so problems show before Save.
+
+The files stay the source of truth: each tab loads its file into a draft, the YAML pane at the bottom shows the draft as it will be written, and **Save** writes the file through the same validator as `pagetailor validate` (errors are shown in red and nothing is written; saving a page also re-applies every override that extends it, so renaming a child that an override targets is refused with the override's name). Saves rewrite the file keeping its top-level comments. Every save is versioned under `.history/files/<name>/NNNN.json` with the content before and after and a `why` (versions are allocated exclusively, so concurrent writers never collide); **Undo** restores the previous content as a new version. The **auto-save** checkbox saves 1.5 s after the last change.
+
+Routes: `GET /api/project`, `GET|PUT|DELETE /api/files/<name>`, `GET /api/files/<name>/history`, `POST /api/files/<name>/undo`, where `<name>` is `manifest`, `tokens`, `data-catalog`, `components/registry`, `pages/<slug>` or `overrides/<name>`. The same functions are exported: `readProjectFile`, `writeProjectFile`, `deleteProjectFile`, `listFileHistory`, `undoFile`, `scaffoldSource`, `scaffoldComponent`.
 
 ## Status
 

package/bin/cli.js

@@ -3,21 +3,28 @@ import { init } from "../src/init.js";
 import { validate } from "../src/validate.js";
 import { dev } from "../src/dev.js";
 import { writeRegistryFile } from "../src/registry-file.js";
+import { readFile } from "node:fs/promises";
 
 const [cmd, ...args] = process.argv.slice(2);
 const flag = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+const version = async () => JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
 const help = `pagetailor <command>
 
   init [--force]     create pagetailor/ with manifest, tokens, data catalog, a sample page, overrides and base components
   validate           check manifest, pages and overrides against the component registry and the data catalog
   registry          write pagetailor/components/index.js exporting every component in registry.yaml
-  dev [--port 4747]  preview server with live reload; ?page=home&user=giulia&role=marketing
+  dev [--port 4747] [--host 127.0.0.1]
+                    preview server with live reload (localhost only unless --host is given); ?page=home&user=giulia&role=marketing
+  help              this text
+  --version, -v     print the version
 `;
 
 try {
   if (cmd === "init") await init(process.cwd(), args);
   else if (cmd === "validate") process.exitCode = (await validate(process.cwd())) ? 0 : 1;
   else if (cmd === "registry") { const r = await writeRegistryFile(process.cwd()); console.log(`wrote ${r.path} (${r.count} components)`); }
-  else if (cmd === "dev") await dev(process.cwd(), { port: Number(flag("--port", 4747)) });
-  else { console.log(help); if (cmd && cmd !== "help") process.exitCode = 1; }
+  else if (cmd === "dev") await dev(process.cwd(), { port: Number(flag("--port", 4747)), host: flag("--host", "127.0.0.1") });
+  else if (cmd === "--version" || cmd === "-v" || cmd === "version") console.log(await version());
+  else if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") console.log(help);
+  else { console.error(`pagetailor: unknown command "${cmd}"\n`); console.log(help); process.exitCode = 1; }
 } catch (e) { console.error("pagetailor:", e.message); process.exitCode = 1; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pages as data: declarative YAML pages, typed data catalog, per-user overrides, validated for AI agents. Renders with json-render.",
   "license": "MIT",
   "type": "module",

package/src/agent.js

@@ -1,6 +1,5 @@
 import { join } from "node:path";
-import { writeFile } from "node:fs/promises";
-import { stringify } from "yaml";
+import { writeYaml } from "./yaml-write.js";
 import { loadProject, loadPage, loadOverrides, loadYaml, exists, listPages } from "./loader.js";
 import { applyOverride, mergePatch } from "./overrides.js";
 import { splitRef, validateTree } from "./validator.js";
@@ -185,10 +184,10 @@ export async function keepAnswer(root, { user, role, title, tree, why }) {
   const taken = new Set([...(await listPages(root)), ...(project.manifest.pages ?? [])]);
   const base = slugify(title); let slug = base;
   for (let n = 2; taken.has(slug); n++) slug = `${base}-${n}`;
-  await writeFile(join(root, "pages", `${slug}.yaml`), stringify({ page: slug, title, owner: user, ...(why ? { why } : {}), layout: tree }));
+  await writeYaml(join(root, "pages", `${slug}.yaml`), { page: slug, title, owner: user, ...(why ? { why } : {}), layout: tree });
   const mfile = join(root, "manifest.yaml");
   const manifest = (await loadYaml(mfile)) ?? {};
-  await writeFile(mfile, stringify({ ...manifest, pages: [...(manifest.pages ?? []), slug] }));
+  await writeYaml(mfile, { ...manifest, pages: [...(manifest.pages ?? []), slug] });
   return { ok: true, page: slug };
 }
 

package/src/dev.js

@@ -10,11 +10,13 @@ import { commitOverride, listHistory, rollback } from "./history.js";
 import { propose, listPending, approve, reject } from "./proposals.js";
 import { tokensToCss } from "./tokens.js";
 import { buildAgentPrompt, runAgent, runAsk, keepAnswer, pinAnswer } from "./agent.js";
-import { anthropicComplete } from "./llm.js";
+import { completeFromEnv, LLM_HELP } from "./llm.js";
+import { isProjectFile, readProjectFile, writeProjectFile, deleteProjectFile, listFileHistory, undoFile, readProject, scaffoldSource, scaffoldComponent } from "./files.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
-export async function dev(cwd, { port = 4747 } = {}) {
+// Binds to localhost only: the API writes project files and has no authentication. Pass host to expose it.
+export async function dev(cwd, { port = 4747, host = "127.0.0.1" } = {}) {
   const root = join(cwd, "pagetailor");
   // Bundle one React only: the project's if installed, otherwise the one shipped with this package.
   const reqProject = createRequire(join(cwd, "package.json")), reqSelf = createRequire(import.meta.url);
@@ -26,94 +28,28 @@ export async function dev(cwd, { port = 4747 } = {}) {
   alias["@aeratic/pagetailor/client"] = join(here, "client.jsx");
   const nodePaths = [join(cwd, "node_modules"), join(here, "..", "node_modules")];
 
-  // one generated entry: imports every component from registry.yaml, mounts <Page>
-  const entry = async () => {
-    const reg = await loadYaml(join(root, "components", "registry.yaml"));
-    const imports = [], map = [];
-    let i = 0;
-    for (const [name, def] of Object.entries(reg)) for (const [ver, v] of Object.entries(def.versions ?? {})) {
-      if (!v.impl) continue; const id = `C${i++}`;
-      imports.push(`import ${id} from ${JSON.stringify(v.impl)};`);
-      map.push(`${JSON.stringify(`${name}@${ver}`)}: ${id}`);
-    }
-    return `${imports.join("\n")}
-import { createRoot } from "react-dom/client";
-import { useCallback, useEffect, useState } from "react";
-import { Page, EditorContext, useEditor } from ${JSON.stringify(join(here, "client.jsx"))};
-const registry = { ${map.join(", ")} };
-function App() {
-  const q = new URLSearchParams(location.search);
-  const [page, setPage] = useState(q.get("page") || "__home__");
-  const [user, setUser] = useState(q.get("user") || "");
-  const [role, setRole] = useState(q.get("role") || "");
-  const [state, setState] = useState(null);
-  const load = useCallback(() => fetch(\`/api/page/\${page}?user=\${user}&role=\${role}\`).then(r => r.json()).then(setState), [page, user, role]);
-  useEffect(() => { load(); }, [load]);
-  // keep page/user/role in the URL: the file watcher reloads the tab after an override is written
-  useEffect(() => { const u = new URLSearchParams({ page, user, role }); history.replaceState(null, "", "?" + u); }, [page, user, role]);
-  const editor = useEditor({ page: state?.page, user, role, why: "reordered in the editor", onApplied: r => { if (!r.pending) load(); } });
-  const [ask, setAsk] = useState(""), [agent, setAgent] = useState(null);
-  const sendAsk = async e => {
-    e.preventDefault(); if (!ask.trim()) return;
-    setAgent({ text: "thinking…" });
-    try {
-      const r = await (await fetch("/api/agent", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ page: state.page, user, role: role || undefined, request: ask }) })).json();
-      if (r.ok) setAgent({ text: (r.proposal.pending ? "sent for approval: " : "applied: ") + (r.reply.why ?? "") });
-      else setAgent({ error: true, text: r.refuse ?? (r.errors ?? [r.error ?? "agent failed"]).join("; ") });
-    } catch (err) { setAgent({ error: true, text: err.message }); }
-  };
-  const [question, setQuestion] = useState(""), [answer, setAnswer] = useState(null), [answerStatus, setAnswerStatus] = useState(null);
-  const post = (path, b) => fetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(b) }).then(r => r.json());
-  const sendQuestion = async e => {
-    e.preventDefault(); if (!question.trim()) return;
-    setAnswer(null); setAnswerStatus({ text: "composing…" });
-    try {
-      const r = await post("/api/ask", { user, role: role || undefined, request: question });
-      if (r.ok) { setAnswer(r); setAnswerStatus(null); }
-      else setAnswerStatus({ error: true, text: r.refuse ?? (r.errors ?? [r.error ?? "ask failed"]).join("; ") });
-    } catch (err) { setAnswerStatus({ error: true, text: err.message }); }
-  };
-  const answerBody = () => ({ user, role: role || undefined, title: answer.title, tree: answer.tree, why: answer.why });
-  const keep = async () => {
-    const r = await post("/api/ask/keep", answerBody());
-    if (r.ok) { setAnswer(null); setAnswerStatus(null); setPage(r.page); } else setAnswerStatus({ error: true, text: (r.errors ?? [r.error]).join("; ") });
-  };
-  const pin = async () => {
-    const r = await post("/api/ask/pin", answerBody());
-    setAnswerStatus(r.ok ? { text: r.pending ? "sent for approval" : "applied to home" } : { error: true, text: (r.errors ?? [r.error]).join("; ") });
-  };
-  useEffect(() => { const es = new EventSource("/events"); es.onmessage = () => location.reload(); return () => es.close(); }, []);
-  if (!state) return null;
-  const pages = state.manifest.pages, roles = state.manifest.roles ?? [];
-  return <>
-    <header style={{ display: "flex", gap: 12, alignItems: "center", padding: "10px 16px", borderBottom: "1px solid var(--pt-color-border)", background: "var(--pt-color-surface)", fontSize: 13 }}>
-      <strong>{state.manifest.app}</strong>
-      <label>page <select value={state.page} onChange={e => setPage(e.target.value)}>{pages.map(p => <option key={p}>{p}</option>)}</select></label>
-      <label>user <input value={user} placeholder="giulia" onChange={e => setUser(e.target.value)} style={{ width: 90 }} /></label>
-      <label>role <select value={role} onChange={e => setRole(e.target.value)}><option value="">(none)</option>{roles.map(r => <option key={r}>{r}</option>)}</select></label>
-      <button onClick={() => editor.setEditing(!editor.editing)} style={{ fontWeight: editor.editing ? 700 : 400 }}>{editor.editing ? "Done editing" : "Edit layout"}</button>
-      {editor.status === "saving" && <span>saving…</span>}
-      {editor.status === "pending" && <span>sent for approval</span>}
-      {editor.status === "error" && <span style={{ color: "var(--pt-color-danger)" }}>{editor.errors.join("; ")}</span>}
-      <form onSubmit={sendAsk} style={{ display: "flex", gap: 6 }}><input value={ask} placeholder="Change this page…" onChange={e => setAsk(e.target.value)} style={{ width: 220 }} /><button type="submit">Ask</button></form>
-      <form onSubmit={sendQuestion} style={{ display: "flex", gap: 6 }}><input value={question} placeholder="Ask…" onChange={e => setQuestion(e.target.value)} style={{ width: 220 }} /><button type="submit">Ask</button></form>
-      {agent && <span style={{ color: agent.error ? "var(--pt-color-danger)" : undefined }}>{agent.text}</span>}
-      {state.errors.length > 0 && <span style={{ color: "var(--pt-color-danger)" }}>{state.errors.length} problem(s), see console</span>}
-    </header>
-    {(answer || answerStatus) && <div style={{ display: "flex", gap: 12, alignItems: "center", padding: "8px 16px", borderBottom: "1px solid var(--pt-color-border)", fontSize: 13 }}>
-      {answer && <><strong>{answer.title}</strong><span>{answer.why}</span><button onClick={keep}>Keep as page</button><button onClick={pin}>Pin to home</button><button onClick={() => { setAnswer(null); setAnswerStatus(null); }}>Back</button></>}
-      {answerStatus && <span style={{ color: answerStatus.error ? "var(--pt-color-danger)" : undefined }}>{answerStatus.text}</span>}
-    </div>}
-    <main style={{ padding: 16, maxWidth: 1100, margin: "0 auto" }}>{answer
-      ? <Page resolved={{ ...state, spec: answer.resolved.spec, errors: answer.resolved.errors }} registry={registry} />
-      : <EditorContext.Provider value={{ editing: editor.editing, propose: editor.propose }}><Page resolved={state} registry={registry} /></EditorContext.Provider>}</main>
-  </>;
-}
-createRoot(document.getElementById("root")).render(<App />);`;
+  // the Studio entry imports the project's components through a virtual module built from registry.yaml,
+  // regenerated on every rebuild
+  const registryPlugin = {
+    name: "pagetailor-registry",
+    setup(build) {
+      build.onResolve({ filter: /^pagetailor:registry$/ }, () => ({ path: "registry", namespace: "pagetailor" }));
+      build.onLoad({ filter: /.*/, namespace: "pagetailor" }, async () => {
+        const reg = await loadYaml(join(root, "components", "registry.yaml"));
+        const imports = [], map = [];
+        let i = 0;
+        for (const [name, def] of Object.entries(reg ?? {})) for (const [ver, v] of Object.entries(def.versions ?? {})) {
+          if (!v.impl) continue; const id = `C${i++}`;
+          imports.push(`import ${id} from ${JSON.stringify(v.impl)};`);
+          map.push(`${JSON.stringify(`${name}@${ver}`)}: ${id}`);
+        }
+        return { contents: `${imports.join("\n")}\nexport const registry = { ${map.join(", ")} };\n`, resolveDir: join(root, "components"), loader: "jsx" };
+      });
+    },
   };
 
   const ctx = await esbuild.context({
-    stdin: { contents: await entry(), resolveDir: join(root, "components"), loader: "jsx", sourcefile: "pagetailor-entry.jsx" },
+    entryPoints: [join(here, "studio", "entry.jsx")], plugins: [registryPlugin],
     bundle: true, write: false, format: "esm", jsx: "automatic", alias, nodePaths, outfile: "bundle.js", sourcemap: "inline", logLevel: "silent",
     define: { "process.env.NODE_ENV": '"development"' },
   });
@@ -165,21 +101,36 @@ createRoot(document.getElementById("root")).render(<App />);`;
         return json(res, 200, await buildAgentPrompt(root, { page: q.page || "home", user: q.user || undefined, role: q.role || undefined, request: q.request ?? "" }));
       }
       if (url.pathname === "/api/agent" && req.method === "POST") {
-        if (!process.env.ANTHROPIC_API_KEY) return json(res, 503, { error: "set ANTHROPIC_API_KEY to use the agent" });
+        const complete = completeFromEnv();
+        if (!complete) return json(res, 503, { error: LLM_HELP });
         const b = await body(req);
-        const complete = anthropicComplete({ apiKey: process.env.ANTHROPIC_API_KEY, ...(process.env.PAGETAILOR_MODEL ? { model: process.env.PAGETAILOR_MODEL } : {}) });
         const r = await runAgent(root, { page: b.page, user: b.user, role: b.role || undefined, request: b.request, complete });
         return json(res, r.ok ? 200 : 400, r);
       }
       if (url.pathname === "/api/ask" && req.method === "POST") {
-        if (!process.env.ANTHROPIC_API_KEY) return json(res, 503, { error: "set ANTHROPIC_API_KEY to use the agent" });
+        const complete = completeFromEnv();
+        if (!complete) return json(res, 503, { error: LLM_HELP });
         const b = await body(req);
-        const complete = anthropicComplete({ apiKey: process.env.ANTHROPIC_API_KEY, ...(process.env.PAGETAILOR_MODEL ? { model: process.env.PAGETAILOR_MODEL } : {}) });
         const r = await runAsk(root, { user: b.user || undefined, role: b.role || undefined, request: b.request, complete });
         return json(res, r.ok ? 200 : 400, r);
       }
       const answer = { "/api/ask/keep": keepAnswer, "/api/ask/pin": pinAnswer }[url.pathname];
       if (answer && req.method === "POST") { const b = await body(req); const r = await answer(root, { ...b, user: b.user || undefined, role: b.role || undefined }); return json(res, r.ok ? 200 : 400, r); }
+      if (url.pathname === "/api/project" && req.method === "GET") return json(res, 200, await readProject(root));
+      if (url.pathname.startsWith("/api/files/")) {
+        let name = decodeURIComponent(url.pathname.slice(11)), action = null;
+        const m = /^(.+)\/(history|undo)$/.exec(name);
+        if (m && isProjectFile(m[1])) { name = m[1]; action = m[2]; }
+        if (!isProjectFile(name)) return json(res, 400, { ok: false, errors: [`not a project file: ${name}`] });
+        if (action === "history" && req.method === "GET") return json(res, 200, await listFileHistory(root, name));
+        if (action === "undo" && req.method === "POST") { const r = await undoFile(root, name, { author: "studio" }); return json(res, r.ok ? 200 : 400, r); }
+        if (!action && req.method === "GET") return json(res, 200, { name, value: await readProjectFile(root, name) });
+        if (!action && req.method === "PUT") { const b = await body(req); const r = await writeProjectFile(root, name, b.value, { author: b.author ?? "studio", why: b.why ?? "edited in studio" }); return json(res, r.ok ? 200 : 400, r); }
+        if (!action && req.method === "DELETE") { const r = await deleteProjectFile(root, name, { author: "studio" }); return json(res, r.ok ? 200 : 400, r); }
+        return json(res, 405, { ok: false, errors: ["method not allowed"] });
+      }
+      if (url.pathname === "/api/scaffold/source" && req.method === "POST") { const b = await body(req); return json(res, 200, await scaffoldSource(root, b.name)); }
+      if (url.pathname === "/api/scaffold/component" && req.method === "POST") { const b = await body(req); return json(res, 200, await scaffoldComponent(root, b.name, { props: b.props, container: b.container })); }
       if (url.pathname === "/api/pending") return json(res, 200, await listPending(root));
       const flow = { "/api/propose": propose, "/api/approve": approve, "/api/reject": reject }[url.pathname];
       if (flow && req.method === "POST") { const r = await flow(root, await body(req)); return json(res, r.ok ? 200 : 400, r); }
@@ -192,7 +143,7 @@ createRoot(document.getElementById("root")).render(<App />);`;
     console.error(`pagetailor: port ${port} is already in use (try --port ${port + 1})`);
     process.exit(1);
   });
-  await new Promise(r => server.listen(port, r));
-  console.log(`pagetailor dev  http://localhost:${port}\n  pages from ${root}\n  ?page=home&user=giulia&role=marketing`);
+  await new Promise(r => server.listen(port, host, r));
+  console.log(`pagetailor dev  http://${host === "0.0.0.0" || host === "::" ? "localhost" : host}:${port}\n  pages from ${root}\n  ?page=home&user=giulia&role=marketing`);
   return server;
 }

package/src/files.js

@@ -0,0 +1,157 @@
+import { mkdir, readdir, readFile, writeFile, rm } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { parse } from "yaml";
+import { toYaml, writeYaml, appendVersion } from "./yaml-write.js";
+export { toYaml };
+import { loadProject, listPages, listOverrides, exists, forgetYaml } from "./loader.js";
+import { validateTree, validateManifest } from "./validator.js";
+import { clearResolveCache } from "./resolver.js";
+import { applyOverride } from "./overrides.js";
+
+// The YAML files of a project, read and written as plain objects; every write is versioned
+// under .history/files/<name with / as __>/NNNN.json with the previous and the new content.
+const FIXED = { manifest: "manifest.yaml", tokens: "tokens.yaml", "data-catalog": "data-catalog.yaml", "components/registry": "components/registry.yaml" };
+const SLUG = /^[a-z0-9-]+$/;
+const msg = e => typeof e === "string" ? e : `${e.path}: ${e.message}`;
+
+export function isProjectFile(name) {
+  if (typeof name !== "string") return false;
+  if (FIXED[name]) return true;
+  const [dir, slug, extra] = name.split("/");
+  return (dir === "pages" || dir === "overrides") && extra === undefined && SLUG.test(slug ?? "");
+}
+const pathOf = (root, name) => {
+  if (!isProjectFile(name)) throw new Error(`not a project file: ${name}`);
+  return join(root, FIXED[name] ?? `${name}.yaml`);
+};
+const historyDir = (root, name) => join(root, ".history", "files", name.replace("/", "__"));
+
+export async function readProjectFile(root, name) {
+  const p = pathOf(root, name);
+  if (!(await exists(p))) return null;
+  return parse(await readFile(p, "utf8")) ?? null;
+}
+
+async function validateFile(root, name, value) {
+  if (name === "tokens") return [];
+  if (!value || typeof value !== "object") return [`${name}: content must be an object`];
+  const project = await loadProject(root);
+  const pages = await listPages(root);
+  if (name === "manifest") return validateManifest(value, pages).map(msg);
+  if (name.startsWith("pages/")) {
+    if (!value.layout) return [`${name}: layout is required`];
+    const errors = validateTree(value.layout, project).map(msg);
+    // the overrides extending this page must still apply: a renamed child would break them silently
+    for (const ov of await listOverrides(root)) {
+      const o = await readProjectFile(root, `overrides/${ov}`);
+      if (!o || (o.extends && o.extends !== name.slice(6))) continue;
+      const r = applyOverride(value.layout, { name: ov, ...o });
+      for (const e of [...r.errors, ...validateTree(r.tree, project, ov.startsWith("role-") ? { role: ov.slice(5) } : {})]) errors.push(`overrides/${ov}: ${msg(e)}`);
+    }
+    return errors;
+  }
+  if (name.startsWith("overrides/")) {
+    // same check as the proposals gate; a role override is validated for its role, a user override with no role
+    const ov = name.slice(10);
+    if (!value.extends) return ["override.extends is required"];
+    const page = await readProjectFile(root, `pages/${value.extends}`);
+    if (!page) return [`page "${value.extends}" not found`];
+    const r = applyOverride(page.layout, { name: ov, ...value });
+    return [...r.errors, ...validateTree(r.tree, project, ov.startsWith("role-") ? { role: ov.slice(5) } : {})].map(msg);
+  }
+  // registry or catalog: every page must still validate against the new version
+  const next = { ...project, ...(name === "data-catalog" ? { catalog: value } : { registry: value }) };
+  const errors = [];
+  for (const page of pages) {
+    const doc = await readProjectFile(root, `pages/${page}`);
+    for (const e of validateTree(doc?.layout, next)) errors.push(`pages/${page} ${msg(e)}`);
+  }
+  return errors;
+}
+
+async function record(root, name, before, after, { author = "studio", why = "" } = {}) {
+  return appendVersion(historyDir(root, name), version => ({ version, at: new Date().toISOString(), author, why, before, after }));
+}
+
+async function put(root, name, value) {
+  const p = pathOf(root, name);
+  if (value === null) await rm(p, { force: true });
+  else { await mkdir(dirname(p), { recursive: true }); await writeYaml(p, value); }
+  forgetYaml(p); clearResolveCache();
+}
+
+export async function writeProjectFile(root, name, value, { author, why, skipValidation = false } = {}) {
+  if (!isProjectFile(name)) return { ok: false, errors: [`not a project file: ${name}`] };
+  const errors = skipValidation ? [] : await validateFile(root, name, value);
+  if (errors.length) return { ok: false, errors };
+  const before = await readProjectFile(root, name);
+  await put(root, name, value);
+  return { ok: true, entry: await record(root, name, before, value, { author, why }) };
+}
+
+export async function deleteProjectFile(root, name, { author, why = "deleted" } = {}) {
+  if (!isProjectFile(name) || !/^(pages|overrides)\//.test(name)) return { ok: false, errors: [`${name} cannot be deleted`] };
+  const before = await readProjectFile(root, name);
+  if (before === null) return { ok: false, errors: [`${name} does not exist`] };
+  if (name.startsWith("pages/") && (await loadProject(root)).manifest.home === name.slice(6))
+    return { ok: false, errors: [`${name.slice(6)} is the home page`] };
+  await put(root, name, null);
+  return { ok: true, entry: await record(root, name, before, null, { author, why }) };
+}
+
+export async function listFileHistory(root, name) {
+  if (!isProjectFile(name)) return [];
+  const dir = historyDir(root, name);
+  let files = []; try { files = (await readdir(dir)).filter(f => f.endsWith(".json")); } catch { return []; }
+  const all = await Promise.all(files.map(async f => JSON.parse(await readFile(join(dir, f), "utf8"))));
+  return all.sort((a, b) => b.version - a.version);
+}
+
+// Restores the content before the latest version; the restore itself is a new version.
+export async function undoFile(root, name, { author } = {}) {
+  const [last] = await listFileHistory(root, name);
+  if (!last) return { ok: false, errors: [`${name} has no history`] };
+  const current = await readProjectFile(root, name);
+  await put(root, name, last.before);
+  return { ok: true, value: last.before, entry: await record(root, name, current, last.before, { author, why: "undo" }) };
+}
+
+// Adds a stub implementation to data/sources.mjs, before the closing `};` of the default export.
+export async function scaffoldSource(root, name) {
+  const p = join(root, "data", "sources.mjs");
+  let src = (await exists(p)) ? await readFile(p, "utf8") : "export default {\n};\n";
+  if (src.includes(JSON.stringify(name))) return { created: false, path: p };
+  const at = src.lastIndexOf("};");
+  if (at < 0) throw new Error("data/sources.mjs: cannot find the end of the default export");
+  const stub = `  ${JSON.stringify(name)}: async (params, { user, role }) => { /* TODO: query */ return null; },\n`;
+  src = src.slice(0, at) + stub + src.slice(at);
+  await mkdir(dirname(p), { recursive: true }); await writeFile(p, src);
+  clearResolveCache();
+  return { created: true, path: p };
+}
+
+export const pascalName = name => String(name).split(/[^a-zA-Z0-9]+/).filter(Boolean).map(s => s[0].toUpperCase() + s.slice(1)).join("");
+
+// Creates components/<PascalName>.jsx reading the declared props; never overwrites.
+export async function scaffoldComponent(root, name, { props = {}, container = false } = {}) {
+  const file = `${pascalName(name)}.jsx`, p = join(root, "components", file);
+  if (await exists(p)) return { created: false, path: p, impl: `./${file}` };
+  const keys = Object.keys(props ?? {}).filter(k => /^[A-Za-z_$][\w$]*$/.test(k));
+  const read = keys.length ? `  const { ${keys.join(", ")} } = props;\n` : "";
+  const show = keys.map(k => `      <div><strong>${k}</strong>: {String(${k} ?? "")}</div>\n`).join("");
+  const src = `// ${name}: generated by pagetailor studio, edit freely.
+export default function ${pascalName(name)}({ props, children }) {
+${read}  return (
+    <div style={{ padding: "var(--pt-spacing-md)", border: "1px solid var(--pt-color-border)", borderRadius: "var(--pt-radius)" }}>
+${show}${container ? "      {children}\n" : "      {props.data !== undefined && <pre style={{ margin: 0, fontSize: 12 }}>{JSON.stringify(props.data, null, 2)}</pre>}\n"}    </div>
+  );
+}
+`;
+  await mkdir(dirname(p), { recursive: true }); await writeFile(p, src);
+  return { created: true, path: p, impl: `./${file}` };
+}
+
+export async function readProject(root) {
+  const [project, pages, overrides] = await Promise.all([loadProject(root), listPages(root), listOverrides(root)]);
+  return { manifest: project.manifest, tokens: project.tokens, catalog: project.catalog, registry: project.registry, pages, overrides };
+}

package/src/history.js

@@ -1,18 +1,14 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { stringify } from "yaml";
+import { writeYaml, appendVersion, pad } from "./yaml-write.js";
 
 // Every write to an override is a new numbered version under .history/<name>/NNNN.json.
 // The current override file is rewritten from the version being committed.
 const dirOf = (root, name) => join(root, ".history", name);
-const pad = n => String(n).padStart(4, "0");
 
 export async function commitOverride(root, name, override, { author = "system", status = "applied" } = {}) {
-  const dir = dirOf(root, name); await mkdir(dir, { recursive: true });
-  const n = (await readdir(dir)).length + 1;
-  const entry = { version: n, at: new Date().toISOString(), author, status, override };
-  await writeFile(join(dir, `${pad(n)}.json`), JSON.stringify(entry, null, 2));
-  if (status === "applied") await writeFile(join(root, "overrides", `${name}.yaml`), stringify(override));
+  const entry = await appendVersion(dirOf(root, name), version => ({ version, at: new Date().toISOString(), author, status, override }));
+  if (status === "applied") await writeYaml(join(root, "overrides", `${name}.yaml`), override);
   return entry;
 }
 

package/src/index.js

@@ -15,4 +15,5 @@ export async function dev(...args) {
 export { writeRegistryFile } from "./registry-file.js";
 export { tokensToCss } from "./tokens.js";
 export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent, buildAskPrompt, runAsk, keepAnswer, pinAnswer } from "./agent.js";
-export { anthropicComplete } from "./llm.js";
+export { anthropicComplete, openaiComplete, googleComplete, createComplete, completeFromEnv, PROVIDERS } from "./llm.js";
+export { readProjectFile, writeProjectFile, deleteProjectFile, listFileHistory, undoFile, scaffoldSource, scaffoldComponent, readProject } from "./files.js";