flet-box 1.1.2 → 1.1.3

package/bin/mcp.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * @file bin/mcp.js
+ * @description `flet-box mcp` — the read-only toolkit over the Model Context
+ * Protocol, stdio transport.
+ *
+ * An assistant that can run a shell already has every tool in this package. An
+ * assistant that cannot — a chat panel with no terminal, a hosted agent, an
+ * editor extension — has none of them, so it guesses about the framework. This
+ * server is the same catalogue with a different mouth: the nine read-only
+ * entries from `bin/utils/toolkit.js`, each answered by the same function the
+ * CLI calls, so the two can never disagree about what the code says.
+ *
+ * Read-only is not a promise in a comment; it is the shape of the code:
+ *
+ *   • `report` runs `buildReport`, which never writes (the HTML artifact is a
+ *     CLI flag, not an MCP argument).
+ *   • the gates run through `runGates`, not `verify` — `verify` appends a
+ *     metrics row, and a diagnosis must not change what it measures.
+ *   • `check-api`, `check-ui` and `unpack` are called without `--emit-api`,
+ *     without `--fix` and without `--all` (the one `unpack` form that writes).
+ *   • no executor edits, deletes, builds or publishes. `scripts/check-report.mjs`
+ *     hashes the tree around every tool call to prove it.
+ *
+ * The transport is newline-delimited JSON-RPC 2.0 (the MCP stdio framing). Logs
+ * go to stderr; stdout carries protocol messages only.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { createRequire } from "node:module";
+import { TOOLS, toolById } from "./utils/toolkit.js";
+import { buildReport, renderText } from "./commands/report.js";
+import { runGates, formatReport } from "./commands/verify.js";
+import { checkApi } from "./commands/checkApi.js";
+import { checkUi } from "./commands/checkUi.js";
+import { metrics } from "./commands/metrics.js";
+import { unpack } from "./commands/unpack.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+/** A terminal's colours must not leak into a protocol string. */
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+/**
+ * Run a CLI function with its output captured.
+ *
+ * @param {(argv: string[], io: object) => Promise<{exitCode?: number}>} fn
+ * @param {string[]} argv
+ * @returns {Promise<{text: string, exitCode: number}>}
+ */
+const capture = async (fn, argv) => {
+  const lines = [];
+  const result = (await fn(argv, { print: (line) => lines.push(String(line)) })) || {};
+  return {
+    text: lines.join("\n").replace(ANSI, "").trim(),
+    exitCode: Number(result.exitCode) || 0,
+  };
+};
+
+const rootArg = (root) => ["--root", root];
+
+/**
+ * Parse JSON that a command printed, so the protocol can carry it as data too.
+ *
+ * @param {string} text
+ * @returns {object|null}
+ */
+const asData = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The executor for every catalogue entry. Each one returns the text a person
+ * would read and, where the command has a JSON form, the same facts as data.
+ */
+const RUN = {
+  report: async ({ root, tests }) => {
+    const built = await buildReport({ root, tests: Boolean(tests) });
+    return { text: renderText(built).join("\n"), data: built };
+  },
+
+  widget_props: async ({ root, widget }) => {
+    const out = await capture(checkApi, ["--props", widget, ...rootArg(root)]);
+    const missing = /is not a FletBox widget/.test(out.text);
+    return { ...out, error: missing ? `no widget named "${widget}"` : null };
+  },
+
+  widget_contract: async ({ root, widget }) => {
+    const out = await capture(unpack, [widget, "--json", ...rootArg(root)]);
+    return { ...out, data: asData(out.text) };
+  },
+
+  list_widgets: async ({ root }) => capture(checkApi, ["--list", ...rootArg(root)]),
+
+  check: async ({ root, full }) => {
+    const out = await capture(checkApi, ["--json", ...(full ? ["--full"] : []), ...rootArg(root)]);
+    return { ...out, data: asData(out.text) };
+  },
+
+  design: async ({ root, tokens, strict }) => {
+    const out = await capture(checkUi, [
+      "--json",
+      ...(tokens ? ["--tokens"] : []),
+      ...(strict ? ["--strict"] : []),
+      ...rootArg(root),
+    ]);
+    return { ...out, data: asData(out.text) };
+  },
+
+  syntax: async ({ root }) => {
+    // `runGates`, not `verify`: verify appends a metrics row, and a diagnosis
+    // that changes the history it reports on is not read-only.
+    const result = await runGates(root, ["syntax"]);
+    return { text: formatReport(result).join("\n").replace(ANSI, ""), data: result };
+  },
+
+  types: async ({ root }) => {
+    const result = await runGates(root, ["types"]);
+    return { text: formatReport(result).join("\n").replace(ANSI, ""), data: result };
+  },
+
+  metrics: async ({ root }) => capture(metrics, rootArg(root)),
+};
+
+/**
+ * The MCP tool descriptor for one catalogue entry.
+ *
+ * @param {object} tool
+ * @returns {object}
+ */
+const descriptor = (tool) => {
+  const properties = {};
+  const required = [];
+  for (const param of tool.params) {
+    properties[param.name] = { type: param.type, description: param.description };
+    if (param.required) required.push(param.name);
+  }
+  return {
+    name: tool.id,
+    title: tool.title,
+    description:
+      `${tool.question} Read-only: ${tool.writes.length ? `only writes on the CLI (${tool.writes.join("; ")}), never here.` : "writes nothing."}`,
+    inputSchema: {
+      type: "object",
+      properties,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    },
+  };
+};
+
+/**
+ * Answer one JSON-RPC message.
+ *
+ * Exported so `scripts/check-report.mjs` can drive the protocol without a
+ * child process; the stdio loop below is a thin wrapper over it.
+ *
+ * @param {object} request
+ * @param {{cwd?: string}} [context]
+ * @returns {Promise<object|null>} null for a notification (no reply)
+ */
+export const handleRequest = async (request, { cwd = process.cwd() } = {}) => {
+  const { id = null, method, params = {} } = request || {};
+  const reply = (result) => ({ jsonrpc: "2.0", id, result });
+  const fail = (code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+
+  if (method === "initialize") {
+    return reply({
+      protocolVersion:
+        typeof params.protocolVersion === "string" ? params.protocolVersion : "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "flet-box", version },
+      instructions:
+        "Read-only diagnosis for a FletBox project. Start with `report` when you do not know which file is wrong; `widget_props` before writing a widget call; `metrics` when the same finding keeps returning.",
+    });
+  }
+  if (method === "notifications/initialized" || method === "notifications/cancelled") return null;
+  if (method === "ping") return reply({});
+  if (method === "tools/list") return reply({ tools: TOOLS.map(descriptor) });
+
+  if (method !== "tools/call") return fail(-32601, `unknown method: ${method}`);
+
+  const tool = toolById(params.name);
+  if (!tool) return fail(-32602, `unknown tool: ${params.name}`);
+  const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
+
+  const missing = tool.params.filter((param) => param.required && !args[param.name]);
+  if (missing.length) {
+    return reply({
+      content: [
+        { type: "text", text: `Missing argument(s): ${missing.map((param) => param.name).join(", ")}` },
+      ],
+      isError: true,
+    });
+  }
+
+  let root;
+  try {
+    root = args.root ? path.resolve(cwd, String(args.root)) : cwd;
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+      throw new Error(`no such directory: ${root}`);
+    }
+  } catch (error) {
+    return reply({ content: [{ type: "text", text: error.message }], isError: true });
+  }
+
+  try {
+    const result = await RUN[tool.id]({ ...args, root });
+    if (result.error) {
+      return reply({ content: [{ type: "text", text: result.text || result.error }], isError: true });
+    }
+    return reply({
+      content: [{ type: "text", text: result.text || "(no output)" }],
+      ...(result.data ? { structuredContent: result.data } : {}),
+    });
+  } catch (error) {
+    return reply({ content: [{ type: "text", text: `${tool.id} failed: ${error.message}` }], isError: true });
+  }
+};
+
+/**
+ * Serve the toolkit on stdin/stdout until the client closes the pipe.
+ *
+ * @returns {void}
+ */
+export const serveStdio = () => {
+  process.stderr.write(
+    `flet-box mcp v${version} — ${TOOLS.length} read-only tool(s) over stdio (JSON-RPC 2.0)\n`,
+  );
+  const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const write = (message) => {
+    if (message) process.stdout.write(`${JSON.stringify(message)}\n`);
+  };
+
+  // stdin can close while a request is still running — `report` takes about a
+  // second — and exiting on "close" would drop the answer the client is waiting
+  // for. Count the work in flight and leave only when the queue is empty.
+  let pending = 0;
+  let closed = false;
+  const finish = () => {
+    if (closed && pending === 0) process.exit(0);
+  };
+
+  input.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let request;
+    try {
+      request = JSON.parse(trimmed);
+    } catch {
+      write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+      return;
+    }
+    pending += 1;
+    handleRequest(request)
+      .then((message) => write(message))
+      .catch((error) => {
+        write({ jsonrpc: "2.0", id: request?.id ?? null, error: { code: -32603, message: error.message } });
+      })
+      .finally(() => {
+        pending -= 1;
+        finish();
+      });
+  });
+
+  input.on("close", () => {
+    closed = true;
+    finish();
+  });
+};
+
+export default serveStdio;

package/bin/utils/contract.js

@@ -0,0 +1,27 @@
+// bin/utils/contract.js
+//
+// `AGENTS_FOR_CODE_GEN.md` at the package root is the ONLY source for the
+// code-generation contract. `flet-box create` copies it into every app it
+// builds, the same way it copies the skills: one copy of the text, so an
+// editor, a diff and the app's own agent all read the same bytes.
+//
+// Node core only: `bin/` may not import a devDependency at module scope.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** The file name the contract carries inside a generated app. */
+export const CONTRACT_FILE = "AGENTS_FOR_CODE_GEN.md";
+
+/** Absolute path of the shipped contract. */
+export const contractPath = () => path.join(packageDir, CONTRACT_FILE);
+
+/**
+ * The contract text.
+ * @throws when the file is missing — a missing contract is a build error, not a
+ * silent skip, or the app ships with half the rules and nobody notices.
+ */
+export const readContract = () => fs.readFileSync(contractPath(), "utf8");

package/bin/utils/dtsProps.js

@@ -107,8 +107,12 @@ export const parseInterfaces = (source) => {
   // Comments can contain `interface` in prose; strip them first so brace
   // matching never starts on a documentation example.
   const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+  // `[^{;]*`, not `[^{]*`: a non-object alias (`export type FletWidget =
+  // WidgetFactoryInstance;`) has no brace of its own, and the looser tail ran on
+  // to the next declaration's brace — swallowing the interface that followed it
+  // and with it every prop it declared.
   const header =
-    /(export\s+)?(?:declare\s+)?(?:interface\s+([A-Za-z_$][\w$]*)|type\s+([A-Za-z_$][\w$]*)\s*=\s*)([^{]*)\{/g;
+    /(export\s+)?(?:declare\s+)?(?:interface\s+([A-Za-z_$][\w$]*)|type\s+([A-Za-z_$][\w$]*)\s*=\s*)([^{;]*)\{/g;
   let match;
   while ((match = header.exec(code))) {
     const name = match[2] || match[3];

package/bin/utils/migrationGuide.js

@@ -0,0 +1,146 @@
+// bin/utils/migrationGuide.js
+//
+// The migration guide is the promise a release makes to the app that used the
+// previous one: "here is what changed, and here is what you write now".
+//
+// Three things read it, and all three read the same bytes:
+//   • `flet-box release --major` refuses to publish a major that has no
+//     section for it — a major is exactly the release where an app has to
+//     change something, so the guide must exist before the release does;
+//   • `scripts/check-migrations.mjs` proves the guide, the deprecation table
+//     and the codemod still agree with each other;
+//   • the person whose app is about to break.
+//
+// Node core only: `bin/` may not import a devDependency at module scope.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** The guide, relative to the package root. */
+export const GUIDE_RELATIVE = "docs/guides/migration.md";
+
+/**
+ * Absolute path of the guide inside a checkout.
+ *
+ * @param {string} [root]
+ * @returns {string}
+ */
+export const guidePath = (root = packageDir) =>
+  path.join(root, ...GUIDE_RELATIVE.split("/"));
+
+/**
+ * The guide's text, or null when there is none.
+ *
+ * @param {string} [root]
+ * @returns {string|null}
+ */
+export const readGuide = (root = packageDir) => {
+  try {
+    return fs.readFileSync(guidePath(root), "utf8");
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The guide's version sections, as `heading → body`.
+ *
+ * A section is a `## <version>` heading; anything under it belongs to it.
+ *
+ * @param {string|null} text
+ * @returns {Map<string, string>}
+ */
+export const sections = (text) => {
+  const map = new Map();
+  if (!text) return map;
+  let current = null;
+  let body = [];
+  for (const line of text.split(/\r?\n/)) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      if (current !== null) map.set(current, body.join("\n"));
+      current = heading[1];
+      body = [];
+      continue;
+    }
+    if (current !== null) body.push(line);
+  }
+  if (current !== null) map.set(current, body.join("\n"));
+  return map;
+};
+
+/**
+ * The "de X a Y" rows of one section.
+ *
+ * The table is the contract, so it is parsed rather than guessed: a row is
+ * `| Widget | From | To | What changed |`, and the header and the separator
+ * are not rows.
+ *
+ * @param {string|null} text The whole guide.
+ * @param {string} version The section heading, e.g. `"1.2.0"`.
+ * @returns {Array<{ widget: string, from: string, to: string, note: string }>}
+ */
+export const rowsFor = (text, version) => {
+  const body = sections(text).get(version);
+  if (!body) return [];
+  const rows = [];
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) continue;
+    const cells = trimmed
+      .split("|")
+      .slice(1, -1)
+      .map((cell) => cell.trim().replace(/`/g, ""));
+    if (cells.length < 3) continue;
+    const [widget, from, to] = cells;
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(widget)) continue; // the separator row
+    if (from === "From") continue; // the header row
+    rows.push({ widget, from, to, note: (cells[3] || "").trim() });
+  }
+  return rows;
+};
+
+/**
+ * Is this checkout the framework itself, rather than an app that uses it?
+ *
+ * Only the framework ships the guide and only the framework releases its own
+ * major version, so the guard never fires inside somebody's app.
+ *
+ * @param {string} [root]
+ * @returns {boolean}
+ */
+export const isFrameworkProject = (root = packageDir) => {
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  } catch {
+    return false;
+  }
+  const bin = pkg.bin && (pkg.bin["flet-box"] || pkg.bin.fletBox);
+  if (!bin) return false;
+  return fs.existsSync(path.join(root, bin));
+};
+
+/**
+ * What is missing before a version may be released, or null when nothing is.
+ *
+ * @param {string} version The version about to be published.
+ * @param {string} [root]
+ * @returns {{ version: string, reason: string }|null}
+ */
+export const missingMigration = (version, root = packageDir) => {
+  const text = readGuide(root);
+  if (!text) {
+    return { version, reason: `the migration guide is missing (${GUIDE_RELATIVE})` };
+  }
+  if (!sections(text).has(version)) {
+    return { version, reason: `the guide has no "## ${version}" section` };
+  }
+  if (!rowsFor(text, version).length) {
+    return { version, reason: `the "## ${version}" section of the guide has no rows` };
+  }
+  return null;
+};

package/bin/utils/moduleExports.js

@@ -12,7 +12,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { neutralise } from "./neutralise.js";
 
-const IDENT = "[A-Za-z_$][\\w$]*";
+// Unicode identifiers: an app is allowed to export `fijarTamaño`. The ASCII
+// class stopped at `ñ`, so the reader stored `fijarTama` and every import of the
+// real name came back as MISSING_EXPORT — a false positive the app then worked
+// around by renaming its exports.
+const IDENT = "[\\p{ID_Start}$_][\\p{ID_Continue}$]*";
 
 /**
  * Resolve a relative/absolute specifier the way the browser ESM loader would,
@@ -85,7 +89,7 @@ export const readModuleExports = (absFile, cache = new Map(), chain = new Set())
   // export const|let|var|function|class NAME  (incl. multi-declarator and async)
   const declRe = new RegExp(
     `export\\s+(?:async\\s+)?(?:const|let|var|function|class)\\s+(${IDENT})`,
-    "g",
+    "gu",
   );
   let decl;
   while ((decl = declRe.exec(code))) {
@@ -93,7 +97,7 @@ export const readModuleExports = (absFile, cache = new Map(), chain = new Set())
     // `export const a = 1, b = 2;` — only accept a later name when it is
     // immediately assigned, so type-ish commas cannot invent an export.
     const tail = code.slice(decl.index + decl[0].length, code.indexOf(";", decl.index));
-    const extraRe = new RegExp(`,\\s*(${IDENT})\\s*=`, "g");
+    const extraRe = new RegExp(`,\\s*(${IDENT})\\s*=`, "gu");
     let extra;
     while ((extra = extraRe.exec(tail))) surface.named.add(extra[1]);
   }
@@ -119,7 +123,7 @@ export const readModuleExports = (absFile, cache = new Map(), chain = new Set())
     for (const part of braces[1].split(",")) {
       const token = part.trim();
       if (!token) continue;
-      const aliased = new RegExp(`^(${IDENT})\\s+as\\s+(${IDENT})$`).exec(token);
+      const aliased = new RegExp(`^(${IDENT})\\s+as\\s+(${IDENT})$`, "u").exec(token);
       const original = aliased ? aliased[1] : token;
       const exportedAs = aliased ? aliased[2] : token;
       if (original === "default") {
@@ -140,7 +144,7 @@ export const readModuleExports = (absFile, cache = new Map(), chain = new Set())
   // export * [as NS] from './mod.js'
   const starRe = new RegExp(
     `export\\s+\\*\\s*(?:as\\s+(${IDENT})\\s+)?from\\s*['"]([^'"]+)['"]`,
-    "g",
+    "gu",
   );
   let star;
   while ((star = starRe.exec(code))) {