@grampro/kit 2.7.2 → 2.7.3

package/source/components/textarea/passport.manual.json

@@ -6,7 +6,7 @@
     "ActionIntent",
     "Summarization"
   ],
-  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap. Inside an <AgentSurface> the component registers itself with these operations; NumberInput and RadioGroup are then written through their own commit path rather than the element.",
   "operations": {
     "setValue": {
       "summary": "Write a value into the field, as though a person had entered it.",

package/source/components/textarea/react/Textarea.tsx

@@ -16,6 +16,7 @@ import {
 } from "react";
 import { useControllableState } from "../../shared/react/useControllableState";
 import { describeField } from "../../shared/core/field";
+import { labelText, useAgentSurfaceField } from "../../shared/react/agentSurfaceContext";
 import { countCharacters } from "../core/count";
 import { fitHeight } from "../core/size";
 import type { FieldSize, TextareaLocaleText, TextareaResize } from "../core/types";
@@ -99,6 +100,21 @@ export function Textarea(props: TextareaProps) {
 
   // Mirrors the text even when uncontrolled, for the counter and auto-resize.
   const [current, setCurrent] = useControllableState(valueProp, defaultValue ?? "");
+
+  // Inside an <AgentSurface>, offered to an agent with what it accepts now.
+  useAgentSurfaceField(() => ({
+    contract: {
+      component: "Textarea",
+      kind: "text",
+      label: labelText(label, textareaProps["aria-label"], textareaProps.name, textareaProps.placeholder),
+      disabled,
+      readOnly,
+      required,
+      maxLength,
+      operations: ["setValue", "clear", "focus"],
+    },
+    target: () => textareaRef.current,
+  }));
   const floor = Math.max(1, minRows ?? rows ?? 3);
 
   const handleChange = (event: ChangeEvent<HTMLTextAreaElement>) => {

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/api.ts",
       "core/index.ts",

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.2",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/tools/doctor/baseline.cjs

@@ -21,7 +21,7 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
-const { hashEntries } = require("../passport/hash.cjs");
+const { componentHash } = require("../passport/hash.cjs");
 const { compactContract } = require("./contract.cjs");
 
 const MANIFEST = ".install-manifest.json";
@@ -100,12 +100,13 @@ function kitRelativeHash(dir, folder, passport) {
     if (typeof relative !== "string" || relative.split(/[\\/]/).includes("..")) return null;
     const file = path.join(dir, relative);
     if (!fs.existsSync(file)) return null; // a file the passport lists is gone: not pristine
-    entries.push({ label: `source/components/${folder}/${relative}`, file });
+    entries.push({ rel: relative, file });
   }
   // The generator hashes styles.css alongside the source when there is one.
   const styles = path.join(dir, "styles.css");
-  if (fs.existsSync(styles)) entries.push({ label: `source/components/${folder}/styles.css`, file: styles });
-  return hashEntries(entries);
+  if (fs.existsSync(styles)) entries.push({ rel: "styles.css", file: styles });
+  // The generator's own labelling rule, not a copy of it.
+  return componentHash(folder, entries);
 }
 
 /**

package/tools/mcp/server.cjs

@@ -308,6 +308,11 @@ 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;
@@ -319,6 +324,9 @@ function installComponents(names) {
       // 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" },
     });
   } catch (error) {
     failed = true;
@@ -326,6 +334,10 @@ function installComponents(names) {
     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());
@@ -395,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

@@ -16,7 +16,8 @@ const fs = require("fs");
 const path = require("path");
 const { allowlistFor } = require("./policy.cjs");
 const { describable } = require("./merge.cjs");
-const { hashEntries } = require("./hash.cjs");
+const { componentHash } = require("./hash.cjs");
+const { resolveTypeScript } = require("./typescript.cjs");
 
 const PASSPORT_VERSION = "1.0.0";
 
@@ -28,55 +29,16 @@ const PASSPORT_VERSION = "1.0.0";
  * 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.
+ * 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.
  */
-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);
-  const tryLoad = (name) => {
-    try {
-      return require(require.resolve(name, { paths }));
-    } catch {
-      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;
+  return resolveTypeScript({
+    searchFrom,
+    log: (message) => process.stderr.write(`${message}\n`),
+  }).ts;
 }
 
 const posix = (p) => p.replace(/\\/g, "/");
@@ -96,20 +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) {
-  // One implementation, shared with the installer: see hash.cjs for why.
-  return hashEntries(files.map((file) => ({ label: posix(path.relative(root, file)), file })));
-}
 
 /* ------------------------------------------------------------------ program */
 
@@ -476,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
@@ -525,6 +481,5 @@ module.exports = {
   createProgram,
   extractComponent,
   sourceFiles,
-  hashSources,
   posix,
 };

package/tools/passport/hash.cjs

@@ -36,4 +36,21 @@ function hashEntries(entries) {
   return `sha256:${h.digest("hex")}`;
 }
 
-module.exports = { hashEntries };
+/**
+ * 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,
+};