nodality 1.2.10 → 1.3.0

package/bin/mcp-server.mjs

@@ -135,6 +135,79 @@ const TOOLS = [
       required: ["nodes"],
     },
   },
+  {
+    name: "check_page",
+    description:
+      "What the page actually DOES, once it has real layout. Everything else " +
+      "here checks the input: validate_nodes checks vocabulary, get_schema " +
+      "says what a type accepts, parse_html says what a page was made from. " +
+      "None of them can tell you the page you just produced scrolls " +
+      "sideways, clips its own text, or is unreadable \u2014 a spec can be " +
+      "perfect and the page still wrong. Give it `html` (or `path` to a file " +
+      "`preview` wrote) and it drives a real browser at a phone and a desktop " +
+      "width and reports horizontal overflow, elements past the viewport, " +
+      "clipped content, images with no description, tap targets under 24px, " +
+      "controls with no accessible name, skipped heading levels and text " +
+      "below the WCAG contrast minimum. Same report shape as validate_nodes; " +
+      "`path` in an error is a CSS selector into the rendered page. It " +
+      "reports facts, never taste \u2014 it will not tell you whether a " +
+      "design is good.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        html: { type: "string", description: "Rendered HTML: a document or a fragment." },
+        path: { type: "string", description: "Path to an HTML file, e.g. what `preview` returned." },
+      },
+    },
+  },
+  {
+    name: "get_schema",
+    description:
+      "One element type's parameters, on demand. This is the other half of " +
+      "list_ops: that returns the vocabulary of N, this returns the " +
+      "vocabulary of E. Call it for the type you are about to write rather " +
+      "than carrying every type's parameters in context \u2014 that is the " +
+      "difference between paying for a schema once and paying for it in " +
+      "every request. Each entry names the mapper, the components it builds " +
+      "and every parameter recovered from the source those components " +
+      "actually read, so it cannot describe a parameter the library does " +
+      "not have. Omit `type` for the whole schema. Composites carry content " +
+      "in a slot \u2014 `items` for cards, nav, sideNav, table and ulist; " +
+      "`children` for row, form and wrap \u2014 and declaring it in the " +
+      "other one renders the placeholders instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          description: "An element type, e.g. \"cards\". Omit for the whole schema.",
+        },
+      },
+    },
+  },
+  {
+    name: "parse_html",
+    description:
+      "Read a rendered page back into an E array, so a page can be EDITED " +
+      "rather than only generated: parse it, change the one thing, render " +
+      "again. Two tiers, and the report says which one you got. A page " +
+      "rendered with `{annotate: true}` carries its own descriptors and " +
+      "comes back exactly \u2014 every type, every option, nothing " +
+      "inferred. Without that, only what the tag settles is recovered: " +
+      "headings, paragraphs, links, images and lists. Thirteen composite " +
+      "types render as a bare <div> with nothing to tell them apart, so " +
+      "those are reported unrecovered rather than guessed \u2014 a wrong " +
+      "guess would silently become a different page. The recovered spec is " +
+      "validated before it is returned, because a descriptor read out of a " +
+      "document is untrusted input.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        html: { type: "string", description: "The rendered HTML to read back." },
+      },
+      required: ["html"],
+    },
+  },
   {
     name: "preview",
     description:
@@ -180,6 +253,64 @@ const IMPL = {
   validate_nodes: async ({ nodes, elements }) =>
     ok(validateNodes(nodes, elements)),
 
+  // Served from the shipped schema.json rather than regenerated: the
+  // generator is a build-time script and this server answers in-process. The
+  // drift test keeps the committed copy honest, so reading it is not a second
+  // source of truth, it is the same one at rest.
+  check_page: async ({ html, path: file } = {}) => {
+    const { checkPage } = await import("../lib/check-page.js");
+    let source = html;
+    if (!source && file) {
+      const { readFile } = await import("node:fs/promises");
+      source = await readFile(file, "utf8");
+    }
+    if (!source) {
+      return ok({
+        ok: false,
+        errors: [{
+          code: "MISSING_FIELD", path: "html", got: undefined,
+          suggestions: ["html", "path"],
+          valid: ["rendered HTML, or a path to a file containing it"],
+        }],
+      });
+    }
+    return ok(await checkPage(source));
+  },
+
+  get_schema: async ({ type } = {}) => {
+    const [{ readFile }, { fileURLToPath }, { dirname, join }] = await Promise.all([
+      import("node:fs/promises"), import("node:url"), import("node:path"),
+    ]);
+    const here = dirname(fileURLToPath(import.meta.url));
+    const schema = JSON.parse(await readFile(join(here, "..", "schema.json"), "utf8"));
+    const types = schema.types || {};
+    if (!type) return ok(schema);
+    if (!types[type]) {
+      // Same report shape as everything else, so an agent parses one thing.
+      return ok({
+        ok: false,
+        errors: [{
+          code: "UNKNOWN_ELEMENT_TYPE", path: "type", got: type,
+          suggestions: Object.keys(types)
+            .filter((t) => t.slice(0, 2) === String(type).slice(0, 2)).slice(0, 3),
+          valid: Object.keys(types),
+        }],
+      });
+    }
+    return ok({ type, ...types[type] });
+  },
+
+  parse_html: async ({ html }) => {
+    // Same arrangement as `preview`: a DOM is a build-time concern, so jsdom
+    // is not bundled and its absence arrives as MISSING_PEER_DEPENDENCY from
+    // the handler below rather than as a stack trace.
+    const [{ JSDOM }, { parseReport }] = await Promise.all([
+      import("jsdom"), import("../lib/parse-html.js"),
+    ]);
+    const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
+    return ok(parseReport(String(html ?? ""), dom.window.document));
+  },
+
   preview: async ({ elements, nodes, output }) => {
     const N = nodes || [];
     const report = validateNodes(N, elements);

package/bin/schema-cli.mjs

@@ -5,24 +5,68 @@
 // that can fetch one type's parameters pays for that type once, instead of
 // carrying every type's vocabulary in every request.
 //
-// The schema is regenerated from source on each call rather than read from
-// the committed schema.json, so what an agent is told can never be staler
-// than the library it is talking to. `--check` compares the two and is what
-// CI runs.
+// TWO SOURCES, in order, because the first one is not always there.
+//
+// In a checkout the generator runs and the schema is rebuilt from source, so
+// what an agent is told cannot be staler than the library it is talking to.
+// In an INSTALLED package it is read from the shipped schema.json instead.
+//
+// That second path is not belt-and-braces, it is a bug fix. `schema.json` and
+// `scripts/` were both outside package.json's `files`, so neither reached the
+// tarball, and `npx nodality schema` failed with MODULE_NOT_FOUND for every
+// consumer while working perfectly in the dev tree — property 2 shipped as
+// nothing at all. Both are packaged now, and `packaging/smoke.mjs` runs this
+// subcommand against the packed tarball so the surface cannot regress
+// invisibly again.
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 
 export async function runSchema(args) {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const gen = path.join(here, "..", "scripts", "generate-schema.mjs");
+  const committed = path.join(here, "..", "schema.json");
   const type = args.find((a) => !a.startsWith("--"));
-  const passthrough = args.includes("--check")
-    ? ["--check"]
-    : type ? ["--type", type] : ["--stdout"];
 
-  await new Promise((resolve) => {
-    const p = spawn(process.execPath, [gen, ...passthrough], { stdio: "inherit" });
-    p.on("exit", (code) => { process.exitCode = code ?? 0; resolve(); });
-  });
+  if (existsSync(gen)) {
+    const passthrough = args.includes("--check")
+      ? ["--check"]
+      : type ? ["--type", type] : ["--stdout"];
+    await new Promise((resolve) => {
+      const p = spawn(process.execPath, [gen, ...passthrough], { stdio: "inherit" });
+      p.on("exit", (code) => { process.exitCode = code ?? 0; resolve(); });
+    });
+    return;
+  }
+
+  if (!existsSync(committed)) {
+    console.error("[nodality] no schema available: neither scripts/generate-schema.mjs");
+    console.error("           nor schema.json is present in this installation.");
+    process.exitCode = 1;
+    return;
+  }
+
+  // `--check` asks whether the committed copy matches what the source would
+  // produce. Without the generator that question cannot be answered, and
+  // answering "yes" from the file being checked would be circular.
+  if (args.includes("--check")) {
+    console.error("[nodality] --check needs scripts/generate-schema.mjs, which is not");
+    console.error("           present in an installed package. Run it from a checkout.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const schema = JSON.parse(readFileSync(committed, "utf8"));
+  if (type) {
+    const entry = schema.types?.[type];
+    if (!entry) {
+      console.error(`unknown type "${type}"`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(JSON.stringify({ type, ...entry }, null, 2));
+    return;
+  }
+  process.stdout.write(JSON.stringify(schema, null, 2) + "\n");
 }