@grampro/kit 2.4.4 → 2.5.0

package/tools/mcp/secret.cjs

@@ -0,0 +1,289 @@
+/*
+ * Credentials, kept by the operating system instead of by the repository.
+ *
+ * The Figma token used to live in a `.env`, which meant a long-lived
+ * credential sitting in a file inside a git working tree — one `git add -A`
+ * away from being published. This moves it to whatever the platform already
+ * uses for secrets: the Windows Data Protection API, the macOS keychain, or
+ * the Secret Service on Linux. Each of those ties the ciphertext to the
+ * logged-in user, so a copied file is useless on another machine.
+ *
+ * Nothing here adds a dependency. Every backend is a command the OS ships
+ * with, and the fallback is a 0600 file — worse, but still outside the repo,
+ * and it says so rather than pretending otherwise.
+ */
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+/** Namespace for keychain/Secret-Service entries. */
+const SERVICE = "grampro-kit";
+
+/** Per-user config directory, following each platform's own convention. */
+function configDir() {
+  if (process.platform === "win32") {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), SERVICE);
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", SERVICE);
+  }
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), SERVICE);
+}
+
+/** True when a command exists and runs. */
+function available(command, args) {
+  try {
+    const probe = spawnSync(command, args, { stdio: "ignore", windowsHide: true });
+    return !probe.error;
+  } catch {
+    return false;
+  }
+}
+
+// --------------------------------------------------------------- windows
+
+/*
+ * DPAPI, reached through PowerShell because Node has no binding for it.
+ *
+ * The plaintext goes in over stdin, never as an argument — command lines are
+ * readable by other processes on the machine.
+ *
+ * The script is passed with `-Command` rather than `-EncodedCommand`, which
+ * accepts the base64 and then silently runs nothing on at least one shipped
+ * 5.1 build (5.1.22621): exit 0, no output, no error. Statements are joined
+ * with semicolons for that reason, and quoting is kept to single quotes so
+ * nothing needs escaping between here and the shell.
+ */
+function powershell(script, input) {
+  const run = spawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", script],
+    { input: input === undefined ? "" : input, encoding: "utf8", windowsHide: true },
+  );
+  if (run.error) throw run.error;
+  if (run.status !== 0) {
+    throw new Error((run.stderr || "PowerShell failed").trim().split("\n")[0]);
+  }
+  return run.stdout;
+}
+
+const DPAPI_PROTECT = [
+  "Add-Type -AssemblyName System.Security",
+  "$plain = [Console]::In.ReadToEnd()",
+  "$bytes = [System.Text.Encoding]::UTF8.GetBytes($plain)",
+  "[Convert]::ToBase64String([System.Security.Cryptography.ProtectedData]::Protect($bytes, $null, 'CurrentUser'))",
+].join("; ");
+
+const DPAPI_UNPROTECT = [
+  "Add-Type -AssemblyName System.Security",
+  "$sealed = [Convert]::FromBase64String([Console]::In.ReadToEnd().Trim())",
+  "[System.Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect($sealed, $null, 'CurrentUser'))",
+].join("; ");
+
+const dpapiFile = (name) => path.join(configDir(), "secrets", `${name}.dpapi`);
+
+const dpapi = {
+  label: "Windows Data Protection API (tied to your Windows account)",
+  set(name, value) {
+    // PowerShell may fold a long string across lines when there is no console
+    // to measure, and base64 does not survive that. Whitespace is dropped on
+    // the way in and on the way out.
+    const sealed = powershell(DPAPI_PROTECT, value).replace(/\s+/g, "");
+    if (!sealed) throw new Error("DPAPI returned nothing; the secret was not stored.");
+    const file = dpapiFile(name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, sealed, { encoding: "utf8", mode: 0o600 });
+  },
+  get(name) {
+    const file = dpapiFile(name);
+    if (!fs.existsSync(file)) return null;
+    // A file carried over from another account will not decrypt; that is the
+    // protection working, so it reads as absent rather than as an error.
+    try {
+      const sealed = fs.readFileSync(file, "utf8").replace(/\s+/g, "");
+      return powershell(DPAPI_UNPROTECT, sealed).trim() || null;
+    } catch {
+      return null;
+    }
+  },
+  remove(name) {
+    const file = dpapiFile(name);
+    if (!fs.existsSync(file)) return false;
+    fs.unlinkSync(file);
+    return true;
+  },
+  list() {
+    const dir = path.join(configDir(), "secrets");
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".dpapi")).map((f) => f.slice(0, -6));
+  },
+};
+
+// ----------------------------------------------------------------- macos
+
+/*
+ * The keychain. `security` takes the password as an argument, which is
+ * visible in `ps` for the moment the command runs — a real if narrow
+ * exposure, and the alternative is an interactive prompt that cannot work
+ * from a tool. Any process able to read that argument is already running as
+ * this user and could ask the keychain directly.
+ */
+const keychain = {
+  label: "macOS keychain",
+  set(name, value) {
+    const run = spawnSync(
+      "security",
+      ["add-generic-password", "-U", "-a", os.userInfo().username, "-s", `${SERVICE}.${name}`,
+        "-D", "api token", "-j", "GramproKit", "-w", value],
+      { encoding: "utf8" },
+    );
+    if (run.status !== 0) throw new Error((run.stderr || "security failed").trim());
+  },
+  get(name) {
+    const run = spawnSync(
+      "security",
+      ["find-generic-password", "-a", os.userInfo().username, "-s", `${SERVICE}.${name}`, "-w"],
+      { encoding: "utf8" },
+    );
+    return run.status === 0 ? run.stdout.trim() || null : null;
+  },
+  remove(name) {
+    const run = spawnSync(
+      "security",
+      ["delete-generic-password", "-a", os.userInfo().username, "-s", `${SERVICE}.${name}`],
+      { encoding: "utf8", stdio: "ignore" },
+    );
+    return run.status === 0;
+  },
+  /* The keychain has no cheap listing by service, so the known names are probed. */
+  list() {
+    return KNOWN.filter((name) => keychain.get(name) !== null);
+  },
+};
+
+// ----------------------------------------------------------------- linux
+
+/** libsecret's CLI, which every desktop keyring implements. */
+const secretTool = {
+  label: "Secret Service (GNOME Keyring, KWallet)",
+  set(name, value) {
+    const run = spawnSync(
+      "secret-tool",
+      ["store", "--label", `GramproKit ${name}`, "service", SERVICE, "account", name],
+      { input: value, encoding: "utf8" },
+    );
+    if (run.status !== 0) throw new Error((run.stderr || "secret-tool failed").trim());
+  },
+  get(name) {
+    const run = spawnSync("secret-tool", ["lookup", "service", SERVICE, "account", name], {
+      encoding: "utf8",
+    });
+    return run.status === 0 ? run.stdout.trim() || null : null;
+  },
+  remove(name) {
+    const run = spawnSync("secret-tool", ["clear", "service", SERVICE, "account", name], {
+      encoding: "utf8",
+      stdio: "ignore",
+    });
+    return run.status === 0;
+  },
+  list() {
+    return KNOWN.filter((name) => secretTool.get(name) !== null);
+  },
+};
+
+// -------------------------------------------------------------- fallback
+
+/*
+ * A 0600 file under the user's config directory. Not encrypted, and it says
+ * so when used — but it is outside the repository, which is the failure this
+ * whole module exists to prevent.
+ */
+const plainFile = {
+  label: "a 0600 file in your config directory (not encrypted)",
+  file: () => path.join(configDir(), "secrets.json"),
+  read() {
+    try {
+      return JSON.parse(fs.readFileSync(plainFile.file(), "utf8"));
+    } catch {
+      return {};
+    }
+  },
+  write(all) {
+    fs.mkdirSync(configDir(), { recursive: true });
+    fs.writeFileSync(plainFile.file(), `${JSON.stringify(all, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  },
+  set(name, value) {
+    const all = plainFile.read();
+    all[name] = value;
+    plainFile.write(all);
+  },
+  get(name) {
+    return plainFile.read()[name] || null;
+  },
+  remove(name) {
+    const all = plainFile.read();
+    if (!(name in all)) return false;
+    delete all[name];
+    plainFile.write(all);
+    return true;
+  },
+  list() {
+    return Object.keys(plainFile.read());
+  },
+};
+
+/** Secret names this package uses, for the backends that cannot enumerate. */
+const KNOWN = ["figma"];
+
+/** The best store this machine offers. Resolved once. */
+let chosen = null;
+function store() {
+  if (chosen) return chosen;
+  if (process.platform === "win32" && available("powershell.exe", ["-NoProfile", "-Command", "exit 0"])) {
+    chosen = dpapi;
+  } else if (process.platform === "darwin" && available("security", ["-h"])) {
+    chosen = keychain;
+  } else if (process.platform === "linux" && available("secret-tool", ["--version"])) {
+    chosen = secretTool;
+  } else {
+    chosen = plainFile;
+  }
+  return chosen;
+}
+
+const setSecret = (name, value) => store().set(name, value);
+const removeSecret = (name) => store().remove(name);
+const listSecrets = () => store().list();
+const describeStore = () => store().label;
+const isEncrypted = () => store() !== plainFile;
+
+/**
+ * A secret, if this machine holds one. Never throws: a missing or unreadable
+ * store is the same answer as an empty one, because every caller has another
+ * place to look.
+ */
+function getSecret(name) {
+  try {
+    return store().get(name);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  setSecret,
+  getSecret,
+  removeSecret,
+  listSecrets,
+  describeStore,
+  isEncrypted,
+  configDir,
+  KNOWN,
+};

package/tools/mcp/server.cjs

@@ -36,32 +36,69 @@ const SUPPORTED_PROTOCOLS = new Set(["2024-11-05", "2025-03-26", "2025-06-18", "
 
 const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
 
-const componentFolders = () =>
-  fs
+/*
+ * The catalogue, read once.
+ *
+ * Every lookup used to re-read and re-parse passports off disk: naming one
+ * component scanned until it matched, so `get_component("DataGrid")` cost ten
+ * file reads, and `validate_usage` parsed all twenty-seven on every call. The
+ * catalogue ships inside the package and cannot change while the server runs,
+ * so it is built once on first use and kept.
+ */
+let index = null;
+
+function catalogue() {
+  if (index) return index;
+
+  const folders = fs
     .readdirSync(CATALOGUE, { withFileTypes: true })
     .filter((e) => e.isDirectory() && fs.existsSync(path.join(CATALOGUE, e.name, "passport.json")))
     .map((e) => e.name)
     .sort();
 
-/** Resolve a name the way an agent would write it: "DataGrid", "data-grid", "datagrid". */
-function findFolder(name) {
-  const wanted = String(name || "").toLowerCase().replace(/[^a-z0-9]/g, "");
-  for (const folder of componentFolders()) {
-    if (folder.replace(/[^a-z0-9]/g, "") === wanted) return folder;
+  const byFolder = new Map();
+  const byName = new Map();
+
+  for (const folder of folders) {
+    // The one place that still touches disk — this is what builds the index.
     const passport = readJson(path.join(CATALOGUE, folder, "passport.json"));
-    const names = [passport.identity.component, ...(passport.identity.exports || [])];
-    if (names.some((n) => String(n).toLowerCase() === wanted)) return folder;
+    const entry = { folder, passport };
+    byFolder.set(folder, entry);
+
+    // Every spelling an agent might reasonably use.
+    const spellings = [folder, passport.identity.component, ...(passport.identity.exports || [])];
+    for (const spelling of spellings) {
+      byName.set(String(spelling).toLowerCase().replace(/[^a-z0-9]/g, ""), entry);
+    }
   }
-  return null;
+
+  index = { folders, byFolder, byName };
+  return index;
+}
+
+const componentFolders = () => catalogue().folders;
+
+/** Resolve a name the way an agent would write it: "DataGrid", "data-grid", "datagrid". */
+function findFolder(name) {
+  const entry = catalogue().byName.get(
+    String(name || "").toLowerCase().replace(/[^a-z0-9]/g, ""),
+  );
+  return entry ? entry.folder : null;
 }
 
+/** The parsed passport for a folder, from the index rather than from disk. */
+const passportOf = (folder) => catalogue().byFolder.get(folder).passport;
+
 /*
  * Most passports carry no `purpose`, so the README's opening line stands in.
  * It is the sentence a human wrote about what the component is for, which is
  * exactly what an agent needs to pick one.
  */
+const purposeCache = new Map();
+
 function purposeOf(folder, passport) {
   if (passport.purpose && passport.purpose.trim()) return passport.purpose.trim();
+  if (purposeCache.has(folder)) return purposeCache.get(folder);
   const readme = path.join(CATALOGUE, folder, "README.md");
   if (!fs.existsSync(readme)) return "";
   const line = fs
@@ -69,14 +106,16 @@ function purposeOf(folder, passport) {
     .split("\n")
     .map((l) => l.trim())
     .find((l) => l && !l.startsWith("#") && !l.startsWith("<!--"));
-  return line ? line.replace(/\s+/g, " ") : "";
+  const purpose = line ? line.replace(/\s+/g, " ") : "";
+  purposeCache.set(folder, purpose);
+  return purpose;
 }
 
 // -------------------------------------------------------------------- tools
 
 function listComponents() {
   return componentFolders().map((folder) => {
-    const passport = readJson(path.join(CATALOGUE, folder, "passport.json"));
+    const passport = passportOf(folder);
     return {
       component: passport.identity.component,
       folder,
@@ -98,7 +137,7 @@ function getComponent(name) {
   if (!folder) {
     return { error: `No component named "${name}". Call list_components for the catalogue.` };
   }
-  const p = readJson(path.join(CATALOGUE, folder, "passport.json"));
+  const p = passportOf(folder);
   return {
     component: p.identity.component,
     folder,
@@ -163,7 +202,7 @@ function validateUsage(code) {
   const source = String(code || "");
   const known = new Map();
   for (const folder of componentFolders()) {
-    const p = readJson(path.join(CATALOGUE, folder, "passport.json"));
+    const p = passportOf(folder);
     const props = new Set((p.props || []).map((x) => x.name));
     for (const e of p.events || []) props.add(e.name);
     const required = (p.props || []).filter((x) => x.required).map((x) => x.name);

package/tools/passport/cli.cjs

@@ -15,7 +15,14 @@ const { generate, check } = require("./index.cjs");
 
 const REPO = path.resolve(__dirname, "..", "..");
 const LIB = path.join(REPO, "source", "components");
-const COVERAGE_THRESHOLD = 40; // ratchet upward over time
+/*
+ * Ratchet upward over time. 40 was set when coverage counted every inherited
+ * HTML attribute in the denominator, which capped some components near 35% and
+ * made the gate unreachable by doing the work it asked for. Now that it
+ * measures the props this library authors, the library sits at 87% and the
+ * weakest component at 75, so this is the floor rather than an aspiration.
+ */
+const COVERAGE_THRESHOLD = 75;
 
 const args = process.argv.slice(2);
 const wantCheck = args.includes("--check");

package/tools/passport/extract.cjs

@@ -16,6 +16,7 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 const { allowlistFor } = require("./policy.cjs");
+const { describable } = require("./merge.cjs");
 
 const PASSPORT_VERSION = "1.0.0";
 
@@ -435,7 +436,10 @@ function extractComponent(ts, program, checker, { name, dir, libRoot, libraryVer
     .filter((p) => /^on[A-Z]/.test(p.name))
     .map((p) => ({ name: p.name, ...(p.signature ? { signature: p.signature } : {}) }));
 
-  const described = propList.filter((p) => p.description).length;
+  // Same rule as the merge step, so the two never disagree: coverage is over
+  // the props this library declares, not the HTML attributes it inherits.
+  const countable = propList.filter(describable);
+  const described = countable.filter((p) => p.description).length;
 
   const passport = {
     passportVersion: PASSPORT_VERSION,
@@ -463,9 +467,9 @@ function extractComponent(ts, program, checker, { name, dir, libRoot, libraryVer
     safeMutations: {},
     examples: [],
     coverage: {
-      propsTotal: propList.length,
+      propsTotal: countable.length,
       propsDescribed: described,
-      describedPct: propList.length ? Math.round((described / propList.length) * 100) : 0,
+      describedPct: countable.length ? Math.round((described / countable.length) * 100) : 0,
       authoredSections: [],
     },
   };

package/tools/passport/merge.cjs

@@ -72,6 +72,25 @@ function mergeProps(derived, overlayProps, origin) {
   return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/*
+ * Props whose meaning is the same on every component in the library, and so
+ * belong in one page of conventions rather than in 27 passports. A one-line
+ * gloss on each would be filler, and filler in a passport is worse than
+ * silence: an agent reads it as information.
+ */
+const PLUMBING = new Set(["className", "classNames", "style", "ref", "key", "localeText"]);
+
+/**
+ * Whether a prop counts towards description coverage.
+ *
+ * Only what this library declares itself. An inherited prop is `aria-label`
+ * or `tabIndex` arriving through `extends ButtonHTMLAttributes` - documented
+ * by the HTML specification, and not ours to restate. Counting them put the
+ * reachable ceiling for some components near 35%, so the gate asked for work
+ * that could not move it.
+ */
+const describable = (prop) => prop.origin === "derived" && !PLUMBING.has(prop.name);
+
 /**
  * Produce the effective passport written to passport.json.
  *
@@ -112,20 +131,21 @@ function mergePassport(derived, manual = {}, local = {}) {
   }
 
   // Coverage is recomputed after overlays, since manual descriptions count.
-  const described = out.props.filter((p) => p.description).length;
+  const counted = out.props.filter(describable);
+  const described = counted.filter((p) => p.description).length;
   const authoredSections = [...AUTHORED].filter((k) => {
     const v = out[k];
     return Array.isArray(v) ? v.length > 0 : isObject(v) ? Object.keys(v).length > 0 : Boolean(v);
   }).sort();
 
   out.coverage = {
-    propsTotal: out.props.length,
+    propsTotal: counted.length,
     propsDescribed: described,
-    describedPct: out.props.length ? Math.round((described / out.props.length) * 100) : 0,
+    describedPct: counted.length ? Math.round((described / counted.length) * 100) : 0,
     authoredSections,
   };
 
   return out;
 }
 
-module.exports = { mergePassport, deepMerge, mergeProps, SOURCE_OWNED, AUTHORED, UNSAFE_KEYS };
+module.exports = { mergePassport, deepMerge, mergeProps, describable, SOURCE_OWNED, AUTHORED, UNSAFE_KEYS };