@grampro/kit 2.7.1 → 2.7.2

package/.gbs/skills/gbs-components/SKILL.md

@@ -31,8 +31,10 @@ npx @grampro/kit add Button,Input,Modal
 ```
 
 Writes `component-lib/<folder>/` plus `component-lib/shared/`. No flag is
-needed: the 2.x components are the default. Import the barrel in your
-component:
+needed: the 2.x components are the default. A component the project has
+edited is never overwritten — if `add` says it kept one, tell the user and
+suggest `npx @grampro/kit doctor <Component>`; **never retry with `--force`**,
+which discards their work. Import the barrel in your component:
 
 ```ts
 import { Button } from "component-lib/button";

package/.gbs/skills/gbs-components/references/install.md

@@ -20,7 +20,8 @@ npx @grampro/kit add Button                 # one component
 npx @grampro/kit add Button,Input,Modal     # several
 npx @grampro/kit -i                         # interactive picker
 npx @grampro/kit -l                         # list available
-npx @grampro/kit add Button --force         # overwrite edited shared/ files
+npx @grampro/kit doctor                     # what changed locally and upstream
+npx @grampro/kit doctor Button --json       # one component, for reading programmatically
 npx @grampro/kit skill                      # install this skill
 npx @grampro/kit skill --for claude         # only the Claude Code copy
 ```
@@ -33,7 +34,32 @@ npx @grampro/kit skill --for claude         # only the Claude Code copy
 | `--legacy` | — | Install from the 1.x set instead. Unmaintained; see below. |
 | `--skill` | — | Install this skill at the project root. `-skill` and `-a skill` also work. |
 | `--for` | — | With `--skill`: which agents to write adapters for (`claude`, `codex`, `antigravity`, or `none`). Default: all. |
-| `--force` | — | Replace files you have edited locally in `shared/` or `.gbs/`. |
+| `--force` | — | Replace a component, `shared/` or `.gbs/` even though the project has edited it. Never pass it on the user's behalf. |
+| `--json` | — | With `doctor`: print the report as JSON. |
+
+## Components the project has changed
+
+Copied components are meant to be edited, so `add` treats an edited one as
+the project's code, not the kit's:
+
+- **Untouched** — `add` updates it in place.
+- **Edited** since it was installed — `add` leaves it alone, prints which
+  files changed, and exits 1. The component is still installed and usable.
+
+When that happens, **stop and tell the user.** Do not rerun with `--force`:
+it discards their changes, and replacing their code is their decision, not
+yours. Show them `npx @grampro/kit doctor <Component>`, which reports:
+
+- which files they changed;
+- what they changed in the component's contract (props, values, handlers);
+- what the new version changes, and where the two conflict or merge;
+- the exact call sites in their code an update would break.
+
+Run `doctor` yourself before proposing an update. `doctor --json` gives the
+same report in a form you can read; it never writes anything.
+
+The MCP server's `install_component` follows the same rule and returns the
+components it kept under `kept`, with the reason.
 
 **Pass no flag.** The 2.x components are what `add` installs. `--beta` used
 to opt in to them and now does nothing but print a notice, so do not pass it.

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 2.7.2
+
+### Fixed
+
+**`add` overwrote components you had edited, and said it had succeeded.**
+Components are copied into your project so that you can change them, but
+running `add` on one that was already installed replaced the whole folder
+unconditionally. It printed "installed successfully" and the edits were gone.
+The same happened through the MCP server: `install_component` runs `add`, so an
+agent asked to "install Button" in a project with a customised Button
+discarded the customisation.
+
+Now every install records what it wrote — a hash of each file and a copy of
+the component's contract, in `.install-manifest.json` beside the component —
+and `add` checks that record first. An untouched component is updated. An
+edited one is left in place: `add` lists the files that changed, prints how to
+see more, and exits 1, while the other components in the same command still
+install. Only `--force` replaces an edited component. `shared/` has worked this
+way since it was introduced; components never did.
+
+Components installed before this release have no record. An untouched one is
+recognised from its passport's `sourceHash` — recomputed over your copy with
+the labels the kit hashed it with, which a test holds to the shipped value for
+all 27 — and is updated normally. One that differs from this version cannot be
+told apart from an older untouched copy, so it is kept, not guessed at.
+
+**`install_component` told an agent nothing when it was refused.** The
+installer explains a refusal on stderr, and the tool only returned stdout — so
+the agent got "Install failed" followed by stylesheet instructions. It now
+returns what was installed, what was kept and why, and advice not to force it.
+
+**`passport` crashed in any project on TypeScript 7.** TypeScript 7 is a
+native rewrite whose npm package does not expose the compiler API passports
+are generated with, and it is what `npm i -D typescript` installs today. The
+command failed with `Cannot read properties of undefined (reading
+'ReactJSX')`. It now checks for the API rather than for the package, falls
+back to a TypeScript 6 installed under an alias, and otherwise says exactly
+that, with the one-line fix.
+
+**`validate_usage` invented props from inside expressions.** Attribute names
+were matched anywhere in a tag, so `title={ok ? first : second}` reported
+`first` and `second` as unknown props. The tag scanner now reads names only at
+the top level, outside braces and quotes. It is shared with `doctor`, and stays
+linear on hostile input.
+
+### Added
+
+**`npx @grampro/kit doctor`** — what you changed in your copies, what the new
+version changes, and which call sites in your code an update would break.
+
+It compares three versions of each component: the one you installed, your copy
+now, and the one the CLI carries. It compares them as contracts — props,
+accepted values, handlers, exports, agent operations — because a text diff of
+`Button.tsx` shows which lines moved, not that `variant` stopped accepting
+`"ghost"`. Edits from both sides to the same value set are merged rather than
+called a conflict; a conflict is an incompatible pair, such as you removing a
+prop that upstream changed. Then it scans your source and names the call sites
+that pass something the replacement would not accept.
+
+It never writes. `--json` gives the same report to agents and CI. The agent
+skill now tells agents to run it, and never to retry `add` with `--force` on
+someone else's edits. A new docs page, *Updating components*, covers all of it.
+
 ## 2.7.1
 
 ### Security

package/README.md

@@ -84,7 +84,8 @@ genuinely headless, and the component READMEs document it under "Headless use".
 
 | | |
 | --- | --- |
-| `add <Component>...` | Copy components into the project. `--dest` chooses where; `--legacy` reaches the 1.x set. |
+| `add <Component>...` | Copy components into the project, or update ones already there. A component you have edited is left alone unless you pass `--force`. `--dest` chooses where; `--legacy` reaches the 1.x set. |
+| `doctor [Component...]` | What you changed in your copies, what the new version changes, and which of your call sites an update would break. `--json` for agents and CI. |
 | `list` | What is available to add. |
 | `skill` | Install the agent skill. `--for claude,codex,antigravity` narrows it. |
 | `mcp` | Run the MCP server. Agents start this themselves; you rarely type it. |

package/index.cjs

@@ -833,6 +833,45 @@ const parseSkillTargets = (value) => {
   return wanted;
 };
 
+/* ---------------------------------------------------------------- doctor */
+
+/**
+ * Report on the components installed here: what was changed since install,
+ * what this version of the kit changes, and which call sites an update would
+ * break. Read-only. See tools/doctor/index.cjs.
+ */
+const runDoctorCommand = ({ only = [], dest: requestedDest, json = false }) => {
+  const dest = resolveDestPath(requestedDest);
+  if (!fs.existsSync(dest)) {
+    console.error(
+      `No ${path.basename(dest)}/ folder here, so there is nothing to check.` +
+        `${NL}  Install a component first: npx ${CLI_NAME} add Button`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const { runDoctor } = require("./tools/doctor/index.cjs");
+  const { formatReport, toJson } = require("./tools/doctor/format.cjs");
+  const report = runDoctor({
+    cwd: process.cwd(),
+    dest,
+    kitRoot: SOURCE_PATH,
+    kitVersion: PACKAGE_VERSION,
+    only,
+  });
+
+  if (report.rows.length === 0 && report.notInstalled.length === 0) {
+    console.log(`No ${CLI_NAME} components found in ${path.relative(process.cwd(), dest) || dest}/.`);
+    return;
+  }
+
+  const shown = { ...report, dest: `${(path.relative(process.cwd(), dest) || ".").split(path.sep).join("/")}/` };
+  console.log(json ? JSON.stringify(toJson(shown), null, 2) : formatReport(shown));
+  // A component someone asked about that is not here is the one failure worth an exit code.
+  if (report.notInstalled.length) process.exitCode = 1;
+};
+
 /* ------------------------------------------------------------- passports */
 
 /**
@@ -901,7 +940,7 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
     );
     if (errors.length > 0) process.exit(1);
   } catch (error) {
-    if (error.code === "ETYPESCRIPT_MISSING" || error.code === "EBADJSON") {
+    if (error.code === "ETYPESCRIPT_MISSING" || error.code === "ETYPESCRIPT_API" || error.code === "EBADJSON") {
       console.error(error.message);
       process.exit(1);
     }
@@ -932,13 +971,27 @@ const checkComponentExists = (component, destPath, current = false) => {
   return fs.existsSync(componentPath);
 };
 
-const copyComponent = async (component, destPath, current = false) => {
+/*
+ * Copy one component into the project — unless that would destroy edits.
+ *
+ * Components are copied in to be edited; that is what owning the code means.
+ * Until 2.7.2 this overwrote the folder unconditionally, so running `add` on a
+ * component that was already there — by hand, from a script, or by an agent
+ * through the MCP server's install_component — silently replaced whatever had
+ * been changed in it, and printed a success message while doing so.
+ *
+ * Now an installed component is compared with the record written when it was
+ * installed. Untouched, it is updated. Changed — or installed before there
+ * were records, and different from this version — it is left alone unless
+ * `--force` is passed, and the user is told what differs and how to see more.
+ *
+ * Returns "installed", "updated", "unchanged" or "kept".
+ */
+const copyComponent = async (component, destPath, current = false, { force = false } = {}) => {
   try {
-    const componentSrc = path.join(
-      getSourcePath(current),
-      folderFor(component, current),
-    );
-    const componentDest = path.join(destPath, folderFor(component, current));
+    const folder = folderFor(component, current);
+    const componentSrc = path.join(getSourcePath(current), folder);
+    const componentDest = path.join(destPath, folder);
 
     if (!fs.existsSync(componentSrc)) {
       throw new Error(
@@ -946,6 +999,25 @@ const copyComponent = async (component, destPath, current = false) => {
       );
     }
 
+    let outcome = "installed";
+    let previous = null;
+    // The 1.x set is unmaintained and keeps its old behaviour.
+    if (current && fs.existsSync(componentDest)) {
+      const status = doctorBaseline().inspect(componentDest, {
+        folder,
+        kitDir: componentSrc,
+        kitVersion: PACKAGE_VERSION,
+      });
+      previous = status.installedVersion;
+
+      if (status.destructive && !force) {
+        reportKept(component, status);
+        process.exitCode = 1;
+        return "kept";
+      }
+      outcome = status.state === "pristine" && status.installedVersion === PACKAGE_VERSION ? "unchanged" : "updated";
+    }
+
     // The whole folder travels, which includes passport.json and
     // passport.manual.json. The passport is part of the component contract,
     // not an add-on — a contract you opt into is not a contract.
@@ -953,23 +1025,65 @@ const copyComponent = async (component, destPath, current = false) => {
       overwrite: true,
       filter: (source) => !isTestPath(path.relative(componentSrc, source)),
     });
-    console.log(
-      `✓ Component ${component} installed successfully ${
-        component === "Grid"
-          ? "This Version of Grid will be deprecated soon. Please Install The New Data Grid Component"
-          : ""
-      }`,
-    );
+
+    // The record `doctor` and the next `add` compare against.
+    if (current) {
+      doctorBaseline().writeManifest(componentDest, {
+        component,
+        version: PACKAGE_VERSION,
+        sourceDir: componentSrc,
+      });
+    }
+
+    if (outcome === "updated") {
+      console.log(
+        previous && previous !== PACKAGE_VERSION
+          ? `✓ Component ${component} updated ${previous} → ${PACKAGE_VERSION}`
+          : `✓ Component ${component} replaced with ${PACKAGE_VERSION}${force ? " (--force)" : ""}`,
+      );
+    } else if (outcome === "unchanged") {
+      console.log(`✓ Component ${component} already up to date (${PACKAGE_VERSION})`);
+    } else {
+      console.log(
+        `✓ Component ${component} installed successfully ${
+          component === "Grid"
+            ? "This Version of Grid will be deprecated soon. Please Install The New Data Grid Component"
+            : ""
+        }`,
+      );
+    }
+    return outcome;
   } catch (error) {
     console.error(`Error installing component ${component}:`, error.message);
     process.exit(1);
   }
 };
 
+/* Loaded on first use, so commands that never touch components don't pay for it. */
+let baselineModule = null;
+const doctorBaseline = () => (baselineModule ??= require("./tools/doctor/baseline.cjs"));
+
+/** Why a component was left alone, and the two ways forward. */
+const reportKept = (component, status) => {
+  const list = (label, files) =>
+    files.length ? `    ${label}: ${files.slice(0, 6).join(", ")}${files.length > 6 ? `, +${files.length - 6} more` : ""}` : null;
+  console.error(
+    status.state === "unknown"
+      ? `✗ ${component} was not replaced: it was installed before 2.7.2 and differs from ${PACKAGE_VERSION}, so it may hold your changes.`
+      : `✗ ${component} was not replaced: it has changes made since it was installed.`,
+  );
+  for (const line of [list("changed", status.changed), list("deleted", status.missing)].filter(Boolean)) {
+    console.error(line);
+  }
+  console.error(`  See what you changed and what ${PACKAGE_VERSION} changes:  npx ${CLI_NAME} doctor ${component}`);
+  console.error(`  Replace it anyway, losing those changes:      npx ${CLI_NAME} add ${component} --force`);
+};
+
 const installComponentWithDependencies = async (
   component,
   destPath,
   current = false,
+  options = {},
 ) => {
   // Get dependencies for the component
   const dependencies = CONFIG.dependencies[component] || [];
@@ -991,7 +1105,7 @@ const installComponentWithDependencies = async (
 
   // Install all pending components
   for (const comp of pendingInstalls) {
-    await copyComponent(comp, destPath, current);
+    await copyComponent(comp, destPath, current, options);
   }
 
   if (dependencies.length > 0) {
@@ -1010,6 +1124,7 @@ const installMultipleComponents = async (
   components,
   destPath,
   current = false,
+  options = {},
 ) => {
   const allComponentsToInstall = new Set();
 
@@ -1038,7 +1153,7 @@ const installMultipleComponents = async (
 
   // Install all pending components
   for (const comp of pendingInstalls) {
-    await copyComponent(comp, destPath, current);
+    await copyComponent(comp, destPath, current, options);
   }
 
   // Show dependency information
@@ -1190,7 +1305,7 @@ const validateComponents = (components, current = false) => {
  * projects a week install this; breaking their scripts to tidy an argument
  * parser is not a trade worth making.
  */
-const COMMANDS = new Set(["add", "list", "skill", "passport", "mcp", "secret", "design"]);
+const COMMANDS = new Set(["add", "list", "skill", "passport", "mcp", "secret", "design", "doctor"]);
 
 /**
  * Flags that take a separate value, so the token after one is that value and
@@ -1281,7 +1396,12 @@ const main = async () => {
       type: "string",
     })
     .option("force", {
-      describe: "Replace files you have edited locally in shared/ or the skill",
+      describe: "Replace files you have edited locally: a component, shared/ or the skill",
+      type: "boolean",
+      default: false,
+    })
+    .option("json", {
+      describe: "With doctor: print the report as JSON, for agents and CI",
       type: "boolean",
       default: false,
     })
@@ -1291,6 +1411,8 @@ const main = async () => {
     .example("$0 skill", "Install the agent skill for every supported agent")
     .example("$0 skill --for claude", "Only the Claude Code copy")
     .example("$0 passport --check", "Fail if a passport is stale (CI)")
+    .example("$0 doctor", "What you changed, what upstream changed, what an update breaks")
+    .example("$0 doctor DataGrid --json", "One component, as JSON")
     .example("$0 add Select --legacy", "Install from the 1.x set")
     .example("$0 add Button --dest app/ui", "Choose where they go")
     .example("$0 mcp", "Serve the catalogue to a coding agent over MCP")
@@ -1364,6 +1486,11 @@ const main = async () => {
     return;
   }
 
+  if (parsed && parsed.command === "doctor") {
+    runDoctorCommand({ only: parsed.operands, dest: argv.dest, json: argv.json });
+    return;
+  }
+
   if (parsed) {
     if (parsed.command === "list") argv.list = true;
     if (parsed.command === "skill") argv.skill = true;
@@ -1419,7 +1546,7 @@ const main = async () => {
     await copySupportFiles(destPath, current, { force: argv.force });
 
     // Install selected components
-    await installMultipleComponents(selectedComponents, destPath, current);
+    await installMultipleComponents(selectedComponents, destPath, current, { force: argv.force });
     return;
   }
 
@@ -1470,10 +1597,10 @@ const main = async () => {
   // Install components
   if (components.length === 1) {
     // Single component installation (existing behavior)
-    await installComponentWithDependencies(components[0], destPath, current);
+    await installComponentWithDependencies(components[0], destPath, current, { force: argv.force });
   } else {
     // Multiple components installation
-    await installMultipleComponents(components, destPath, current);
+    await installMultipleComponents(components, destPath, current, { force: argv.force });
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "GramproKit — an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
   "type": "module",
   "files": [

package/source/components/accordion/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/open.ts",

package/source/components/alert/passport.json

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

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/identity.ts",
       "core/index.ts",

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/breadcrumb/passport.json

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

package/source/components/button/passport.json

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

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/trend.ts",

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/group.ts",

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/filter.ts",

package/source/components/data-grid/passport.json

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",

package/source/components/date-picker/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/calendar.ts",

package/source/components/dialog/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/api.ts",
       "core/dialog.ts",

package/source/components/file-uploader/passport.json

@@ -13,7 +13,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/input/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/count.ts",

package/source/components/menu/passport.json

@@ -16,7 +16,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/modal/passport.json

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

package/source/components/number-input/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/format.ts",

package/source/components/popover/passport.json

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

package/source/components/progress/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/progress.ts",

package/source/components/radio-group/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/group.ts",

package/source/components/skeleton/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/lines.ts",

package/source/components/spinner/passport.json

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

package/source/components/switch/passport.json

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