@grampro/kit 2.7.1 → 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.1",
+    "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.1",
+    "libraryVersion": "2.7.3",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/tools/doctor/baseline.cjs

@@ -0,0 +1,228 @@
+/*
+ * What a component looked like when it was installed, and whether it still does.
+ *
+ * Components are copied into a project to be edited — that is the point of
+ * copy-in. Until 2.7.2 nothing recorded what was copied, so `add` could not
+ * tell a pristine Button from one somebody had spent a week on, and it
+ * overwrote both. This is the record.
+ *
+ * Each installed component gets `.install-manifest.json` beside its files:
+ * the kit version it came from, a hash of every file as written, and a
+ * compact copy of its contract. The contract is stored here, not just in
+ * passport.json, because the `passport` command regenerates passport.json
+ * from the project's own source — after which it describes the edits, not the
+ * baseline. Nothing rewrites the manifest except installing the component.
+ *
+ * Components installed before 2.7.2 have no manifest. For those the
+ * passport's own `sourceHash` is still usable: it was computed over the
+ * kit's files with the kit's path labels, and recomputing it over the
+ * project's copy with those same labels says whether anything changed.
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { componentHash } = require("../passport/hash.cjs");
+const { compactContract } = require("./contract.cjs");
+
+const MANIFEST = ".install-manifest.json";
+const PASSPORT = "passport.json";
+const TESTS_DIR = "__tests__";
+const MANIFEST_VERSION = 1;
+
+/*
+ * passport.json is derived, and the `passport` command regenerates it on
+ * purpose. Counting that as an edit would flag every project that ever ran
+ * it, so it is left out of change detection; the manifest carries the
+ * baseline contract instead.
+ */
+const DERIVED = new Set([PASSPORT]);
+
+/* The consumer's own overlay, which the CLI never writes. Adding it is not an edit. */
+const OWNED = new Set(["passport.local.json"]);
+
+const TEXT = /\.(tsx?|jsx?|mjs|cjs|css|md|json|svg|html?)$/i;
+
+/** A file's hash, ignoring line endings for text — autocrlf is not an edit. */
+function hashFile(file) {
+  const bytes = fs.readFileSync(file);
+  const content = TEXT.test(file) ? bytes.toString("utf8").replace(/\r\n/g, "\n") : bytes;
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/** Every file in a component folder, relative and "/"-separated, minus the manifest and tests. */
+function listFiles(dir, prefix = "") {
+  if (!fs.existsSync(path.join(dir, prefix))) return [];
+  return fs
+    .readdirSync(path.join(dir, prefix), { withFileTypes: true })
+    .flatMap((entry) => {
+      if (entry.name === MANIFEST || entry.name === TESTS_DIR) return [];
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink()) return []; // never follow a link out of the folder
+      return entry.isDirectory() ? listFiles(dir, relative) : [relative];
+    })
+    .sort();
+}
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Record a component as just installed. Hashes are taken from the source the
+ * kit copied, so the record describes what the kit wrote, whatever happened
+ * to the copy between the copy and this call.
+ */
+function writeManifest(destDir, { component, version, sourceDir }) {
+  const files = listFiles(sourceDir);
+  const manifest = {
+    manifestVersion: MANIFEST_VERSION,
+    component,
+    version,
+    installedAt: new Date().toISOString(),
+    files: Object.fromEntries(files.map((file) => [file, hashFile(path.join(sourceDir, file))])),
+    contract: compactContract(readJson(path.join(sourceDir, PASSPORT))),
+  };
+  fs.writeFileSync(path.join(destDir, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return manifest;
+}
+
+/** The passport's sourceHash, recomputed over the project's copy with the kit's labels. */
+function kitRelativeHash(dir, folder, passport) {
+  const files = passport?.source?.files;
+  if (!Array.isArray(files)) return null;
+  const entries = [];
+  for (const relative of files) {
+    // A path that climbs out of the folder is not one the kit ever wrote.
+    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({ 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({ rel: "styles.css", file: styles });
+  // The generator's own labelling rule, not a copy of it.
+  return componentHash(folder, entries);
+}
+
+/**
+ * Where an installed component stands against what was installed.
+ *
+ * `state` is one of:
+ *   pristine  every file is as the kit wrote it
+ *   edited    something changed; `changed`/`missing`/`added` say what, when known
+ *   unknown   installed before 2.7.2 and no longer matches what any record
+ *             describes — it may hold edits, so it is treated as edited
+ *
+ * @param {string} dir      the installed component folder
+ * @param {object} options
+ * @param {string} options.folder   its name, e.g. "date-picker"
+ * @param {string} [options.kitDir] the same component in the running CLI, for
+ *                                  the case where versions match and the files
+ *                                  can be compared directly
+ * @param {string} [options.kitVersion]
+ */
+function inspect(dir, { folder, kitDir, kitVersion }) {
+  const manifest = readJson(path.join(dir, MANIFEST));
+
+  if (manifest && manifest.files && typeof manifest.files === "object") {
+    const present = new Set(listFiles(dir));
+    const changed = [];
+    const missing = [];
+    for (const [file, hash] of Object.entries(manifest.files)) {
+      if (DERIVED.has(file)) continue;
+      if (!present.has(file)) missing.push(file);
+      else if (hashFile(path.join(dir, file)) !== hash) changed.push(file);
+    }
+    const added = [...present].filter(
+      (file) => !(file in manifest.files) && !DERIVED.has(file) && !OWNED.has(file),
+    );
+    return {
+      baseline: "manifest",
+      installedVersion: manifest.version || null,
+      state: changed.length || missing.length || added.length ? "edited" : "pristine",
+      changed,
+      missing,
+      added,
+      // Updating copies over the folder: it never deletes an added file, but it
+      // does replace a changed one and restore a deleted one.
+      destructive: changed.length > 0 || missing.length > 0,
+      baseContract: manifest.contract || null,
+    };
+  }
+
+  // Before 2.7.2: no manifest. Is the passport still the one the kit wrote?
+  const passport = readJson(path.join(dir, PASSPORT));
+  const recorded = passport?.source?.sourceHash;
+  const recomputed = recorded ? kitRelativeHash(dir, folder, passport) : null;
+  if (recorded && recomputed === recorded) {
+    return {
+      baseline: "passport",
+      installedVersion: passport.source.libraryVersion || null,
+      state: "pristine",
+      changed: [],
+      missing: [],
+      added: [],
+      destructive: false,
+      baseContract: compactContract(passport),
+    };
+  }
+
+  /*
+   * No record that still applies. Compare with the running CLI's own copy:
+   * identical files are pristine at this version. Any difference could be an
+   * edit or simply an older version, and there is no telling which — so it is
+   * reported as unknown, and `add` will not overwrite it without --force.
+   * Refusing once too often costs a flag; overwriting once too often costs
+   * someone's work.
+   */
+  if (kitDir && fs.existsSync(kitDir)) {
+    const ours = new Set(listFiles(kitDir).filter((file) => !DERIVED.has(file)));
+    const theirs = new Set(listFiles(dir).filter((file) => !DERIVED.has(file) && !OWNED.has(file)));
+    const changed = [...ours].filter(
+      (file) => theirs.has(file) && hashFile(path.join(dir, file)) !== hashFile(path.join(kitDir, file)),
+    );
+    const missing = [...ours].filter((file) => !theirs.has(file));
+    const added = [...theirs].filter((file) => !ours.has(file));
+    if (!changed.length && !missing.length && !added.length) {
+      return {
+        baseline: "kit",
+        installedVersion: kitVersion || null,
+        state: "pristine",
+        changed,
+        missing,
+        added,
+        destructive: false,
+        baseContract: compactContract(readJson(path.join(kitDir, PASSPORT))),
+      };
+    }
+    return {
+      baseline: "none",
+      installedVersion: passport?.source?.libraryVersion || null,
+      state: "unknown",
+      // Differences from the running CLI's copy — not necessarily your edits.
+      changed,
+      missing,
+      added,
+      destructive: true,
+      baseContract: null,
+    };
+  }
+
+  return {
+    baseline: "none",
+    installedVersion: null,
+    state: "unknown",
+    changed: [],
+    missing: [],
+    added: [],
+    destructive: true,
+    baseContract: null,
+  };
+}
+
+module.exports = { MANIFEST, inspect, writeManifest, listFiles, hashFile, kitRelativeHash };

package/tools/doctor/contract.cjs

@@ -0,0 +1,252 @@
+/*
+ * What a component promises, reduced to what a caller depends on, and how two
+ * of those promises differ.
+ *
+ * A text diff of two versions of Button.tsx says which lines moved. It cannot
+ * say that `variant` stopped accepting "ghost", or that a prop became
+ * required, or that the agent runtime lost an operation — and those are the
+ * only differences that break someone. The passport already records each of
+ * them, so the comparison is done there.
+ *
+ * Pure: no filesystem, no TypeScript. Everything here takes passports, or the
+ * compact contracts made from them, and returns plain data.
+ */
+
+/** The parts of a passport a caller can depend on. */
+function compactContract(passport) {
+  if (!passport || typeof passport !== "object") return null;
+  const props = {};
+  for (const prop of passport.props || []) {
+    if (!prop || typeof prop.name !== "string") continue;
+    props[prop.name] = {
+      type: prop.type || "",
+      typeText: normaliseType(prop.typeText || ""),
+      required: Boolean(prop.required),
+      origin: prop.origin || "derived",
+      ...(prop.default !== undefined ? { default: String(prop.default) } : {}),
+      ...(Array.isArray(prop.values) && prop.values.length
+        ? { values: prop.values.map(String).sort() }
+        : {}),
+    };
+  }
+  const events = {};
+  for (const event of passport.events || []) {
+    if (event && typeof event.name === "string") events[event.name] = normaliseType(event.signature || "");
+  }
+  return {
+    component: passport.identity?.component || null,
+    version: passport.source?.libraryVersion || null,
+    exports: [...(passport.identity?.exports || [])].map(String).sort(),
+    props,
+    events,
+    operations: Object.keys(passport.operations || {}).sort(),
+  };
+}
+
+/** Whitespace is not a type change. */
+const normaliseType = (text) => String(text).replace(/\s+/g, " ").trim();
+
+/*
+ * Inherited props come from React's DOM types, and whether they appear at all
+ * depends on whether @types/react was found when the passport was made. A
+ * project without it would report every one of them as "removed" — so when
+ * one side has inherited props and the other has none, only the component's
+ * own props are compared, and the report says so.
+ */
+function comparableProps(before, after) {
+  const has = (c) => Object.values(c.props).some((p) => p.origin === "inherited");
+  const ownOnly = has(before) !== has(after);
+  const pick = (c) =>
+    Object.fromEntries(Object.entries(c.props).filter(([, p]) => !ownOnly || p.origin !== "inherited"));
+  return { before: pick(before), after: pick(after), ownOnly };
+}
+
+/**
+ * Every difference between two contracts, oldest first.
+ *
+ * `severity` is what a caller should take from it:
+ *   breaking  code that worked against `before` may not compile or behave against `after`
+ *   changed   the promise moved, but existing callers keep working
+ *   added     something new, which nobody can be depending on yet
+ */
+function diffContracts(before, after) {
+  if (!before || !after) return { changes: [], ownPropsOnly: false };
+  const changes = [];
+  const add = (kind, name, change, severity, detail = {}) =>
+    changes.push({ kind, name, change, severity, ...detail });
+
+  const { before: bp, after: ap, ownOnly } = comparableProps(before, after);
+
+  for (const [name, was] of Object.entries(bp)) {
+    const now = ap[name];
+    if (!now) {
+      add("prop", name, "removed", "breaking", { from: was.typeText });
+      continue;
+    }
+    if (!was.required && now.required) add("prop", name, "now required", "breaking");
+    if (was.required && !now.required) add("prop", name, "now optional", "changed");
+
+    if (was.values || now.values) {
+      const gone = (was.values || []).filter((v) => !(now.values || []).includes(v));
+      const fresh = (now.values || []).filter((v) => !(was.values || []).includes(v));
+      if (gone.length) add("prop", name, "values removed", "breaking", { values: gone });
+      if (fresh.length) add("prop", name, "values added", "added", { values: fresh });
+    } else if (was.typeText !== now.typeText) {
+      // Without enumerated values there is no telling a widening from a
+      // narrowing, so it is reported without claiming either.
+      add("prop", name, "type changed", "changed", { from: was.typeText, to: now.typeText });
+    }
+
+    if ((was.default ?? null) !== (now.default ?? null)) {
+      add("prop", name, "default changed", "changed", { from: was.default ?? null, to: now.default ?? null });
+    }
+  }
+  for (const [name, now] of Object.entries(ap)) {
+    if (bp[name]) continue;
+    const type = now.values ? now.values.map((v) => JSON.stringify(v)).join(" | ") : now.typeText.replace(/ \| undefined$/, "");
+    add("prop", name, "added", now.required ? "breaking" : "added", { type, ...(now.required ? { required: true } : {}) });
+  }
+
+  for (const [name, signature] of Object.entries(before.events)) {
+    if (!(name in after.events)) add("event", name, "removed", "breaking");
+    else if (after.events[name] !== signature) {
+      add("event", name, "signature changed", "changed", { from: signature, to: after.events[name] });
+    }
+  }
+  for (const name of Object.keys(after.events)) {
+    if (!(name in before.events)) add("event", name, "added", "added");
+  }
+
+  for (const name of before.exports) if (!after.exports.includes(name)) add("export", name, "removed", "breaking");
+  for (const name of after.exports) if (!before.exports.includes(name)) add("export", name, "added", "added");
+
+  // An agent that drove this operation yesterday is refused it today.
+  for (const name of before.operations) {
+    if (!after.operations.includes(name)) add("operation", name, "removed", "breaking");
+  }
+  for (const name of after.operations) if (!before.operations.includes(name)) add("operation", name, "added", "added");
+
+  return { changes, ownPropsOnly: ownOnly };
+}
+
+const keyOf = (change) => `${change.kind}:${change.name}`;
+
+/**
+ * Your edits and upstream's, measured from the version you installed, and the
+ * places both of you changed the same thing.
+ *
+ * Without a base, only the difference between your copy and upstream can be
+ * reported, with no telling who moved — so it is reported as that, not
+ * dressed up as a three-way result.
+ */
+function threeWay(base, mine, theirs) {
+  if (!base) {
+    const differences = diffContracts(theirs, mine);
+    return { mode: "two-way", differences: differences.changes, ownPropsOnly: differences.ownPropsOnly };
+  }
+  const yours = diffContracts(base, mine);
+  const upstream = diffContracts(base, theirs);
+
+  const group = (changes) => {
+    const by = new Map();
+    for (const change of changes) by.set(keyOf(change), [...(by.get(keyOf(change)) || []), change]);
+    return by;
+  };
+  const ours = group(yours.changes);
+  const conflicts = [];
+  const merges = [];
+
+  for (const [key, upstreamChanges] of group(upstream.changes)) {
+    const ownChanges = ours.get(key);
+    if (!ownChanges) continue;
+    const { kind, name } = upstreamChanges[0];
+    const verdict = reconcile(kind, name, ownChanges, upstreamChanges, { base, mine, theirs });
+    if (verdict.conflict) conflicts.push({ kind, name, yours: verdict.yours, upstream: verdict.upstream });
+    else if (verdict.merged) merges.push({ kind, name, ...verdict.merged });
+  }
+
+  return {
+    mode: "three-way",
+    yours: yours.changes,
+    upstream: upstream.changes,
+    conflicts,
+    merges,
+    ownPropsOnly: yours.ownPropsOnly || upstream.ownPropsOnly,
+  };
+}
+
+const describeAll = (changes) => [...new Set(changes.map((c) => c.change))].join(", ");
+
+/*
+ * Two sides touched the same entry. Whether that is a conflict depends on
+ * what each did to it, not merely on both having done something:
+ *
+ *   - you added "ghost"-less values while upstream added "link": value sets
+ *     combine, so that merges, and the merged set is reported;
+ *   - one side removed the prop while the other changed it: a conflict, since
+ *     no combination keeps both intentions;
+ *   - both changed the type, the default, or the required-ness, to different
+ *     results: a conflict;
+ *   - both made the identical change: agreement, not reported at all.
+ */
+function reconcile(kind, name, ownChanges, upstreamChanges, { base, mine, theirs }) {
+  const kinds = (changes) => new Set(changes.map((c) => c.change));
+  const own = kinds(ownChanges);
+  const up = kinds(upstreamChanges);
+  const conflict = () => ({ conflict: true, yours: describeAll(ownChanges), upstream: describeAll(upstreamChanges) });
+
+  if (kind !== "prop") {
+    // Exports and operations either exist or do not, so both sides changing one
+    // means both made the same change. Events can diverge in signature.
+    if (kind === "event" && own.has("signature changed") && up.has("signature changed")) {
+      return mine.events[name] === theirs.events[name] ? {} : conflict();
+    }
+    if (own.has("removed") !== up.has("removed")) return conflict();
+    return {};
+  }
+
+  const minePropNow = mine.props[name];
+  const theirsPropNow = theirs.props[name];
+
+  // One side deleted it, the other kept and changed it.
+  if (own.has("removed") !== up.has("removed")) return conflict();
+  if (own.has("removed") && up.has("removed")) return {};
+
+  // Both added a prop of the same name: fine only if they agree on what it is.
+  if (own.has("added") && up.has("added")) {
+    return JSON.stringify(minePropNow) === JSON.stringify(theirsPropNow) ? {} : conflict();
+  }
+
+  if (minePropNow?.typeText !== theirsPropNow?.typeText && own.has("type changed") && up.has("type changed")) {
+    return conflict();
+  }
+  if (own.has("default changed") && up.has("default changed") && minePropNow?.default !== theirsPropNow?.default) {
+    return conflict();
+  }
+  if ((own.has("now required") && up.has("now optional")) || (own.has("now optional") && up.has("now required"))) {
+    return conflict();
+  }
+
+  // Value sets merge: start from the base, apply both sides' removals and additions.
+  const valueEdits = (s) => s.has("values added") || s.has("values removed");
+  if (valueEdits(own) && valueEdits(up)) {
+    const was = new Set(base.props[name]?.values || []);
+    const mineValues = new Set(minePropNow?.values || []);
+    const theirValues = new Set(theirsPropNow?.values || []);
+    const merged = new Set(was);
+    for (const v of was) if (!mineValues.has(v) || !theirValues.has(v)) merged.delete(v);
+    for (const v of mineValues) if (!was.has(v)) merged.add(v);
+    for (const v of theirValues) if (!was.has(v)) merged.add(v);
+    return { merged: { values: [...merged].sort() } };
+  }
+  return {};
+}
+
+/**
+ * Names a caller can write on this component's JSX: props and handlers. What
+ * your copy accepts and upstream does not is exactly what replacing yours with
+ * upstream would take away from your call sites.
+ */
+const acceptedNames = (contract) => new Set([...Object.keys(contract.props), ...Object.keys(contract.events)]);
+
+module.exports = { compactContract, diffContracts, threeWay, acceptedNames };