@grampro/kit 2.7.1 → 2.7.3

package/README.md

@@ -14,6 +14,9 @@ Figma design.
 npx @grampro/kit add DataGrid
 ```
 
+Or `npx @grampro/kit add` with no names, to pick from the list: type to search,
+space to select, enter to install.
+
 The source lands in `component-lib/`, or `src/component-lib/` in a project
 with a `src/` folder; `--dest` puts it anywhere you like, and later installs
 follow the first. There is no runtime package to depend on, and nothing to
@@ -84,7 +87,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. |
@@ -217,6 +221,10 @@ version. What is built and tested:
   application supplies. No model is bundled, downloaded or named.
 - **WebMCP** — one tool, `operate_grid`, exposing the same validated boundary to
   a browser agent. Needs no model at all.
+- **`<AgentSurface>`** — wrap a page and every field and grid in it describes
+  itself to a browser agent, from its own props, and is operated through its own
+  validator. One WebMCP tool, `operate_page`, for the whole page; no tool
+  definitions to write
 - A model evaluation harness, with the measurements that justify both
 
 Every producer — a model, a browser agent, a form — proposes. The validator
@@ -226,9 +234,10 @@ it is why no AI path gets a second route into the component.
 Nine of the 27 are agent-operable. The executor abstraction was the open
 question — a grid is driven through an imperative API, and a field is not — and
 it is settled: Combobox and DatePicker are driven through their handles,
-Input, Textarea, NumberInput, Checkbox, Switch and RadioGroup through the
-element their ref already hands back. Neither the contract, the schemas, the
-validator nor the refusals know which.
+Input, Textarea, Checkbox and Switch through the element their ref already
+hands back, and NumberInput and RadioGroup, inside an `<AgentSurface>`, through
+their own commit path — a number is not text, and a group is not one radio.
+Neither the contract, the schemas, the validator nor the refusals know which.
 
 Still open: the components whose value is in what they contain rather than what
 they hold — Menu, Tabs, Accordion, Modal, FileUploader — and the question of

package/index.cjs

@@ -24,7 +24,7 @@ const path = require("path");
 const crypto = require("crypto");
 const yargs = require("yargs/yargs");
 const { hideBin } = require("yargs/helpers");
-const readline = require("readline");
+const ui = require("./tools/ui.cjs");
 
 // Configuration
 const CONFIG = {
@@ -391,7 +391,7 @@ const copyCommonFiles = async (destPath) => {
     const src = path.join(LEGACY_SOURCE_PATH, ...file.src);
     const dest = path.join(destPath, file.dest);
     await fs.copy(src, dest, { overwrite: true });
-    console.log(`✓ ${file.dest} copied successfully`);
+    console.log(`${ui.check()} ${file.dest} copied successfully`);
   }
 };
 
@@ -467,7 +467,7 @@ const installShared = async (destPath, { force = false } = {}) => {
 
     if (order > 0) {
       console.error(
-        `\n✗ This project has shared v${installedVersion}, newer than the v${srcVersion} in this installer.`,
+        `\n${ui.cross()} This project has shared v${installedVersion}, newer than the v${srcVersion} in this installer.`,
       );
       console.error(
         "  Installing it would downgrade the folder and break the components already here.",
@@ -478,11 +478,17 @@ const installShared = async (destPath, { force = false } = {}) => {
       process.exit(1);
     }
 
-    if (order === 0) {
+    // The same version is only "already installed" when it is the same files:
+    // a release that changed shared/ without bumping it must still reach the
+    // project, or the components it brings import files that are not there.
+    const sameFiles = listFiles(src).every(
+      (file) => manifest.files[file] === sha256(path.join(src, file)),
+    );
+    if (order === 0 && sameFiles) {
       console.log(
         edited.length > 0
-          ? `✓ shared v${installedVersion} is already installed (keeping your ${edited.length} edited file(s))`
-          : `✓ shared v${installedVersion} is already installed`,
+          ? `${ui.check()} shared v${installedVersion} is already installed (keeping your ${edited.length} edited file(s))`
+          : `${ui.check()} shared v${installedVersion} is already installed`,
       );
       return;
     }
@@ -490,7 +496,7 @@ const installShared = async (destPath, { force = false } = {}) => {
 
   if (edited.length > 0 && !force) {
     console.error(
-      `\n✗ These files in component-lib/${SHARED_DIR} have local changes:`,
+      `\n${ui.cross()} These files in component-lib/${SHARED_DIR} have local changes:`,
     );
     edited.forEach((file) => console.error(`  - ${file}`));
     console.error(
@@ -541,8 +547,8 @@ const installShared = async (destPath, { force = false } = {}) => {
 
   console.log(
     installedVersion
-      ? `✓ shared updated ${installedVersion} → ${srcVersion}`
-      : `✓ shared v${srcVersion} installed`,
+      ? `${ui.check()} shared updated ${installedVersion} → ${srcVersion}`
+      : `${ui.check()} shared v${srcVersion} installed`,
   );
 };
 
@@ -656,7 +662,7 @@ const writeAntigravityRule = async (root) => {
 
 /**
  * Codex: a pointer in AGENTS.md rather than the skill itself, because that file
- * is always in context and the skill is 5 KB. Everything outside our markers is
+ * is always in context and the skill is about 10 KB. Everything outside our markers is
  * left exactly as it was.
  */
 const writeAgentsPointer = async (root) => {
@@ -727,7 +733,7 @@ const installSkill = async (
   const edited = locallyEdited(destRoot, manifest);
 
   if (edited.length > 0 && !force) {
-    console.error(`${NL}✗ These skill files have local changes:`);
+    console.error(`${NL}${ui.cross()} These skill files have local changes:`);
     edited.forEach((file) => console.error(`  - ${file}`));
     console.error(
       NL +
@@ -793,8 +799,8 @@ const installSkill = async (
 
   console.log(
     installedVersion
-      ? `✓ skill updated ${installedVersion} → ${PACKAGE_VERSION}`
-      : `✓ skill v${PACKAGE_VERSION} installed`,
+      ? `${ui.check()} skill updated ${installedVersion} → ${PACKAGE_VERSION}`
+      : `${ui.check()} skill v${PACKAGE_VERSION} installed`,
   );
   console.log(`  ${SKILL_DEST_DIR}/ (canonical, ${listFiles(src).length} files)`);
   if (targets.includes("claude")) {
@@ -833,6 +839,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 */
 
 /**
@@ -863,10 +908,17 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
     process.exit(1);
   }
 
-  const pkgPath = path.join(process.cwd(), "package.json");
-  const libraryVersion = fs.existsSync(pkgPath)
-    ? readJson(pkgPath, {}).version || "unknown"
-    : "unknown";
+  /*
+   * Each component is stamped with the kit version it was installed from —
+   * its install record, else the passport it shipped with — not with this
+   * project's own version. Stamping the project's version made every
+   * regenerated passport differ from the shipped one, so `passport --check`
+   * failed for components nobody had touched.
+   */
+  const libraryVersion = (name, dir) =>
+    readJson(path.join(dir, ".install-manifest.json"), {})?.version ||
+    readJson(path.join(dir, "passport.json"), {})?.source?.libraryVersion ||
+    PACKAGE_VERSION;
 
   const options = {
     libRoot: dest,
@@ -874,6 +926,7 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
     libraryVersion,
     includeLocal: true,
     coverageThreshold: undefined,
+    regenerate: `npx ${CLI_NAME} passport`,
   };
 
   try {
@@ -885,7 +938,7 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
           continue;
         }
         for (const issue of row.problems) {
-          console.log(`  ${issue.level === "error" ? "✗" : "!"} ${issue.component}: ${issue.message}`);
+          console.log(`  ${issue.level === "error" ? ui.cross(process.stdout) : ui.c.yellow("!")} ${issue.component}: ${issue.message}`);
         }
       }
       console.log(`${NL}${report.length} component(s) · ${errors} error(s) · ${warnings} warning(s)`);
@@ -895,13 +948,13 @@ const runPassport = async ({ check: checkOnly, dest: requestedDest }) => {
 
     const { results, written } = passport.generate(options);
     const errors = results.flatMap((r) => r.issues.filter((i) => i.level === "error"));
-    for (const issue of errors) console.error(`  ✗ ${issue.component}: ${issue.message}`);
+    for (const issue of errors) console.error(`  ${ui.cross()} ${issue.component}: ${issue.message}`);
     console.log(
-      `${NL}✓ ${results.length} passport(s) regenerated · ${written.length} changed`,
+      `${NL}${ui.check()} ${results.length} passport(s) regenerated · ${written.length} changed`,
     );
     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 +985,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 +1013,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 +1039,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
+          ? `${ui.check()} Component ${component} updated ${previous} → ${PACKAGE_VERSION}`
+          : `${ui.check()} Component ${component} replaced with ${PACKAGE_VERSION}${force ? " (--force)" : ""}`,
+      );
+    } else if (outcome === "unchanged") {
+      console.log(`${ui.check()} Component ${component} already up to date (${PACKAGE_VERSION})`);
+    } else {
+      console.log(
+        `${ui.check()} 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"
+      ? `${ui.cross()} ${component} was not replaced: it was installed before 2.7.2 and differs from ${PACKAGE_VERSION}, so it may hold your changes.`
+      : `${ui.cross()} ${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] || [];
@@ -984,14 +1112,14 @@ const installComponentWithDependencies = async (
 
   if (pendingInstalls.length === 0) {
     console.log(
-      `✓ ${component} and all its dependencies are already installed.`,
+      `${ui.check()} ${component} and all its dependencies are already installed.`,
     );
     return;
   }
 
   // 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 +1138,7 @@ const installMultipleComponents = async (
   components,
   destPath,
   current = false,
+  options = {},
 ) => {
   const allComponentsToInstall = new Set();
 
@@ -1029,7 +1158,7 @@ const installMultipleComponents = async (
 
   if (pendingInstalls.length === 0) {
     console.log(
-      "✓ All selected components and their dependencies are already installed.",
+      `${ui.check()} All selected components and their dependencies are already installed.`,
     );
     return;
   }
@@ -1038,7 +1167,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
@@ -1060,95 +1189,44 @@ const installMultipleComponents = async (
   console.log(`\nFor documentation visit: ${CONFIG.docs}`);
 };
 
-const interactiveComponentSelector = async (current = false) => {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    let selectedComponents = new Set();
-    let currentIndex = 0;
-
-    const renderMenu = () => {
-      console.clear();
-      console.log("🚀 Component Installer - Interactive Mode");
-      console.log(
-        "Use ↑/↓ arrow keys to navigate, SPACE to select/deselect, ENTER to install\n",
-      );
-
-      const availableComponents = getAvailableComponents(current);
-
-      availableComponents.forEach((component, index) => {
-        const isSelected = selectedComponents.has(component);
-        const isCurrentIndex = index === currentIndex;
-        const deps = CONFIG.dependencies[component]
-          ? ` (requires: ${CONFIG.dependencies[component].join(", ")})`
-          : "";
-
-        const prefix = isCurrentIndex ? ">" : " ";
-        const checkbox = isSelected ? "☑" : "☐";
-        const line = `${prefix} ${checkbox} ${component}${deps}`;
-
-        if (isCurrentIndex) {
-          console.log(`\x1b[36m${line}\x1b[0m`); // Cyan highlight
-        } else {
-          console.log(line);
-        }
-      });
-
-      console.log(`\nSelected: ${selectedComponents.size} components`);
-      console.log("Press ENTER to install selected components, or 'q' to quit");
-    };
-
-    const handleKeyPress = (key) => {
-      switch (key) {
-        case "": // Up arrow
-          currentIndex = Math.max(0, currentIndex - 1);
-          renderMenu();
-          break;
-        case "": // Down arrow
-          currentIndex = Math.min(
-            getAvailableComponents(current).length - 1,
-            currentIndex + 1,
-          );
-          renderMenu();
-          break;
-        case " ": // Space bar
-          const component = getAvailableComponents(current)[currentIndex];
-          if (selectedComponents.has(component)) {
-            selectedComponents.delete(component);
-          } else {
-            selectedComponents.add(component);
-          }
-          renderMenu();
-          break;
-        case "\r": // Enter
-          if (selectedComponents.size > 0) {
-            rl.close();
-            resolve(Array.from(selectedComponents));
-          }
-          break;
-        case "q":
-          rl.close();
-          resolve([]);
-          break;
-      }
-    };
-
-    // Enable raw mode to capture arrow keys
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", handleKeyPress);
-
-    renderMenu();
+/*
+ * Where each component sits in the docs' navigation, shown beside it in the
+ * picker and searchable: typing "overlay" narrows the list to the overlays.
+ */
+const GROUPS = {
+  Inputs: ["Button", "Checkbox", "Combobox", "DatePicker", "FileUploader", "Input", "NumberInput", "RadioGroup", "Switch", "Textarea"],
+  Data: ["DataGrid"],
+  Overlays: ["Dialog", "Menu", "Modal", "Popover", "Tooltip"],
+  Feedback: ["Alert", "Progress", "Skeleton", "Spinner", "Toaster"],
+  Display: ["Accordion", "Avatar", "Badge", "Card"],
+  Navigation: ["Breadcrumb", "Tabs"],
+};
+const groupOf = (component) =>
+  Object.keys(GROUPS).find((group) => GROUPS[group].includes(component)) || "";
+
+/** The one-line purpose a component's passport gives, for the picker's hint line. */
+const purposeOf = (component, current) => {
+  if (!current) return "";
+  const passport = readJson(path.join(SOURCE_PATH, folderFor(component, true), "passport.json"));
+  return (passport && passport.purpose) || "";
+};
 
-    rl.on("close", () => {
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
+const interactiveComponentSelector = async (current = false, destPath) => {
+  const { multiselect } = require("./tools/prompt.cjs");
+  const options = getAvailableComponents(current)
+    .map((component) => ({
+      value: component,
+      tag: current ? groupOf(component) : "",
+      hint: purposeOf(component, current),
+      note: destPath && checkComponentExists(component, destPath, current) ? "installed" : "",
+    }))
+    // The docs' order of groups, alphabetical within each.
+    .sort((a, b) => {
+      const order = Object.keys(GROUPS);
+      return order.indexOf(a.tag) - order.indexOf(b.tag) || a.value.localeCompare(b.value);
     });
-  });
+  const picked = await multiselect({ message: "Which components?", options });
+  return picked || [];
 };
 
 const parseMultipleComponents = (componentString) => {
@@ -1190,7 +1268,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 +1359,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 +1374,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")
@@ -1298,7 +1383,7 @@ const main = async () => {
     .example("$0 mcp install --for codex", "Only write the Codex config")
     .example("$0 secret set figma", "Store a Figma token in the OS credential store")
     .example("$0 design ./design.json", "Split a whole-file Figma export into design/")
-    .example("$0 -i", "Interactive selection")
+    .example("$0 add", "Pick components interactively (same as -i)")
     .help().argv;
 
   /*
@@ -1364,16 +1449,26 @@ 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;
     if (parsed.command === "passport") argv.passport = true;
     if (parsed.command === "add") {
       if (parsed.operands.length === 0) {
-        console.log(`Which component? Try: ${CLI_NAME} add Button    (or: ${CLI_NAME} list)`);
-        return;
+        // In a terminal, a bare `add` opens the picker; in a script it says what to type.
+        if (process.stdin.isTTY && process.stdout.isTTY) argv.interactive = true;
+        else {
+          console.log(`Which component? Try: ${CLI_NAME} add Button    (or: ${CLI_NAME} list)`);
+          return;
+        }
+      } else {
+        argv.add = parsed.operands.join(",");
       }
-      argv.add = parsed.operands.join(",");
     }
   } else if (argv.add || argv.list || argv.skill || argv.passport) {
     console.log(`Tip: the shorter form is \`${CLI_NAME} add <Component>\`.`);
@@ -1405,21 +1500,38 @@ const main = async () => {
 
   // Interactive mode
   if (argv.interactive) {
-    console.log("Starting interactive component selector...\n");
-    const selectedComponents = await interactiveComponentSelector(current);
+    const destPath = resolveDestPath(argv.dest);
+    const where = path.relative(process.cwd(), destPath) || ".";
+    ui.intro(`GramproKit ${PACKAGE_VERSION}`);
+    let selectedComponents;
+    try {
+      selectedComponents = await interactiveComponentSelector(current, destPath);
+    } catch (error) {
+      ui.outro(ui.c.red(error.message));
+      process.exitCode = 1;
+      return;
+    }
 
     if (selectedComponents.length === 0) {
-      console.log("No components selected. Exiting...");
+      ui.outro(ui.c.dim("Nothing installed."));
       return;
     }
+    console.log(ui.c.gray(ui.s.bar));
+    console.log(`${ui.c.gray(ui.s.bar)}  ${ui.c.dim(`Installing into ${where}/`)}`);
+    console.log("");
 
-    const destPath = resolveDestPath(argv.dest);
     await fs.ensureDir(destPath);
 
     await copySupportFiles(destPath, current, { force: argv.force });
 
     // Install selected components
-    await installMultipleComponents(selectedComponents, destPath, current);
+    await installMultipleComponents(selectedComponents, destPath, current, { force: argv.force });
+    console.log("");
+    ui.outro(
+      process.exitCode
+        ? ui.c.yellow("Done, with the warnings above.")
+        : `${ui.c.green("Done.")} Import them from ${ui.c.cyan(`${where}/`)}`,
+    );
     return;
   }
 
@@ -1470,10 +1582,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 });
   }
 };