@aeratic/pagetailor 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @aeratic/pagetailor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+Status: 0.0.1, name reservation. The engine (built on json-render) lands in 0.1.
+
+```
+npm init -y
+npx @aeratic/pagetailor init
+npx @aeratic/pagetailor validate
+```

package/bin/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { init } from "../src/init.js";
+import { validate } from "../src/validate.js";
+
+const [cmd, ...args] = process.argv.slice(2);
+const help = `pagetailor <command>
+
+  init        create the pagetailor/ folder with manifest, tokens, data catalog, a sample page and base components
+  validate    check every page and override against the catalog
+`;
+
+try {
+  if (cmd === "init") await init(process.cwd(), args);
+  else if (cmd === "validate") process.exitCode = (await validate(process.cwd())) ? 0 : 1;
+  else { console.log(help); if (cmd && cmd !== "help") process.exitCode = 1; }
+} catch (e) { console.error("pagetailor:", e.message); process.exitCode = 1; }

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@aeratic/pagetailor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Pages as data: declarative, per-user tailored UI that an AI agent can safely compose.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pagetailor": "bin/cli.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "server-driven-ui",
+    "generative-ui",
+    "declarative-ui",
+    "json-render",
+    "yaml",
+    "personalization",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aeratic/pagetailor.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { init } from "./init.js";
+export { validate } from "./validate.js";

package/src/init.js

@@ -0,0 +1,22 @@
+import { cp, mkdir, access } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export async function init(cwd, args = []) {
+  const target = join(cwd, "pagetailor");
+  const force = args.includes("--force");
+  try { await access(target); if (!force) throw new Error("pagetailor/ already exists (use --force to overwrite)"); } catch (e) { if (e.code !== "ENOENT") throw e; }
+  await mkdir(target, { recursive: true });
+  await cp(join(here, "..", "templates"), target, { recursive: true, force });
+  console.log(`created ${target}/
+  manifest.yaml        app shape: pages, home, navigation, roles
+  tokens.yaml          design tokens
+  data-catalog.yaml    typed data sources with roles
+  pages/home.yaml      a sample page
+  overrides/           per-user and per-role patches
+  components/          base components, yours to edit
+
+next: npx pagetailor validate`);
+}

package/src/validate.js

@@ -0,0 +1,43 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+const load = async (p) => parse(await readFile(p, "utf8"));
+
+export async function validate(cwd) {
+  const root = join(cwd, "pagetailor");
+  const manifest = await load(join(root, "manifest.yaml"));
+  const data = await load(join(root, "data-catalog.yaml"));
+  const registry = await load(join(root, "components", "registry.yaml"));
+  const errors = [];
+
+  const walk = (node, page, path = "root") => {
+    if (!node || typeof node !== "object") return;
+    if (node.ref) {
+      const [name, version] = String(node.ref).split("@");
+      const comp = registry[name];
+      if (!comp) errors.push(`${page}: ${path}: unknown component "${name}"`);
+      else if (version && !comp.versions?.[version]) errors.push(`${page}: ${path}: "${name}" has no version ${version}`);
+      if (node.data?.source) {
+        const src = data[node.data.source];
+        if (!src) errors.push(`${page}: ${path}: unknown data source "${node.data.source}"`);
+        else if (comp?.accepts && src.returns && !compatible(comp.accepts, src.returns))
+          errors.push(`${page}: ${path}: "${name}" accepts ${comp.accepts} but "${node.data.source}" returns ${src.returns}`);
+      }
+    }
+    (node.children ?? []).forEach((c, i) => walk(c, page, `${path}/${i}`));
+  };
+
+  for (const file of await readdir(join(root, "pages"))) {
+    if (!file.endsWith(".yaml")) continue;
+    const page = await load(join(root, "pages", file));
+    if (!manifest.pages?.includes(page.page)) errors.push(`${file}: page "${page.page}" is not listed in manifest.yaml`);
+    walk(page.layout, file);
+  }
+
+  if (errors.length) { console.error(errors.join("\n")); console.error(`\n${errors.length} problem(s)`); return false; }
+  console.log("all pages valid"); return true;
+}
+
+// v0: exact match or "any"; a real type lattice comes later.
+const compatible = (accepts, returns) => accepts === "any" || accepts === returns;

package/templates/components/LineChart.jsx

@@ -0,0 +1,3 @@
+export default function LineChart({ props, data, children }) {
+  return <div data-pagetailor="LineChart">{props?.title}{children}</div>;
+}

package/templates/components/Stack.jsx

@@ -0,0 +1,3 @@
+export default function Stack({ props, data, children }) {
+  return <div data-pagetailor="Stack">{props?.title}{children}</div>;
+}

package/templates/components/Table.jsx

@@ -0,0 +1,3 @@
+export default function Table({ props, data, children }) {
+  return <div data-pagetailor="Table">{props?.title}{children}</div>;
+}

package/templates/components/Text.jsx

@@ -0,0 +1,3 @@
+export default function Text({ props, data, children }) {
+  return <div data-pagetailor="Text">{props?.title}{children}</div>;
+}

package/templates/components/TodoList.jsx

@@ -0,0 +1,3 @@
+export default function TodoList({ props, data, children }) {
+  return <div data-pagetailor="TodoList">{props?.title}{children}</div>;
+}

package/templates/components/registry.yaml

@@ -0,0 +1,14 @@
+# name -> versions, and the data type each component accepts
+layout/stack:
+  versions: { "1.0.0": { impl: ./Stack.jsx } }
+charts/line:
+  accepts: timeseries<money>
+  versions: { "1.0.0": { impl: ./LineChart.jsx } }
+tables/simple:
+  accepts: any
+  versions: { "1.0.0": { impl: ./Table.jsx } }
+todo/list:
+  accepts: list<task>
+  versions: { "1.0.0": { impl: ./TodoList.jsx } }
+text/block:
+  versions: { "1.0.0": { impl: ./Text.jsx } }

package/templates/data-catalog.yaml

@@ -0,0 +1,10 @@
+# Typed data sources. Components can only bind to sources whose `returns` they accept.
+analytics.revenue:
+  description: "Revenue over time"
+  params: { period: [7d, 30d, 90d] }
+  returns: timeseries<money>
+  roles: [admin]
+tasks.mine:
+  description: "Tasks assigned to the current user"
+  returns: list<task>
+  roles: [admin, user]

package/templates/manifest.yaml

@@ -0,0 +1,6 @@
+app: my-app
+home: home
+nav:
+  position: left
+pages: [home]
+roles: [admin, user]

package/templates/overrides/README.md

@@ -0,0 +1,6 @@
+One file per user or role, e.g. `user-giulia.yaml`:
+
+    extends: home
+    why: "Reports every Monday, wants revenue first"
+    patches:
+      - { op: move, ref: charts/line, to: 0 }

package/templates/pages/home.yaml

@@ -0,0 +1,10 @@
+page: home
+layout:
+  ref: layout/stack@1.0.0
+  children:
+    - ref: charts/line@1.0.0
+      props: { title: "Revenue, last 30 days" }
+      data: { source: analytics.revenue, params: { period: 30d } }
+    - ref: todo/list@1.0.0
+      props: { filter: mine }
+      data: { source: tasks.mine }

package/templates/tokens.yaml

@@ -0,0 +1,6 @@
+color:
+  primary: "#1D9E75"
+  surface: "#FFFFFF"
+  text: "#1A1A1A"
+spacing: { sm: 8, md: 16, lg: 24 }
+font: { base: "Inter", size: 15 }