@kitn.ai/cli 0.4.0 → 0.5.0

package/dist/doctor.es.js

@@ -6,7 +6,14 @@ const RULES = [
     // Rule 1 — array/object data set as an HTML attribute
     // Source: for-ai-agents.mdx §1; context7.json rule 2
     id: "array-as-attribute",
-    test: (t) => /\b(messages|models|context|suggestions|triggers)\s*=\s*["']/.test(t),
+    // A LEADING `:` OR `[` IS A PROPERTY BINDING, WHICH IS THE CORRECT FORM, and this rule is about
+    // HTML ATTRIBUTES. Vue writes the right thing as `:messages="messages"` (or `v-bind:`), Angular
+    // as `[messages]="messages"`, and the bare `\b` matched the tail of both: measured, `kai doctor`
+    // warned on a freshly scaffolded vue app whose only `messages` occurrence was `:messages=`,
+    // telling the reader to do what they had already done. The lookbehind excludes a binding, a
+    // member access (`x.messages=`) and a compound attribute name (`data-messages=`), so a real
+    // `<kai-chat messages="[...]">` still fires.
+    test: (t) => /(?<![:.\[\w-])(messages|models|context|suggestions|triggers)\s*=\s*["']/.test(t),
     title: "Array/object prop set as an HTML attribute (silent failure)",
     cause: "An HTML attribute is always a string. Passing `messages`, `models`, `context`, `suggestions`, or `triggers` as an HTML attribute silently fails — the element receives a stringified value it cannot parse.",
     fix: "Set the property in JavaScript, not as an HTML attribute. Only scalar props (`placeholder`, `loading`, `theme`) work as attributes.\n\n```js\n// ✅ Works — set messages in JavaScript as a property\nconst chat = document.querySelector('kai-chat');\nchat.messages = [{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hello!' }] }];\n```\n\n```html\n<!-- ❌ Fails — messages cannot be an HTML attribute -->\n<kai-chat messages=\"[...]\"></kai-chat>\n```"
@@ -43,10 +50,25 @@ const RULES = [
   {
     // Rule 6 — web components not registered / renders nothing (React #1 failure)
     // Source: field-test reports; for-ai-agents.mdx §"Import order matters"
+    //
+    // THE SIGNALS MUST BE A REPORT'S VOCABULARY, NOT AN IDIOM WIRING USES. `kai doctor` runs this
+    // same rule set over a project's FILES (doctor.ts), so a signal that a correct app can contain
+    // reports a registered app as broken. Two were both, and the four raw-tag starters carry them
+    // verbatim: their upgrade gate reads
+    //   const unregistered = TAGS.filter((tag) => !customElements.get(tag));
+    // A bare `unregistered` therefore matched an identifier, and the bare `customElements.get`
+    // matched a guard. Measured: `kai doctor` on a freshly scaffolded vue app warned "Web components
+    // not registered" at src/main.ts, about an app that registers every tag it places.
+    //
+    // So the bare token now needs a noun after it (`unregistered element`, not `unregistered =`),
+    // and the idiom needs its undefined COMPARISON, which is what a pasted diagnostic carries
+    // (`customElements.get('kai-chat') === undefined`) and what a guard does not.
     id: "web-components-not-registered",
     test: (t) => {
-      if (/renders?\s+nothing|nothing\s+renders?|not\s+registered|unregistered|not\s+upgraded|unknown\s+element|customElements\.get|undefined\s+element|no\s+shadow\s+root/.test(t))
+      if (/renders?\s+nothing|nothing\s+renders?|not\s+registered|not\s+upgraded|unknown\s+element|undefined\s+element|no\s+shadow\s+root/.test(t))
         return true;
+      if (/\bunregistered\s+(?:kai|element|component|tag|web)/.test(t)) return true;
+      if (/customElements\.get\s*\([^)\n]*\)\s*(?:={2,3}|!={1,2})?\s*undefined/.test(t)) return true;
       if (/\b(empty|blank)\b/.test(t) && /render|element|component|kai-|<[a-z]+-|shadow/.test(t))
         return true;
       if (/doesn'?t\s+render|won'?t\s+render/.test(t) && /kai-|element|component|custom.?element/.test(t))
@@ -55,7 +77,7 @@ const RULES = [
     },
     title: "Web components not registered — renders nothing / empty box",
     cause: "The `@kitn.ai/ui/react` wrappers (and bare `<kai-*>` tags) do NOT register the web components by themselves. Without the registration side-effect import, `<kai-chat>` / `<Chat>` is an un-upgraded unknown element — an empty box. `customElements.get('kai-chat') === undefined`.",
-    fix: "Import the web-components bundle for its side effect BEFORE your first render — it must run before the component mounts.\n\n```tsx\nimport '@kitn.ai/ui/web-components'   // registers <kai-*> — REQUIRED, must come first\nimport { Chat } from '@kitn.ai/ui/react'\nimport '@kitn.ai/ui/theme.css'\n```\n\nIn plain HTML: `import '@kitn.ai/ui/web-components'` in your module script. The import is a side effect — keep it even if your linter flags it as \"unused\"."
+    fix: "Register the web components on the client BEFORE your first render: the import has to run before the component mounts. A scaffolded app takes the narrowest form that covers what it renders, ONE ENTRY PER TAG it places.\n\n```tsx\nimport '@kitn.ai/ui/web-components/chat';  // registers <kai-chat>, and kai-message rides in with it\nimport { Chat } from '@kitn.ai/ui/react'\nimport '@kitn.ai/ui/theme.css'\n```\n\nThe register-all barrel `import '@kitn.ai/ui/web-components'` is still the right form when you want every tag, and it is the SSR-import-safe default: a per-web-component entry is client-only, so an SSR entry point wants the single barrel line instead of one import per tag. It is also the barrel the imperative `toast()` helper is exported from.\n\nIn plain HTML: either form in your module script. The import is a side effect; keep it even if your linter flags it as \"unused\"."
   },
   {
     // Rule 7 — tsc errors inside node_modules/@kitn.ai/ui/src (SolidJS source pulled in)
@@ -194,6 +216,113 @@ const RULES = [
 function matchRules(text) {
   return RULES.filter((rule) => rule.test(text));
 }
+const tags = { "kai-conversations": "conversation-list", "kai-conversation-item": "conversation-item", "kai-prompt-input": "prompt-input", "kai-chat": "chat", "kai-workspace": "chat-workspace", "kai-thread": "thread", "kai-thinking-bar": "thinking-bar", "kai-model-switcher": "model-switcher", "kai-attachments": "attachments", "kai-message": "message", "kai-markdown": "markdown", "kai-code-block": "code-block", "kai-reasoning": "reasoning", "kai-tool": "tool", "kai-context": "context-meter", "kai-feedback-bar": "feedback-bar", "kai-scope-picker": "chat-scope-picker", "kai-suggestions": "prompt-suggestions", "kai-file-upload": "file-upload", "kai-voice-input": "voice-input", "kai-audio-visualizer": "audio-visualizer", "kai-loader": "loader", "kai-text-shimmer": "text-shimmer", "kai-image": "image", "kai-checkpoint": "checkpoint", "kai-skills": "message-skills", "kai-source": "source", "kai-sources": "source", "kai-response-stream": "response-stream", "kai-empty": "empty", "kai-status": "status", "kai-nav": "nav", "kai-progress-bar": "progress-bar", "kai-coachmark": "coachmark", "kai-tabs": "tabs", "kai-voice-output": "voice-output", "kai-screen": "screen", "kai-chain-of-thought": "chain-of-thought", "kai-resizable": "resizable", "kai-resizable-item": "resizable", "kai-file-tree": "file-tree", "kai-artifact": "artifact", "kai-scroll-button": "scroll-button", "kai-popover": "popover", "kai-switch": "switch", "kai-checkbox": "checkbox", "kai-checkbox-group": "checkbox-group", "kai-radio-group": "radio-group", "kai-slider": "slider", "kai-select": "select", "kai-button": "button", "kai-avatar": "avatar", "kai-badge": "badge", "kai-tooltip": "tooltip", "kai-notice": "notice", "kai-icon": "icon", "kai-separator": "separator", "kai-scroll-area": "scroll-area", "kai-hover-card": "hover-card", "kai-skeleton": "skeleton", "kai-toast-region": "toast", "kai-card": "card", "kai-form": "form", "kai-link-preview": "link-preview", "kai-embed": "embed", "kai-confirm": "confirm-card", "kai-tasks": "tasks", "kai-choice": "choice", "kai-cards": "cards", "kai-compare": "compare", "kai-composer": "composer", "kai-menu": "menu", "kai-dropdown": "dropdown", "kai-command": "command", "kai-prompt-dock": "prompt-dock", "kai-segmented": "segmented", "kai-settings-group": "settings-group", "kai-setting-item": "setting-item", "kai-pane": "pane", "kai-pane-group": "pane-group", "kai-pane-grid": "pane-grid", "kai-agent-card": "agent-card", "kai-dialog": "dialog", "kai-dock": "dock", "kai-input": "input", "kai-search": "search", "kai-kbd": "kbd", "kai-editable-label": "editable-label", "kai-panel": "panel", "kai-panel-header": "panel", "kai-tab-bar": "tab-bar", "kai-tab-bar-item": "tab-bar-item", "kai-view-stack": "view-stack", "kai-view": "view", "kai-row": "row", "kai-row-group": "row-group" };
+const WEB_COMPONENTS_ENTRY = "@kitn.ai/ui/web-components";
+function entryForTag(tag) {
+  return tags[tag];
+}
+const WORD = /[\w$]/;
+const PLACED_TAG = /<(kai-[a-z][a-z0-9-]*)/g;
+const CREATED_TAG = /\b(?:el|createElement)\s*\(\s*['"](kai-[a-z][a-z0-9-]*)['"]/g;
+const REGISTRATION_IMPORT = /(?:import\s*\(\s*|import(?!\s*type\b)\s*([^;'"]*?\bfrom\s*)?)['"]@kitn\.ai\/ui\/web-components(?:\/([a-z][a-z0-9-]*))?['"]/g;
+const SELF_DEFINE = /customElements\s*\.\s*define\s*\(\s*['"](kai-[a-z][a-z0-9-]*)['"]/g;
+function past(text, from, terminator) {
+  const at = text.indexOf(terminator, from);
+  return at === -1 ? text.length : at + terminator.length;
+}
+function stringEnd(text, open) {
+  const quote = text[open];
+  for (let i = open + 1; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === "\\") {
+      i += 1;
+      continue;
+    }
+    if (ch === quote) return i;
+    if (ch === "\n" && quote !== "`") return i;
+  }
+  return text.length;
+}
+function blank(text) {
+  const code = [];
+  const markup = [];
+  const put = (chunk, visibleInMarkup = true) => {
+    code.push(chunk);
+    markup.push(visibleInMarkup ? chunk : " ".repeat(chunk.length));
+  };
+  const blanked = (count) => put(" ".repeat(count));
+  let i = 0;
+  while (i < text.length) {
+    if (text.startsWith("<!--", i)) {
+      const end = past(text, i + 4, "-->");
+      blanked(end - i);
+      i = end;
+      continue;
+    }
+    if (text.startsWith("//", i) && text[i - 1] !== ":") {
+      const stop = text.indexOf("\n", i);
+      const end = stop === -1 ? text.length : stop;
+      blanked(end - i);
+      i = end;
+      continue;
+    }
+    if (text.startsWith("/*", i)) {
+      const end = past(text, i + 2, "*/");
+      blanked(end - i);
+      i = end;
+      continue;
+    }
+    const ch = text[i];
+    if ((ch === "'" || ch === '"' || ch === "`") && !WORD.test(text[i - 1] ?? " ")) {
+      const end = stringEnd(text, i);
+      put(ch);
+      put(text.slice(i + 1, end), false);
+      if (text[end] === ch) {
+        put(ch);
+        i = end + 1;
+      } else {
+        i = end;
+      }
+      continue;
+    }
+    put(ch);
+    i += 1;
+  }
+  return { code: code.join(""), markup: markup.join("") };
+}
+function sourceCode(text) {
+  return blank(text).code;
+}
+function unregisteredPlacedTags(files) {
+  const placed = /* @__PURE__ */ new Map();
+  const imported = /* @__PURE__ */ new Set();
+  const defined = /* @__PURE__ */ new Set();
+  let barrel = false;
+  const note = (tag, file) => {
+    const seen = placed.get(tag);
+    if (seen === void 0) placed.set(tag, [file]);
+    else if (!seen.includes(file)) seen.push(file);
+  };
+  for (const { file, text } of files) {
+    const { code, markup } = blank(text);
+    for (const match of markup.matchAll(PLACED_TAG)) note(match[1], file);
+    for (const match of code.matchAll(CREATED_TAG)) note(match[1], file);
+    for (const match of code.matchAll(REGISTRATION_IMPORT)) {
+      const entry = match[2];
+      if (entry === void 0) barrel = true;
+      else imported.add(entry);
+    }
+    for (const match of code.matchAll(SELF_DEFINE)) defined.add(match[1]);
+  }
+  if (barrel) return [];
+  const out = [];
+  for (const [tag, names] of placed) {
+    const entry = entryForTag(tag);
+    if (entry === void 0 || imported.has(entry) || defined.has(tag)) continue;
+    out.push({ tag, entry, files: names });
+  }
+  return out;
+}
 const KIT = "@kitn.ai/ui";
 const MCP = "@kitn.ai/mcp";
 const KAI_JSON = "kai.json";
@@ -377,7 +506,7 @@ Run \`kai upgrade\` to see what the template this CLI emits would change (it rep
     }
     const hitByRule = /* @__PURE__ */ new Map();
     for (const { file, text } of contents) {
-      for (const rule of matchRules(text)) {
+      for (const rule of matchRules(sourceCode(text))) {
         if (!hitByRule.has(rule.id)) hitByRule.set(rule.id, { rule, files: [] });
         hitByRule.get(rule.id).files.push(relative(input.cwd, file));
       }
@@ -392,6 +521,25 @@ Run \`kai upgrade\` to see what the template this CLI emits would change (it rep
 ${rule.fix}`
       });
     }
+    const unregistered = unregisteredPlacedTags(contents);
+    if (unregistered.length > 0) {
+      const shown = unregistered.slice(0, 3);
+      const lines = shown.map(({ tag, entry, files: placing }) => {
+        const where = placing.slice(0, 2).map((file) => relative(input.cwd, file)).join(", ");
+        const more = placing.length > 2 ? ` (+${placing.length - 2})` : "";
+        return `<${tag}> in ${where}${more} -> add: import '${WEB_COMPONENTS_ENTRY}/${entry}'`;
+      });
+      if (unregistered.length > shown.length) lines.push(`(and ${unregistered.length - shown.length} more)`);
+      lines.push(
+        `Per-web-component entries are client-only: on an SSR target, put the import inside \`if (typeof window !== 'undefined')\`.`,
+        `Importing the register-all barrel '${WEB_COMPONENTS_ENTRY}' instead is the SSR-import-safe form and registers every tag at once.`
+      );
+      findings.push({
+        severity: "warn",
+        title: `${unregistered.length} placed <kai-*> tag(s) have nothing registering them`,
+        detail: lines.join("\n")
+      });
+    }
     const styled = contents.some((c) => /theme\.tokens\.css|theme\.css|solid\.css/.test(c.text));
     if (files.length > 0 && !styled) {
       findings.push({
@@ -441,7 +589,7 @@ async function runDoctor(argv = [], io = {}) {
   const findings = diagnose({
     cwd: io.cwd ?? process.cwd(),
     cliVersion: cliVersion(),
-    builtAgainstKit: "0.35.0"
+    builtAgainstKit: "0.36.0"
   });
   const strict = argv.includes("--strict");
   if (argv.includes("--json")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "The kai command line for @kitn.ai/ui: scaffold a project or add a block to one, diagnose its wiring, and run the construct dev/eject/compile tooling.",
@@ -56,7 +56,7 @@
     "lint:cli-invocations": "node scripts/lint-cli-invocations.mjs --self-test && node scripts/lint-cli-invocations.mjs"
   },
   "dependencies": {
-    "create-kai": "^0.8.0",
+    "create-kai": "^0.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {