nodality 1.3.15 → 1.3.17

package/bin/install-skill.mjs

@@ -55,19 +55,19 @@ function place(src, dest, content) {
 // Merge our server into an existing config without touching anything
 // else in it. A file that exists but does not parse is left alone and
 // reported — clobbering a hand-edited config is worse than skipping.
-function registerMcp(configPath) {
+export function registerMcp(configPath, entry = MCP_ENTRY) {
   let config = {};
   if (fs.existsSync(configPath)) {
     try {
       config = JSON.parse(fs.readFileSync(configPath, "utf8"));
     } catch {
       log(`SKIPPED ${configPath} — existing file is not valid JSON; add this by hand:`);
-      log(`  "mcpServers": { "nodality": ${JSON.stringify(MCP_ENTRY)} }`);
+      log(`  "mcpServers": { "nodality": ${JSON.stringify(entry)} }`);
       return;
     }
   }
   const existed = fs.existsSync(configPath);
-  config.mcpServers = { ...config.mcpServers, nodality: MCP_ENTRY };
+  config.mcpServers = { ...config.mcpServers, nodality: entry };
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
   log(`${existed ? "updated  " : "installed"} ${configPath} (mcpServers.nodality)`);

package/bin/mcp-server.mjs

@@ -221,6 +221,7 @@ const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
+          viewport: { description: "\"phone\" (default, 390×844) or \"desktop\" (1440×900), or {width, height}. Width-dependent elements render their view for it." },
         elements: ELEMENTS_SCHEMA,
         nodes: NODES_SCHEMA,
         output: {
@@ -286,6 +287,25 @@ const IMPL = {
     const schema = JSON.parse(await readFile(join(here, "..", "schema.json"), "utf8"));
     const types = schema.types || {};
     if (!type) return ok(schema);
+    if (types[type] && Array.isArray(types[type].params)) {
+      // The type's own parameters first: what its mapper reads by name, then
+      // described ones, then the rest — inherited through components. A
+      // composite lists 150+, and the dozen that matter were alphabetised
+      // among them.
+      const t = types[type];
+      const rank = (p) => (p.via === "mapper" ? 0 : p.description ? 1 : 2);
+      const params = [...t.params].sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name));
+      return ok({
+        type, ...t,
+        summary: {
+          total: params.length,
+          readByType: params.filter((p) => p.via === "mapper").length,
+          throughComponents: params.filter((p) => p.via !== "mapper").length,
+          described: params.filter((p) => p.description).length,
+        },
+        params,
+      });
+    }
     if (!types[type]) {
       // Same report shape as everything else, so an agent parses one thing.
       return ok({
@@ -312,7 +332,7 @@ const IMPL = {
     return ok(parseReport(String(html ?? ""), dom.window.document));
   },
 
-  preview: async ({ elements, nodes, output }) => {
+  preview: async ({ elements, nodes, output, viewport }) => {
     const N = nodes || [];
     const report = validateNodes(N, elements);
     if (!report.ok) return reportAsError(report);
@@ -338,10 +358,23 @@ const IMPL = {
       `<title>Nodality preview</title></head><body>` +
       `<div id="mount"></div></body></html>`, "utf8");
 
+    // The prerenderer emulates a phone by default, and anything chosen by
+    // width (a nav, a multiswitcher) renders as its phone view. "desktop"
+    // shows the other side.
+    const size = viewport === "desktop" ? { width: 1440, height: 900 }
+      : (viewport && typeof viewport === "object" ? viewport : { width: 390, height: 844 });
+    // Ids that rendered as an empty box, recorded while the DOM exists.
+    const empty = [];
+    const ids = [];
+    const collect = (list) => { for (const el of Array.isArray(list) ? list : []) {
+      if (el && typeof el === "object") { if (typeof el.id === "string") ids.push(el.id); collect(el.children); }
+    } };
+    collect(elements);
     await prerender({
       template,
       mount: "#mount",
       output: out,
+      viewport: size,
       // `build` is handed the jsdom window and is expected to render
       // into it. The Designer is imported HERE, inside the callback,
       // rather than at module scope: prerender installs the DOM globals
@@ -351,6 +384,13 @@ const IMPL = {
       build: async () => {
         const { Des } = await import("../lib/designer.js");
         new Des().nodes(N).add(elements).set({ mount: "#mount", code: false });
+        for (const id of ids) {
+          const node = document.querySelector(`[id="${id}"]`);
+          if (!node) { empty.push({ id, why: "not in the output" }); continue; }
+          const hasContent = node.children.length > 0 || (node.textContent || "").trim() !== ""
+            || /^(IMG|VIDEO|AUDIO|INPUT|SELECT|TEXTAREA|CANVAS|IFRAME|HR|BR|SVG)$/i.test(node.tagName);
+          if (!hasContent) empty.push({ id, why: "rendered empty" });
+        }
       },
     });
 
@@ -381,7 +421,12 @@ const IMPL = {
 
     return ok({
       path: out, bytes,
+      viewport: size,
       ...(surface ? { surface } : {}),
+      // An element that rendered nothing is said, not left to look like a
+      // finished page: a 181-byte preview of a nav was the only sign that
+      // its view is chosen at run time.
+      ...(empty.length ? { empty, emptyNote: "These ids rendered no content at this viewport. A runtime choice (multiswitcher, morph state), content that loads in the browser (commerce), or an element given nothing to show. Try viewport: \"desktop\", or open the file in a browser." } : {}),
       // Said plainly, because an agent cannot see the result and would
       // otherwise report a shader that never ran as working.
       note: "Prerendered DOM only. Raster effects and morph transitions " +

package/bin/nodality.mjs

@@ -34,6 +34,60 @@ import path from "node:path";
 import { prerenderSite } from "../layout/prerender-site.js";
 import { prerender } from "../layout/prerender.js";
 
+// ─── link-local: test an unreleased library in a real site ─────────
+//
+// Pre-release testing used to be a manual copy of dist/, lib/, layout/ and the
+// schema into the site's node_modules — easy to get wrong, and invisible once
+// done: nothing said the site was running something other than the release.
+// This does the copy, leaves a marker every other command warns about, and
+// undoes itself from the lockfile.
+async function linkLocal(rest) {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const { execSync } = await import("node:child_process");
+  const target = path.join(process.cwd(), "node_modules", "nodality");
+  const marker = path.join(target, ".linked-local.json");
+
+  if (rest.includes("--undo")) {
+    if (!fs.existsSync(marker)) { console.log("[nodality] link-local: nothing to undo — the installed copy is a release"); return; }
+    fs.rmSync(target, { recursive: true, force: true });
+    execSync("npm install --no-audit --no-fund", { stdio: "inherit" });
+    const v = JSON.parse(fs.readFileSync(path.join(target, "package.json"), "utf8")).version;
+    console.log(`[nodality] link-local: restored the released nodality ${v}. Rebuild your bundle (e.g. npm run build or nodality stage).`);
+    return;
+  }
+
+  const fromArg = rest.find((a) => a.startsWith("--from="));
+  if (!fromArg) {
+    console.error("[nodality] link-local: --from=<path to the nodality repository> is required (or --undo)");
+    process.exit(1);
+  }
+  const from = path.resolve(fromArg.slice("--from=".length));
+  const pkg = path.join(from, "package.json");
+  if (!fs.existsSync(pkg) || JSON.parse(fs.readFileSync(pkg, "utf8")).name !== "nodality") {
+    console.error(`[nodality] link-local: ${from} is not the nodality repository`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(target)) {
+    console.error("[nodality] link-local: install nodality in this project first (npm i nodality)");
+    process.exit(1);
+  }
+  if (!rest.includes("--no-build")) {
+    console.log(`[nodality] link-local: building ${from}…`);
+    execSync("npm run build", { cwd: from, stdio: "inherit" });
+  }
+  for (const part of ["dist", "lib", "layout", "bin", "schema.json"]) {
+    const src = path.join(from, part);
+    if (!fs.existsSync(src)) continue;
+    fs.rmSync(path.join(target, part), { recursive: true, force: true });
+    fs.cpSync(src, path.join(target, part), { recursive: true });
+  }
+  const version = JSON.parse(fs.readFileSync(pkg, "utf8")).version;
+  fs.writeFileSync(marker, JSON.stringify({ from, builtAt: new Date().toISOString(), baseVersion: version }, null, 2));
+  console.log(`[nodality] link-local: this project now runs the LOCAL build from ${from} (on top of ${version}).`);
+  console.log("[nodality] Rebuild your bundle (e.g. npm run build or nodality stage). Every nodality command will warn until: npx nodality link-local --undo");
+}
+
 // ─── Usage ──────────────────────────────────────────────────────
 
 function showUsage() {
@@ -55,6 +109,14 @@ function showUsage() {
                                               #   { "mcpServers": { "nodality": {
                                               #       "command": "npx",
                                               #       "args": ["nodality", "mcp"] } } }
+  nodality link-local --from=<repo> [--no-build]  # Build a local nodality checkout and run
+                                              # this project on it, for testing before a
+                                              # release; every command warns while linked.
+  nodality link-local --undo                  # Back to the released version (lockfile).
+  nodality mcp --register [--root=<dir>]      # Write that entry into <dir>/.mcp.json —
+                                              # the folder agent sessions start in
+                                              # (default: here). From a parent folder
+                                              # it runs this project's installed copy.
   nodality skill [flags]                      # Install the /nodality skill into agent
                                               # IDEs. No flags: interactive (or full
                                               # default install when not a TTY).
@@ -869,6 +931,20 @@ async function main() {
   }
 
   const [command, ...rest] = process.argv.slice(2);
+
+  // A site running a locally built library says so on every command, so a
+  // pre-release copy is never mistaken for the release (see link-local).
+  {
+    const fs = await import("node:fs");
+    const path = await import("node:path");
+    const marker = path.join(process.cwd(), "node_modules", "nodality", ".linked-local.json");
+    if (command !== "link-local" && fs.existsSync(marker)) {
+      try {
+        const m = JSON.parse(fs.readFileSync(marker, "utf8"));
+        console.warn(`[nodality] ⚠ using a LOCAL build of nodality from ${m.from} (built ${m.builtAt}). Undo: npx nodality link-local --undo`);
+      } catch {}
+    }
+  }
   if (!command || command === "help" || command === "--help" || command === "-h") {
     showUsage();
   } else if (command === "prerender") {
@@ -887,6 +963,33 @@ async function main() {
   } else if (command === "skill") {
     const { runSkillInstall } = await import("./install-skill.mjs");
     await runSkillInstall(rest);
+  } else if (command === "link-local") {
+    await linkLocal(rest);
+  } else if (command === "mcp" && rest.includes("--register")) {
+    // Register the server where agent sessions START, which is not always
+    // the project. A session opened one folder up never saw the project's
+    // own .mcp.json, and the agent drove the server by hand instead. From a
+    // parent root the entry runs npx with --prefix, so it is still the
+    // project's installed nodality that answers, not whatever npm resolves.
+    const path = await import("node:path");
+    const { registerMcp } = await import("./install-skill.mjs");
+    const rootArg = rest.find((a) => a.startsWith("--root="));
+    // Real paths on both sides: through a symlink (macOS /var is
+    // /private/var) the two spellings of one folder looked unrelated and a
+    // correct root was refused.
+    const fsMod = await import("node:fs");
+    const real = (p) => { try { return fsMod.realpathSync(p); } catch { return path.resolve(p); } };
+    const root = real(path.resolve(rootArg ? rootArg.slice("--root=".length) : process.cwd()));
+    const project = real(process.cwd());
+    const rel = path.relative(root, project);
+    if (rel.startsWith("..")) {
+      console.error(`[nodality] mcp --register: --root must be this project or a folder above it (${root})`);
+      process.exit(1);
+    }
+    const entry = rel === "" ? { command: "npx", args: ["nodality", "mcp"] }
+      : { command: "npx", args: ["--prefix", rel, "nodality", "mcp"] };
+    registerMcp(path.join(root, ".mcp.json"), entry);
+    console.log(`[nodality] start sessions in ${root} — the nodality tools are registered there`);
   } else if (command === "mcp") {
     // Lazily imported so that prerender/compile/stage pay nothing for a
     // subcommand they never touch, and so a broken morph core cannot