@grampro/kit 2.7.1 → 2.7.3

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");
@@ -241,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) {
@@ -340,18 +308,69 @@ function installComponents(names) {
   }
 
   const cli = path.join(__dirname, "..", "..", "index.cjs");
+  const withoutColour = (env) => {
+    const copy = { ...env };
+    delete copy.FORCE_COLOR;
+    return copy;
+  };
+  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 output below is read by pattern. Colour would break the match, and
+      // a host that sets FORCE_COLOR for its own reasons would turn it on.
+      env: { ...withoutColour(process.env), NO_COLOR: "1" },
     });
-    // 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}` };
   }
+  // Belt and braces: whatever reached the output, match it without escapes.
+  const ansi = /\x1b\[[0-9;?]*[A-Za-z]/g;
+  stdout = stdout.replace(ansi, "");
+  stderr = stderr.replace(ansi, "");
+
+  // 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 = [
@@ -388,7 +407,7 @@ const TOOLS = [
   {
     name: "get_guidance",
     description:
-      "Authored guidance on a topic: forms, overlays, data-grid, pickers, styling, accessibility, data-display, toaster, install. Omit the topic to list them.",
+      "Authored guidance on a topic: forms (including making a page operable by a browser agent with <AgentSurface>), overlays, data-grid, pickers, styling, accessibility, data-display, toaster, install. Omit the topic to list them.",
     inputSchema: {
       type: "object",
       properties: { topic: { type: "string" } },

package/tools/passport/extract.cjs

@@ -14,9 +14,10 @@
 
 const fs = require("fs");
 const path = require("path");
-const crypto = require("crypto");
 const { allowlistFor } = require("./policy.cjs");
 const { describable } = require("./merge.cjs");
+const { componentHash } = require("./hash.cjs");
+const { resolveTypeScript } = require("./typescript.cjs");
 
 const PASSPORT_VERSION = "1.0.0";
 
@@ -27,23 +28,17 @@ 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.
  */
+/*
+ * A TypeScript with the compiler API, on any project: the project's own when
+ * it has the API, otherwise the kit's pinned version, fetched once and
+ * cached. See typescript.cjs for why, and for how the fetch is kept narrow.
+ * Progress goes to stderr so `doctor --json` keeps a clean stdout.
+ */
 function loadTypeScript(searchFrom = []) {
-  const paths = [...searchFrom, process.cwd(), __dirname].filter(Boolean);
-  try {
-    return require(require.resolve("typescript", { paths }));
-  } catch {
-    try {
-      return require("typescript");
-    } 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 resolveTypeScript({
+    searchFrom,
+    log: (message) => process.stderr.write(`${message}\n`),
+  }).ts;
 }
 
 const posix = (p) => p.replace(/\\/g, "/");
@@ -63,26 +58,6 @@ function sourceFiles(dir) {
   return out.sort();
 }
 
-/**
- * Hash of the inputs the passport is derived from. Deterministic: sorted paths,
- * file contents only, no timestamps.
- *
- * Line endings are normalised first. The same file arrives as CRLF on a
- * Windows checkout and LF on CI, so hashing the bytes verbatim made a
- * passport generated on one platform read as stale on the other — which it
- * did, for all 27 components at once. A content hash should not depend on
- * 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")}`;
-}
 
 /* ------------------------------------------------------------------ program */
 
@@ -449,9 +424,17 @@ function extractComponent(ts, program, checker, { name, dir, libRoot, libraryVer
       exports: componentExports.sort(),
     },
     source: {
-      libraryVersion,
+      // A project regenerating its copies stamps each with the kit version it
+      // came from, not the project's own version, so `passport --check` can
+      // compare like with like.
+      libraryVersion: typeof libraryVersion === "function" ? libraryVersion(name, dir) : libraryVersion,
       files: files.map((f) => posix(path.relative(dir, f))),
-      sourceHash: hashSources([...files, ...(fs.existsSync(path.join(dir, "styles.css")) ? [path.join(dir, "styles.css")] : [])], repoRoot),
+      sourceHash: componentHash(
+        name,
+        [...files, ...(fs.existsSync(path.join(dir, "styles.css")) ? [path.join(dir, "styles.css")] : [])].map(
+          (file) => ({ rel: posix(path.relative(dir, file)), file }),
+        ),
+      ),
     },
     props: propList,
     ...(externalBases.size
@@ -498,6 +481,5 @@ module.exports = {
   createProgram,
   extractComponent,
   sourceFiles,
-  hashSources,
   posix,
 };

package/tools/passport/hash.cjs

@@ -0,0 +1,56 @@
+/*
+ * 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")}`;
+}
+
+/**
+ * A component's sourceHash, labelled the same way wherever the component sits.
+ *
+ * Every file is labelled `source/components/<folder>/<path in folder>` — the
+ * path it has in this repository. In the repository that is simply where it
+ * is; in a project it is installed under `component-lib/` or `src/...`, and
+ * labelling it by that location made an untouched installed component hash
+ * differently from the passport it shipped with. One rule for both, so the
+ * generator, `passport --check` in a project, and `doctor` all agree.
+ *
+ * @param {string} folder  e.g. "date-picker"
+ * @param {{ rel: string, file: string }[]} files  path inside the folder ("/"-separated), absolute file
+ */
+function componentHash(folder, files) {
+  return hashEntries(files.map(({ rel, file }) => ({ label: `source/components/${folder}/${rel}`, file })));
+}
+
+module.exports = { hashEntries, componentHash };

package/tools/passport/index.cjs

@@ -149,6 +149,8 @@ function generate(opts) {
  */
 function check(opts) {
   const { results } = buildAll(opts);
+  // In this repository it is an npm script; in a project, the CLI.
+  const regenerate = opts.regenerate || "npm run passport";
   const report = [];
   let errors = 0;
   let warnings = 0;
@@ -161,14 +163,14 @@ function check(opts) {
     const problems = [...r.issues];
     if (actual === null) {
       problems.unshift({ level: "error", code: "missing-passport", component: r.name,
-        message: "no passport.json committed; run `npm run passport`" });
+        message: `no passport.json committed; run \`${regenerate}\`` });
     } else if (actual !== expected) {
       const reason =
         JSON.parse(actual).source?.sourceHash !== r.effective.source.sourceHash
           ? "source changed since the passport was generated"
           : "committed passport differs from generated output";
       problems.unshift({ level: "error", code: "stale-passport", component: r.name,
-        message: `passport stale — ${reason}; run \`npm run passport\`` });
+        message: `passport stale — ${reason}; run \`${regenerate}\`` });
     }
 
     errors += problems.filter((p) => p.level === "error").length;

package/tools/passport/typescript.cjs

@@ -0,0 +1,220 @@
+/*
+ * A TypeScript that has the compiler API, whatever the project has installed.
+ *
+ * Reading a component's contract means resolving types — following
+ * `ButtonVariant` to its string literals, expanding
+ * `Omit<ButtonHTMLAttributes<…>, "onClick">` into the props it leaves — and
+ * that is the type checker's job. The kit has always borrowed the project's
+ * TypeScript for it rather than shipping one, so that `npx @grampro/kit add`
+ * stays a small download.
+ *
+ * TypeScript 7 broke the borrowing. It is a native rewrite, its npm package
+ * does not expose the JavaScript compiler API (`createProgram` and the rest
+ * are absent), and it is what `npm i -D typescript` installs now. So when the
+ * project's TypeScript cannot do the job, the exact version the kit itself is
+ * built and tested with is fetched once, cached per user, and used from then
+ * on. Same extractor, same result, on any TypeScript the project happens to
+ * use — or none.
+ *
+ * Fetching code at run time is a supply-chain surface, so it is narrow:
+ *   - one exact version, never a range, so what runs is what was tested;
+ *   - installed by the npm the user already runs `npx` with, so the registry,
+ *     proxy, mirror and integrity checks are theirs, unchanged;
+ *   - `--ignore-scripts`, so nothing executes during the install;
+ *   - written to a temporary folder and moved into place only once complete,
+ *     so an interrupted download never leaves a half-cache that loads;
+ *   - checked after install: the version must be the pinned one and the API
+ *     must be present, or it is not used;
+ *   - `GRAMPRO_KIT_OFFLINE=1`, or npm's own offline setting, turns it off, and
+ *     the callers fall back to what needs no TypeScript.
+ * Nothing about the project changes: no package.json edit, no node_modules.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+/** The kit's own TypeScript. A test fails if this drifts from the devDependency. */
+const PINNED_VERSION = "6.0.3";
+
+/** Older names a project may have installed TypeScript 6 under, to sit beside 7. */
+const ALIASES = ["typescript-6", "typescript6"];
+
+const hasCompilerApi = (ts) => Boolean(ts && typeof ts.createProgram === "function" && ts.JsxEmit);
+
+function tryRequire(name, paths) {
+  try {
+    return require(require.resolve(name, { paths }));
+  } catch {
+    return null;
+  }
+}
+
+/** The per-user cache, where the operating system expects caches to live. */
+function cacheRoot(env = process.env, platform = process.platform, home = os.homedir()) {
+  if (env.GRAMPRO_KIT_CACHE_DIR) return path.resolve(env.GRAMPRO_KIT_CACHE_DIR);
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "grampro-kit", "Cache");
+  }
+  if (platform === "darwin") return path.join(home, "Library", "Caches", "grampro-kit");
+  return path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "grampro-kit");
+}
+
+const cacheDirFor = (version = PINNED_VERSION, env = process.env) =>
+  path.join(cacheRoot(env), `typescript-${version}`);
+
+/** The pinned TypeScript, if a previous run already fetched it. */
+function fromCache(dir) {
+  const pkg = path.join(dir, "node_modules", "typescript", "package.json");
+  try {
+    if (JSON.parse(fs.readFileSync(pkg, "utf8")).version !== PINNED_VERSION) return null;
+    const ts = require(path.join(dir, "node_modules", "typescript"));
+    return hasCompilerApi(ts) ? ts : null;
+  } catch {
+    return null;
+  }
+}
+
+/*
+ * The npm CLI's own entry point, run with the current node — never through a
+ * shell. `npm_execpath` is set when this is running under npm or npx; failing
+ * that, npm sits next to node in every standard install.
+ */
+function findNpmCli(env = process.env, execPath = process.execPath) {
+  const candidates = [];
+  if (env.npm_execpath) {
+    const given = env.npm_execpath;
+    candidates.push(given.replace(/npx-cli\.js$/, "npm-cli.js"), given);
+  }
+  const bin = path.dirname(execPath);
+  candidates.push(
+    path.join(bin, "node_modules", "npm", "bin", "npm-cli.js"), // Windows
+    path.join(bin, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"), // macOS, Linux
+  );
+  return candidates.find((file) => /npm-cli\.js$/.test(file) && fs.existsSync(file)) || null;
+}
+
+const offline = (env) =>
+  env.GRAMPRO_KIT_OFFLINE === "1" || String(env.npm_config_offline).toLowerCase() === "true";
+
+/** Fetch the pinned version into the cache. Returns the loaded module, or throws. */
+function download({ env = process.env, log = () => {} } = {}) {
+  const npmCli = findNpmCli(env);
+  if (!npmCli) {
+    const error = new Error("npm was not found next to node, so TypeScript could not be fetched.");
+    error.code = "ETYPESCRIPT_FETCH";
+    throw error;
+  }
+
+  const dir = cacheDirFor(PINNED_VERSION, env);
+  const staging = `${dir}.partial-${process.pid}`;
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.mkdirSync(staging, { recursive: true });
+  // A minimal manifest so npm treats the folder as its own project, not the user's.
+  fs.writeFileSync(path.join(staging, "package.json"), '{"name":"grampro-kit-cache","private":true}\n');
+
+  log(
+    `Fetching TypeScript ${PINNED_VERSION} once, to read component contracts ` +
+      `(cached in ${path.dirname(dir)}).`,
+  );
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        npmCli,
+        "install",
+        `typescript@${PINNED_VERSION}`,
+        "--prefix",
+        staging,
+        "--no-save",
+        "--no-package-lock",
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+        "--loglevel=error",
+      ],
+      { stdio: ["ignore", "ignore", "pipe"], timeout: 180000, env },
+    );
+  } catch (cause) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    const detail = String(cause.stderr || cause.message || "").trim().split("\n").slice(-2).join(" ");
+    const error = new Error(`Could not fetch TypeScript ${PINNED_VERSION}: ${detail || "npm failed"}`);
+    error.code = "ETYPESCRIPT_FETCH";
+    throw error;
+  }
+
+  // Verified before it is trusted, then moved into place in one step.
+  const fetched = fromCache(staging);
+  if (!fetched) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    const error = new Error(`The fetched TypeScript was not version ${PINNED_VERSION} with the compiler API.`);
+    error.code = "ETYPESCRIPT_FETCH";
+    throw error;
+  }
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.renameSync(staging, dir);
+  } catch {
+    // Another run finished first, or the rename is not allowed here; the
+    // verified staging copy is still fine to use for this run.
+    return fetched;
+  }
+  return fromCache(dir) || fetched;
+}
+
+/**
+ * The first TypeScript that has the compiler API: the project's own, a
+ * TypeScript 6 the project installed under an alias, the cached copy, or a
+ * freshly fetched one.
+ *
+ * @returns {{ ts: object, source: "project" | "alias" | "cache" | "downloaded" }}
+ * @throws  ETYPESCRIPT_API when the project's TypeScript lacks the API and
+ *          fetching is turned off or fails; ETYPESCRIPT_MISSING when there is
+ *          no TypeScript at all and fetching is off or fails.
+ */
+function resolveTypeScript({ searchFrom = [], env = process.env, allowDownload = true, log = () => {} } = {}) {
+  const paths = [...searchFrom, process.cwd(), __dirname].filter(Boolean);
+
+  const project = tryRequire("typescript", paths);
+  if (hasCompilerApi(project)) return { ts: project, source: "project" };
+  for (const alias of ALIASES) {
+    const candidate = tryRequire(alias, paths);
+    if (hasCompilerApi(candidate)) return { ts: candidate, source: "alias" };
+  }
+
+  const cached = fromCache(cacheDirFor(PINNED_VERSION, env));
+  if (cached) return { ts: cached, source: "cache" };
+
+  let fetchError = null;
+  if (allowDownload && !offline(env)) {
+    try {
+      return { ts: download({ env, log }), source: "downloaded" };
+    } catch (error) {
+      fetchError = error;
+    }
+  }
+
+  const why = fetchError
+    ? ` ${fetchError.message}`
+    : offline(env)
+      ? " Fetching it is turned off (offline)."
+      : "";
+  const error = new Error(
+    (project
+      ? `This project's TypeScript (${project.version || "unknown"}) has no compiler API — TypeScript 7 is a native rewrite without it — and TypeScript ${PINNED_VERSION} could not be used instead.`
+      : `Reading component contracts needs TypeScript ${PINNED_VERSION}, which could not be used.`) +
+      why +
+      ` It is fetched automatically when online; to provide it yourself: npm i -D typescript-6@npm:typescript@${PINNED_VERSION}`,
+  );
+  error.code = project ? "ETYPESCRIPT_API" : "ETYPESCRIPT_MISSING";
+  throw error;
+}
+
+module.exports = {
+  PINNED_VERSION,
+  resolveTypeScript,
+  hasCompilerApi,
+  cacheRoot,
+  cacheDirFor,
+  findNpmCli,
+};