@aeratic/pagetailor 0.3.0 → 0.4.0

package/README.md

@@ -127,10 +127,21 @@ A user asks in natural language ("put the KPI at the top"); the agent turns it i
 
 `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).
 
-In `pagetailor dev`, set `ANTHROPIC_API_KEY` (and optionally `PAGETAILOR_MODEL`) and use the "Ask the agent…" 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 `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.
+
+## Pages as answers
+
+A user asks a question ("how did sales go this week?") and the agent composes a brand-new page from the catalog instead of changing an existing one.
+
+1. `runAsk(root, { user, role, request, complete })` starts from an empty `layout/stack`, asks the model for `{ "title", "why", "patches" }` using only `insert` ops (cards, grids, widgets), applies them in memory and resolves the tree with `resolve(root, "answer", { user, role, tree })`. Gate or resolve errors are sent back once, like `runAgent`.
+2. The result (`{ title, why, tree, resolved }`) is rendered as is. Nothing is written to disk until the user decides.
+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 }`.
 
 ## Status
 
-0.3: engine, CLI (`init`, `validate`, `registry`, `dev`), history with rollback, proposals with owner approval, reorder editor, agent with a pluggable model adapter.
+0.4: engine, CLI (`init`, `validate`, `registry`, `dev`), history with rollback, proposals with owner approval, reorder editor, agent with a pluggable model adapter, pages as answers.
 
 License: MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.3.0",
+  "version": "0.4.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,8 +1,11 @@
 import { join } from "node:path";
-import { loadProject, loadPage, loadOverrides, loadYaml, exists } from "./loader.js";
+import { writeFile } from "node:fs/promises";
+import { stringify } from "yaml";
+import { loadProject, loadPage, loadOverrides, loadYaml, exists, listPages } from "./loader.js";
 import { applyOverride, mergePatch } from "./overrides.js";
-import { splitRef } from "./validator.js";
+import { splitRef, validateTree } from "./validator.js";
 import { propose } from "./proposals.js";
+import { resolve } from "./resolver.js";
 
 // The agent never writes files: it turns a request into override patches and hands them to propose().
 const OPS = [
@@ -56,22 +59,27 @@ export async function describePage(root, page, { user, role } = {}) {
   return `PAGE ${page} (user ${user ?? "none"}, role ${role ?? "none"})\n${lines.join("\n")}`;
 }
 
+const RULES = `- Use only the components, data sources and ops listed below; refs include the version (name@version).
+- Respect types: a component bound to data must accept the type the source returns. Use only params listed for a source.
+- Respect the role: never use a data source that is not listed (the role cannot read it).`;
+const GRID_RULE = "- A grid with areas must place every child exactly once";
+const reply = shape => `Answer ONLY with a JSON object, no prose:
+  ${shape}
+or, when the request cannot be satisfied with this catalog or this user's role:
+  { "refuse": string }`;
+const LANG = (...f) => `- Write ${f.map(x => `"${x}"`).join(", ")} (and "refuse") in the user's language.`;
+
 export async function buildAgentPrompt(root, { page, user, role, request }) {
   const project = await loadProject(root);
   const system = `You modify a declarative UI page for one user by writing override patches.
-Answer ONLY with a JSON object, no prose:
-  { "why": string, "patches": [ ...override ops... ] }
-or, when the request cannot be satisfied with this catalog or this user's role:
-  { "refuse": string }
+${reply('{ "why": string, "patches": [ ...override ops... ] }')}
 
 RULES
-- Use only the components, data sources and ops listed below; refs include the version (name@version).
-- Respect types: a component bound to data must accept the type the source returns. Use only params listed for a source.
-- Respect the role: never use a data source that is not listed (the role cannot read it).
+${RULES}
 - Targets are existing child names or component names from the current page.
-- A grid with areas must place every child exactly once: when you insert, remove or replace grid children, update areas too.
+${GRID_RULE}: when you insert, remove or replace grid children, update areas too.
 - Keep patches minimal: change only what the request asks for. Patches are appended to the user's existing ones.
-- Write "why" (and "refuse") in the user's language.
+${LANG("why")}
 
 ${describeCatalog(project, { role })}
 
@@ -79,6 +87,28 @@ CURRENT ${await describePage(root, page, { user, role })}`;
   return { system, user: request };
 }
 
+export const ANSWER_SKELETON = { ref: "layout/stack@1.0.0", children: [] };
+
+export async function buildAskPrompt(root, { user, role, request }) {
+  const project = await loadProject(root);
+  const system = `You answer a user's question by composing a brand-new UI page from a catalog of components and data sources.
+${reply('{ "title": string, "why": string, "patches": [ ...insert ops only... ] }')}
+
+RULES
+${RULES}
+- Use ONLY "insert" ops, onto the page's root layout/stack (target "layout/stack") or onto a layout/grid or layout/card you inserted.
+- Add a layout/card (with a title) or a layout/grid to group widgets as needed. To fill a grid, insert it with named children and areas in one node.
+${GRID_RULE}.
+- "title" names the page in a few words; "why" says briefly how the page answers the question.
+${LANG("title", "why")}
+
+${describeCatalog(project, { role })}
+
+CURRENT PAGE answer (empty, user ${user ?? "none"}, role ${role ?? "none"})
+layout/stack: layout/stack@1.0.0`;
+  return { system, user: request };
+}
+
 export function parseAgentReply(text) {
   const s = String(text ?? "");
   const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(s);
@@ -121,3 +151,70 @@ export async function runAgent(root, { page, user, role, request, complete }) {
     reply = undefined; errors = [];
   }
 }
+
+// Pages as answers: compose a page in memory; nothing is written until keepAnswer or pinAnswer.
+export async function runAsk(root, { user, role, request, complete }) {
+  const prompt = await buildAskPrompt(root, { user, role, request });
+  let message = prompt.user, reply, errors = [];
+  for (let attempts = 1; attempts <= 2; attempts++) {
+    const text = await complete({ system: prompt.system, user: message });
+    try { reply = parseAgentReply(text); } catch (e) { errors = [e.message]; }
+    if (reply?.refuse) return { ok: false, refuse: reply.refuse, reply, attempts };
+    if (reply && !errors.length) {
+      if (!Array.isArray(reply.patches)) errors = ["reply has no patches array"];
+      else if (reply.patches.some(p => p?.op !== "insert")) errors = ["only insert ops are allowed"];
+      else {
+        const r = applyOverride(ANSWER_SKELETON, { name: "answer", patches: reply.patches });
+        const resolved = await resolve(root, "answer", { user, role, tree: r.tree });
+        errors = [...r.errors, ...resolved.errors].map(e => `${e.path}: ${e.message}`);
+        if (!errors.length) return { ok: true, title: reply.title ?? "Answer", why: reply.why, tree: r.tree, resolved: { spec: resolved.spec, errors: resolved.errors }, attempts };
+      }
+    }
+    if (attempts === 2) return { ok: false, errors, reply, attempts };
+    message = `${prompt.user}\n\nThe previous page was rejected: ${errors.join("; ")}. Fix it.`;
+    reply = undefined; errors = [];
+  }
+}
+
+const slugify = s => String(s ?? "").normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "answer";
+
+export async function keepAnswer(root, { user, role, title, tree, why }) {
+  const project = await loadProject(root);
+  const errors = validateTree(tree, project, { role: role ?? null });
+  if (errors.length) return { ok: false, errors: errors.map(e => `${e.path}: ${e.message}`) };
+  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 }));
+  const mfile = join(root, "manifest.yaml");
+  const manifest = (await loadYaml(mfile)) ?? {};
+  await writeFile(mfile, stringify({ ...manifest, pages: [...(manifest.pages ?? []), slug] }));
+  return { ok: true, page: slug };
+}
+
+// The home's main container: the root, or the single grid it wraps.
+function mainContainer(tree) {
+  let node = tree;
+  while (Array.isArray(node.children) && node.children.length === 1 && node.children[0]?.children && !Array.isArray(node.children[0].children)) node = node.children[0];
+  return node;
+}
+
+export async function pinAnswer(root, { user, role, page, title, tree, why }) {
+  if (!user) return { ok: false, errors: ["user is required"] };
+  page ??= (await loadProject(root)).manifest.home;
+  const name = `user-${user}`;
+  const file = join(root, "overrides", `${name}.yaml`);
+  const existing = await exists(file) ? (await loadYaml(file)) ?? {} : {};
+  const base = existing.extends === page ? existing.patches ?? [] : [];
+  const target = mainContainer(await currentTree(root, page, { user, role }));
+  const card = { ref: "layout/card@1.0.0", props: { title: title ?? "Answer" }, children: structuredClone(tree.children ?? []) };
+  const insert = { op: "insert", target: splitRef(target.ref)[0], node: card };
+  if (target.children && !Array.isArray(target.children)) {
+    let n = 1; while (`answer-${n}` in target.children) n++;
+    insert.name = `answer-${n}`;
+    const areas = String(target.props?.areas ?? "").trimEnd();
+    const cols = areas ? areas.split("\n")[0].trim().split(/\s+/).length : 1;
+    insert.area = `${areas ? areas + "\n" : ""}${Array(cols).fill(insert.name).join(" ")}\n`;
+  }
+  return propose(root, { name, author: user, role, override: { extends: page, why: why ?? `pinned: ${title ?? "answer"}`, patches: mergePatch(base, insert) } });
+}

package/src/dev.js

@@ -9,7 +9,7 @@ import { loadProject, loadYaml, listPages } from "./loader.js";
 import { commitOverride, listHistory, rollback } from "./history.js";
 import { propose, listPending, approve, reject } from "./proposals.js";
 import { tokensToCss } from "./tokens.js";
-import { buildAgentPrompt, runAgent } from "./agent.js";
+import { buildAgentPrompt, runAgent, runAsk, keepAnswer, pinAnswer } from "./agent.js";
 import { anthropicComplete } from "./llm.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -62,6 +62,26 @@ function App() {
       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 ?? [];
@@ -75,11 +95,18 @@ function App() {
       {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="Ask the agent…" onChange={e => setAsk(e.target.value)} style={{ width: 220 }} /><button type="submit">Ask</button></form>
+      <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>
-    <main style={{ padding: 16, maxWidth: 1100, margin: "0 auto" }}><EditorContext.Provider value={{ editing: editor.editing, propose: editor.propose }}><Page resolved={state} registry={registry} /></EditorContext.Provider></main>
+    {(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 />);`;
@@ -144,6 +171,15 @@ createRoot(document.getElementById("root")).render(<App />);`;
         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 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/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); }

package/src/index.js

@@ -14,5 +14,5 @@ export async function dev(...args) {
 }
 export { writeRegistryFile } from "./registry-file.js";
 export { tokensToCss } from "./tokens.js";
-export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent } from "./agent.js";
+export { describeCatalog, describePage, buildAgentPrompt, parseAgentReply, runAgent, buildAskPrompt, runAsk, keepAnswer, pinAnswer } from "./agent.js";
 export { anthropicComplete } from "./llm.js";

package/src/resolver.js

@@ -14,7 +14,9 @@ const fingerprint = (root, page, user, role) => Promise.all([
 ].map(f => mtime(join(root, f)))).then(a => Math.max(...a));
 
 // YAML page + overrides + data  ->  json-render flat spec { root, elements, state }
-export async function resolve(root, page, { user, role, sources, fresh = false, maxAge = 0 } = {}) {
+// opts.tree: an in-memory layout (e.g. an agent answer), no page file, no overrides, no cache
+export async function resolve(root, page, { user, role, sources, tree, fresh = false, maxAge = 0 } = {}) {
+  if (tree) return build(root, page, { user, role, sources, tree });
   const key = `${root}|${page}|${user}|${role}`, fp = await fingerprint(root, page, user, role);
   const hit = cache.get(key);
   if (!fresh && hit && hit.fp === fp && (!maxAge || Date.now() - hit.at < maxAge)) return hit.result;
@@ -23,12 +25,12 @@ export async function resolve(root, page, { user, role, sources, fresh = false,
   return result;
 }
 
-async function build(root, page, { user, role, sources }) {
+async function build(root, page, { user, role, sources, tree: given }) {
   const project = await loadProject(root);
   const fetchers = sources ?? await loadSources(root);
-  let tree = (await loadPage(root, page)).layout;
+  let tree = given ?? (await loadPage(root, page)).layout;
   const errors = [];
-  for (const ov of await loadOverrides(root, page, user, role)) {
+  if (!given) for (const ov of await loadOverrides(root, page, user, role)) {
     const r = applyOverride(tree, ov); tree = r.tree; errors.push(...r.errors);
   }
   errors.push(...validateTree(tree, project, { role: role ?? null }));