@grampro/kit 2.7.0 → 2.7.2

package/tools/mcp/server.cjs

@@ -24,6 +24,7 @@ const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const { figmaFrame } = require("./figma.cjs");
+const { jsxOpenings } = require("../jsx-tags.cjs");
 
 const CATALOGUE = path.join(__dirname, "..", "..", "source", "components");
 const REFERENCES = path.join(__dirname, "..", "..", ".gbs", "skills", "gbs-components", "references");
@@ -197,7 +198,23 @@ function getGuidance(topic) {
     ? fs.readdirSync(REFERENCES).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""))
     : [];
   if (!topic) return { topics: available };
+
+  /*
+   * `topic` is caller-controlled, and `path.join(REFERENCES, topic + ".md")`
+   * followed a `../` out of the references folder: a prompt-injected agent
+   * could turn this into "read any .md file on disk". The list is already an
+   * allowlist of what actually ships, so a topic that is not one of those
+   * names is refused before any path is built. The resolved-prefix check is
+   * the belt to that braces — it also stops a name that readdir would never
+   * produce, such as one reaching through a symlink.
+   */
+  if (!available.includes(topic)) {
+    return { error: `No guidance for "${topic}".`, topics: available };
+  }
   const file = path.join(REFERENCES, `${topic}.md`);
+  if (!path.resolve(file).startsWith(path.resolve(REFERENCES) + path.sep)) {
+    return { error: `No guidance for "${topic}".`, topics: available };
+  }
   if (!fs.existsSync(file)) return { error: `No guidance for "${topic}".`, topics: available };
   return { topic, text: fs.readFileSync(file, "utf8") };
 }
@@ -225,43 +242,10 @@ function validateUsage(code) {
 
   const issues = [];
   const used = [];
-  const opening = /<([A-Z][A-Za-z0-9]*)(?=[\s/>])/g;
-  let match;
-
-  while ((match = opening.exec(source))) {
-    const [, name] = match;
+  // Shared with `doctor`, which scans whole projects with the same rules.
+  for (const { name, attrs } of jsxOpenings(source)) {
     const entry = known.get(name);
     if (!entry) continue; // Not ours; the agent may compose with its own components.
-
-    /*
-     * Scan to the tag's own `>` rather than matching one. An attribute can
-     * hold an arrow function — `onDismiss={() => {}}` — so the first `>` is
-     * usually inside a brace, and a regex that stops there finds nothing.
-     */
-    let depth = 0;
-    let quote = null;
-    let end = -1;
-    for (let i = match.index + match[0].length; i < source.length; i += 1) {
-      const ch = source[i];
-      if (quote) {
-        if (ch === quote) quote = null;
-      } else if (ch === '"' || ch === "'" || ch === "`") {
-        quote = ch;
-      } else if (ch === "{") {
-        depth += 1;
-      } else if (ch === "}") {
-        depth -= 1;
-      } else if (ch === ">" && depth === 0) {
-        end = i;
-        break;
-      }
-    }
-    if (end === -1) continue; // Unterminated fragment; nothing reliable to say.
-
-    const rawAttrs = source.slice(match.index + match[0].length, end);
-    const attrs = [...rawAttrs.matchAll(/(?:^|\s)([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s*=|\s|$)/g)].map(
-      (m) => m[1],
-    );
     used.push({ component: name, props: attrs });
 
     for (const attr of attrs) {
@@ -324,18 +308,57 @@ function installComponents(names) {
   }
 
   const cli = path.join(__dirname, "..", "..", "index.cjs");
+  let stdout = "";
+  let stderr = "";
+  let failed = false;
   try {
-    const output = execFileSync(process.execPath, [cli, "add", ...wanted], {
+    stdout = execFileSync(process.execPath, [cli, "add", ...wanted], {
       cwd: process.cwd(),
       encoding: "utf8",
       timeout: 120000,
+      // Captured, not forwarded: the installer explains a refusal on stderr,
+      // and that explanation is what the agent most needs to read.
+      stdio: ["ignore", "pipe", "pipe"],
     });
-    // The installer prints the one manual step; the agent needs to see it.
-    const importLine = (output.match(/^\s*@import .+$/gm) || []).map((l) => l.trim());
-    return { installed: wanted, stylesheet: importLine, output: output.trim().slice(-1200) };
   } catch (error) {
-    return { error: `Install failed: ${(error.stdout || error.message || "").toString().slice(-600)}` };
+    failed = true;
+    stdout = (error.stdout || "").toString();
+    stderr = (error.stderr || "").toString();
+    if (!stdout && !stderr) return { error: `Install failed: ${error.message}` };
+  }
+
+  // The installer prints the one manual step; the agent needs to see it.
+  const importLine = (stdout.match(/^\s*@import .+$/gm) || []).map((l) => l.trim());
+  const done = [...stdout.matchAll(/✓ Component (\S+) /g)].map((m) => m[1]);
+
+  /*
+   * A component the project has edited is left alone by `add`, and this tool
+   * never passes --force. That is deliberate: replacing someone's edited
+   * component is their decision, and an agent asked to "install Button" has
+   * not been asked to discard the Button they already customised. So the
+   * agent is told what was kept, why, and how the user can see the changes —
+   * not handed a generic failure it might try to work around.
+   */
+  const kept = [...stderr.matchAll(/✗ (\S+) was not replaced/g)].map((m) => m[1]);
+  if (kept.length) {
+    return {
+      installed: done,
+      kept,
+      reason:
+        "These components have changes made in this project since they were installed, and " +
+        "install_component never overwrites them. They are still in place and still usable.",
+      advice:
+        "Do not try to replace them. Tell the user, and suggest " +
+        `\`npx @grampro/kit doctor ${kept.join(" ")}\`: it shows what was changed locally, what the ` +
+        "new version changes, and which call sites an update would break. Replacing them with " +
+        "--force discards the user's work, which is their decision to make.",
+      detail: stderr.trim().slice(-1500),
+      stylesheet: importLine,
+    };
   }
+
+  if (failed) return { error: `Install failed: ${(stderr || stdout).trim().slice(-600)}` };
+  return { installed: wanted, stylesheet: importLine, output: stdout.trim().slice(-1200) };
 }
 
 const TOOLS = [

package/tools/passport/extract.cjs

@@ -14,9 +14,9 @@
 
 const fs = require("fs");
 const path = require("path");
-const crypto = require("crypto");
 const { allowlistFor } = require("./policy.cjs");
 const { describable } = require("./merge.cjs");
+const { hashEntries } = require("./hash.cjs");
 
 const PASSPORT_VERSION = "1.0.0";
 
@@ -27,23 +27,56 @@ const PASSPORT_VERSION = "1.0.0";
  * the runtime dependency story. The caller's project is searched first, so a
  * consumer regenerating a forked component uses their own TypeScript.
  */
+/*
+ * TypeScript 7 is a native rewrite and its npm package does not expose the
+ * compiler API this generator is built on — `createProgram`, `JsxEmit` and the
+ * rest are simply absent. It is also what `npm i -D typescript` installs now,
+ * so a current project has a `typescript` that loads fine and then fails on
+ * the first enum it is asked for, with an error about `ReactJSX` that says
+ * nothing useful.
+ *
+ * So a candidate is only accepted if it actually has the API. After the
+ * project's own `typescript`, a TypeScript 6 installed under an alias is
+ * tried: it sits beside a TypeScript 7 build without replacing it.
+ */
+const TS6_ALIASES = ["typescript-6", "typescript6"];
+const hasCompilerApi = (ts) => Boolean(ts && typeof ts.createProgram === "function" && ts.JsxEmit);
+
 function loadTypeScript(searchFrom = []) {
   const paths = [...searchFrom, process.cwd(), __dirname].filter(Boolean);
-  try {
-    return require(require.resolve("typescript", { paths }));
-  } catch {
+  const tryLoad = (name) => {
     try {
-      return require("typescript");
+      return require(require.resolve(name, { paths }));
     } catch {
-      const error = new Error(
-        "Passport generation needs the TypeScript compiler API.\n" +
-          "  Install it as a dev dependency:  npm i -D typescript\n" +
-          "  It is only needed to generate passports, never to run a component.",
-      );
-      error.code = "ETYPESCRIPT_MISSING";
-      throw error;
+      return null;
     }
+  };
+
+  const primary = tryLoad("typescript");
+  if (hasCompilerApi(primary)) return primary;
+  for (const alias of TS6_ALIASES) {
+    const candidate = tryLoad(alias);
+    if (hasCompilerApi(candidate)) return candidate;
   }
+
+  if (primary) {
+    const error = new Error(
+      `This project's TypeScript (${primary.version || "unknown version"}) does not provide the compiler API that ` +
+        "passports are read with: TypeScript 7 is a native rewrite without it.\n" +
+        "  Install TypeScript 6 alongside it, under another name, so your build keeps using 7:\n" +
+        "    npm i -D typescript-6@npm:typescript@6\n" +
+        "  It is only used to read component contracts, never to build or run a component.",
+    );
+    error.code = "ETYPESCRIPT_API";
+    throw error;
+  }
+  const error = new Error(
+    "Passport generation needs the TypeScript compiler API.\n" +
+      "  Install it as a dev dependency:  npm i -D typescript-6@npm:typescript@6\n" +
+      "  It is only needed to read component contracts, never to run a component.",
+  );
+  error.code = "ETYPESCRIPT_MISSING";
+  throw error;
 }
 
 const posix = (p) => p.replace(/\\/g, "/");
@@ -74,14 +107,8 @@ function sourceFiles(dir) {
  * how the file was checked out.
  */
 function hashSources(files, root) {
-  const h = crypto.createHash("sha256");
-  for (const f of [...files].sort()) {
-    h.update(posix(path.relative(root, f)));
-    h.update("\0");
-    h.update(fs.readFileSync(f, "utf8").replace(/\r\n/g, "\n"));
-    h.update("\0");
-  }
-  return `sha256:${h.digest("hex")}`;
+  // One implementation, shared with the installer: see hash.cjs for why.
+  return hashEntries(files.map((file) => ({ label: posix(path.relative(root, file)), file })));
 }
 
 /* ------------------------------------------------------------------ program */

package/tools/passport/hash.cjs

@@ -0,0 +1,39 @@
+/*
+ * The content hash a passport records as `source.sourceHash`.
+ *
+ * Kept on its own, with no TypeScript and no extractor behind it, because two
+ * very different callers need the identical function: the passport generator,
+ * which writes the hash, and the installer, which has to recompute it inside a
+ * user's project to tell an untouched component from an edited one. If those
+ * two ever disagreed by a byte, every installed component would read as
+ * edited, and `add` would refuse to update any of them.
+ *
+ * Entries are hashed by label, not by where the file sits on disk. The
+ * generator labels a file by its path inside this repository
+ * (`source/components/button/react/Button.tsx`); the installer reads the same
+ * file from `component-lib/button/react/Button.tsx` and labels it the same
+ * way. Sorting by that label — rather than by absolute path, as this used to —
+ * also makes the order independent of whether the OS separator is `/` or `\`.
+ */
+const fs = require("fs");
+const crypto = require("crypto");
+
+/**
+ * @param {{ label: string, file: string }[]} entries
+ * @returns {string} "sha256:<hex>"
+ */
+function hashEntries(entries) {
+  const h = crypto.createHash("sha256");
+  const sorted = [...entries].sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+  for (const { label, file } of sorted) {
+    h.update(label);
+    h.update("\0");
+    // Line endings normalised: the same file is CRLF on a Windows checkout
+    // and LF on CI, and a content hash must not depend on how it was checked out.
+    h.update(fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n"));
+    h.update("\0");
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+module.exports = { hashEntries };