nodality 1.2.9 → 1.2.11

package/bin/mcp-server.mjs

@@ -135,6 +135,54 @@ const TOOLS = [
       required: ["nodes"],
     },
   },
+  {
+    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 +228,44 @@ 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.
+  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/nodality.js

@@ -64,6 +64,13 @@ function showUsage() {
                                               #   --dir=<path>        copy SKILL.md anywhere
                                               #   --no-mcp            skip MCP registration
                                               # Re-run after upgrading to refresh in place.
+  nodality schema [type] [--check]            # Print the machine-readable element
+                                              # schema, derived from the source
+                                              # at run time. With a type, print
+                                              # just that type — the form an
+                                              # agent puts in its context.
+                                              #   --check  exit 1 if schema.json
+                                              #            is stale (used in CI)
   nodality help
 
 Compile flags:
@@ -872,6 +879,11 @@ async function main() {
     await runFanoutStandalone(rest);
   } else if (command === "stage") {
     await runStage(rest);
+  } else if (command === "schema") {
+    // Lazily imported like `mcp` and `skill`: a subcommand nobody invoked
+    // should cost nothing, and a broken generator must not take the CLI down.
+    const { runSchema } = await import("./schema-cli.mjs");
+    await runSchema(rest);
   } else if (command === "skill") {
     const { runSkillInstall } = await import("./install-skill.mjs");
     await runSkillInstall(rest);

package/bin/schema-cli.mjs

@@ -0,0 +1,72 @@
+// bin/schema-cli.mjs — `npx nodality schema [type] [--check]`
+//
+// Stage 2 of AGENTIC-FIRST-PLAN.md. The point of the subcommand is property 2
+// of "agentic-first": schema ON DEMAND rather than schema in context. A model
+// that can fetch one type's parameters pays for that type once, instead of
+// carrying every type's vocabulary in every request.
+//
+// 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("--"));
+
+  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");
+}

package/dist/animator.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/animator.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/audionew.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/audionew.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/base.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/base.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-desktop-bar.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-desktop-bar.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-mobile-bar.cjs.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/dist/beta-mobile-bar.esm.js.LICENSE.txt

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.2.8
+ * nodality v1.2.10
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */