@cometchat/skills-cli 2.0.0 → 2.0.2

package/dist/index.js

@@ -170,9 +170,24 @@ function detectReactjs(root, deps) {
     bundler: isVite ? "vite" : isCra ? "webpack" : "vite",
     // default to vite for ambiguous
     ssr_strategy: "spa-no-ssr",
-    env_prefix: isVite ? "VITE_" : isCra ? "REACT_APP_" : "VITE_"
+    env_prefix: isVite ? "VITE_" : isCra ? "REACT_APP_" : "VITE_",
+    uses_jsx: detectUsesJsx(root)
   };
 }
+function detectUsesJsx(root) {
+  const indexHtml = readFileOrNull(p(root, "index.html"));
+  if (indexHtml) {
+    if (/src=["']\/?src\/main\.jsx["']/.test(indexHtml)) return true;
+    if (/src=["']\/?src\/main\.tsx["']/.test(indexHtml)) return false;
+  }
+  const hasJsxMain = pathExists(p(root, "src/main.jsx"));
+  const hasTsxMain = pathExists(p(root, "src/main.tsx"));
+  if (hasJsxMain && !hasTsxMain) return true;
+  const hasTsconfig = pathExists(p(root, "tsconfig.json"));
+  const hasJsxApp = pathExists(p(root, "src/App.jsx"));
+  if (!hasTsconfig && hasJsxApp) return true;
+  return false;
+}
 function detectFramework(root) {
   const pkg = readJsonOrNull(p(root, "package.json"));
   if (!pkg) return EMPTY;
@@ -500,6 +515,7 @@ async function runDetectors(root) {
     bundler: fw.bundler,
     ssr_strategy: fw.ssr_strategy,
     env_prefix: fw.env_prefix,
+    uses_jsx: fw.uses_jsx,
     package_manager,
     credentials,
     existing_integration,
@@ -536,6 +552,9 @@ function printHumanReadable(r) {
   if (r.ssr_strategy !== null) lines.push(`  SSR strategy:      ${r.ssr_strategy}`);
   if (r.env_prefix !== null) lines.push(`  Env var prefix:    ${r.env_prefix}`);
   if (r.package_manager !== null) lines.push(`  Package manager:   ${r.package_manager}`);
+  if (r.uses_jsx === true) {
+    lines.push(`  Source language:   JavaScript (.jsx) \u2014 \u26A0 apply will refuse, the v6 templates are TypeScript-only`);
+  }
   lines.push("");
   lines.push("  Credentials:");
   lines.push(`    Source:           ${r.credentials.source}`);
@@ -1350,6 +1369,128 @@ function checkOverwriteSafetyBatch(root, framework, filePaths) {
   return filePaths.map((p2) => checkOverwriteSafety(root, framework, p2));
 }
 
+// src/utils/env-file.ts
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join7 } from "node:path";
+var PLACEHOLDER_SENTINEL = "YOUR_";
+var PLACEHOLDER_SUFFIX = "_HERE";
+function envFileNameFor(framework) {
+  return framework === "nextjs" ? ".env.local" : ".env";
+}
+function placeholderFor(varName) {
+  let stripped = varName.replace(/^[A-Z]+_/, "");
+  stripped = stripped.replace(/^COMETCHAT_/, "");
+  return `${PLACEHOLDER_SENTINEL}${stripped}${PLACEHOLDER_SUFFIX}`;
+}
+function isPlaceholder(value) {
+  const trimmed = value.trim();
+  return trimmed.startsWith(PLACEHOLDER_SENTINEL) && trimmed.endsWith(PLACEHOLDER_SUFFIX);
+}
+function parseEnvKeys(content) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    if (key) keys.add(key);
+  }
+  return keys;
+}
+function parseEnvPairs(content) {
+  const pairs = /* @__PURE__ */ new Map();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    const commentIdx = value.indexOf("  #");
+    if (commentIdx !== -1) {
+      value = value.slice(0, commentIdx).trim();
+    }
+    if (key) pairs.set(key, value);
+  }
+  return pairs;
+}
+function writeEnvFile(args) {
+  const { projectRoot, framework, envVars } = args;
+  const fileName = envFileNameFor(framework);
+  const fullPath = join7(projectRoot, fileName);
+  let existing = "";
+  if (pathExists(fullPath)) {
+    try {
+      existing = readFileSync7(fullPath, "utf8");
+    } catch {
+      existing = "";
+    }
+  }
+  const presentKeys = parseEnvKeys(existing);
+  const toWrite = [];
+  const skipped = [];
+  for (const v of envVars) {
+    if (presentKeys.has(v.name)) {
+      skipped.push(v.name);
+      continue;
+    }
+    toWrite.push({ name: v.name, placeholder: placeholderFor(v.name) });
+  }
+  if (toWrite.length > 0) {
+    const lines = [];
+    if (existing.length > 0 && !existing.endsWith("\n")) lines.push("");
+    if (existing.length > 0) lines.push("");
+    lines.push("# CometChat \u2014 fill in real values from https://app.cometchat.com \u2192 Your App \u2192 API & Auth Keys");
+    for (const v of envVars) {
+      if (presentKeys.has(v.name)) continue;
+      const placeholder = placeholderFor(v.name);
+      const inlineComment = v.secret ? "  # secret \u2014 do not commit" : v.description ? `  # ${v.description}` : "";
+      lines.push(`${v.name}=${placeholder}${inlineComment}`);
+    }
+    lines.push("");
+    writeFileSync4(fullPath, existing + lines.join("\n"), "utf8");
+  }
+  const gitignoreUpdated = ensureEnvIgnored(projectRoot, fileName);
+  return {
+    path: fileName,
+    written: toWrite,
+    skipped,
+    gitignore_updated: gitignoreUpdated
+  };
+}
+function ensureEnvIgnored(projectRoot, envFileName) {
+  const gitignorePath = join7(projectRoot, ".gitignore");
+  let existing = "";
+  if (pathExists(gitignorePath)) {
+    try {
+      existing = readFileSync7(gitignorePath, "utf8");
+    } catch {
+      existing = "";
+    }
+  }
+  const lines = existing.split(/\r?\n/).map((l) => l.trim());
+  for (const line of lines) {
+    if (!line || line.startsWith("#")) continue;
+    if (line === envFileName) return false;
+    if (line === `/${envFileName}`) return false;
+    if (line === ".env*" || line === "/.env*") return false;
+    if (line === ".env*.local" && envFileName.endsWith(".local")) return false;
+    if (line === ".env" && envFileName === ".env") return false;
+  }
+  const block = [];
+  if (existing.length > 0 && !existing.endsWith("\n")) block.push("");
+  if (existing.length > 0) block.push("");
+  block.push("# CometChat \u2014 keep credentials out of source control");
+  block.push(envFileName);
+  block.push("");
+  writeFileSync4(gitignorePath, existing + block.join("\n"), "utf8");
+  return true;
+}
+
 // src/commands/apply.ts
 function isJsonMode4(args) {
   return args.flags.json === true || args.flags.json === "true";
@@ -1526,6 +1667,7 @@ async function apply(args) {
   let frameworkVersion = null;
   let credentialsSource = "none";
   let detectedRouter = null;
+  let usesJsx = false;
   if (!framework) {
     const detected = await runDetectors(root);
     if (detected.framework === null) {
@@ -1540,15 +1682,44 @@ async function apply(args) {
     frameworkVersion = detected.framework_version;
     credentialsSource = detected.credentials.source;
     detectedRouter = detected.router ?? null;
+    usesJsx = detected.uses_jsx === true;
   } else if (framework === "nextjs") {
     const detected = await runDetectors(root);
     detectedRouter = detected.router ?? null;
     if (!frameworkVersion) frameworkVersion = detected.framework_version;
     if (credentialsSource === "none") credentialsSource = detected.credentials.source;
+  } else if (framework === "reactjs") {
+    const detected = await runDetectors(root);
+    usesJsx = detected.uses_jsx === true;
+    if (!frameworkVersion) frameworkVersion = detected.framework_version;
+    if (credentialsSource === "none") credentialsSource = detected.credentials.source;
   }
   if (!envPrefix) {
     envPrefix = framework === "nextjs" ? "NEXT_PUBLIC_" : framework === "astro" ? "PUBLIC_" : "VITE_";
   }
+  if (framework === "reactjs" && usesJsx) {
+    return errorOut(
+      args,
+      [
+        "Error: This project uses JavaScript (.jsx) entry files. The CometChat React UI Kit v6 templates are TypeScript-only.",
+        "",
+        "Detected: src/main.jsx (or index.html references /src/main.jsx) and no tsconfig.json.",
+        "",
+        "Options:",
+        "  1. Recreate the project as TypeScript (recommended for new projects):",
+        "       npm create vite@latest my-react-app -- --template react-ts",
+        "  2. Convert this project to TypeScript first:",
+        "       - Add a tsconfig.json (see https://vite.dev/guide/features#typescript)",
+        "       - Rename src/main.jsx \u2192 src/main.tsx",
+        "       - Rename src/App.jsx \u2192 src/App.tsx",
+        "       - Update index.html to reference /src/main.tsx",
+        "     Then re-run `cometchat init`.",
+        "",
+        "JSX template variants ship in a future release. Tracking: v2.1."
+      ].join("\n"),
+      1
+    );
+  }
   let manifestKey = framework;
   if (framework === "nextjs" && detectedRouter === "pages") {
     manifestKey = "nextjs-pages";
@@ -1714,6 +1885,18 @@ async function apply(args) {
     state_file: ".cometchat/state.json",
     next_steps: (manifest.next_steps ?? []).map((s) => substitute(s, subs))
   };
+  if (manifest.env_vars.length > 0) {
+    result.env_file = writeEnvFile({
+      projectRoot: root,
+      framework,
+      envVars: result.env_vars_to_add.map((v) => ({
+        name: v.name,
+        required: v.required,
+        secret: v.secret,
+        description: manifest.env_vars.find((e) => substitute(e.name, subs) === v.name)?.description
+      }))
+    });
+  }
   if (embedPath !== null && entryPath !== null) {
     const embedHints = embedNextSteps(framework, embedPath);
     result.next_steps = [...embedHints, ...result.next_steps];
@@ -1840,12 +2023,24 @@ function printHumanReadable3(r) {
       lines.push("    (or pass --auto-install next time to do this automatically)");
     }
   }
-  if (r.env_vars_to_add.length > 0) {
+  if (r.env_file) {
     lines.push("");
-    lines.push("  Add these to your .env file:");
-    for (const e of r.env_vars_to_add) {
-      const tag = e.secret ? "  # secret \u2014 do not commit" : "";
-      lines.push(`    ${e.name}=YOUR_VALUE_HERE${tag}`);
+    if (r.env_file.written.length > 0) {
+      lines.push(
+        `  \u2713 Wrote ${r.env_file.written.length} placeholder env var(s) to ${r.env_file.path}`
+      );
+      lines.push(`    Open ${r.env_file.path} and replace the YOUR_*_HERE values:`);
+      for (const v of r.env_file.written) {
+        lines.push(`      ${v.name}=${v.placeholder}`);
+      }
+      lines.push(`    (get real values from https://app.cometchat.com \u2192 Your App \u2192 API & Auth Keys)`);
+    } else if (r.env_vars_to_add.length > 0) {
+      lines.push(
+        `  \u2713 All ${r.env_vars_to_add.length} env var(s) already present in ${r.env_file.path}`
+      );
+    }
+    if (r.env_file.gitignore_updated) {
+      lines.push(`    + Added ${r.env_file.path} to .gitignore`);
     }
   }
   lines.push("");
@@ -2127,7 +2322,7 @@ function printHumanReadable5(r) {
 
 // src/commands/uninstall.ts
 import { rmSync as rmSync2, statSync as statSync3, rmdirSync, readdirSync as readdirSync3 } from "node:fs";
-import { dirname as dirname5, join as join7, resolve as resolve7 } from "node:path";
+import { dirname as dirname5, join as join8, resolve as resolve7 } from "node:path";
 function isJsonMode7(args) {
   return args.flags.json === true || args.flags.json === "true";
 }
@@ -2188,7 +2383,7 @@ async function uninstall(args) {
   const skipped = [];
   const dirsToCheck = /* @__PURE__ */ new Set();
   for (const file of state.files_owned) {
-    const fullPath = join7(root, file);
+    const fullPath = join8(root, file);
     if (!pathExists(fullPath)) {
       skipped.push({ path: file, reason: "file not found" });
       continue;
@@ -2442,8 +2637,8 @@ function printHumanReadable7(r) {
 }
 
 // src/commands/production-auth.ts
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join8, resolve as resolve9 } from "node:path";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join9, resolve as resolve9 } from "node:path";
 function isJsonMode9(args) {
   return args.flags.json === true || args.flags.json === "true";
 }
@@ -2454,17 +2649,17 @@ function projectPath8(args) {
 }
 var SUPPORTED_FRAMEWORKS = /* @__PURE__ */ new Set(["nextjs", "react-router", "astro"]);
 function productionRoot() {
-  return join8(findRegistryRoot(), "v6", "production");
+  return join9(findRegistryRoot(), "v6", "production");
 }
 function loadProductionManifest(framework) {
   const root = productionRoot();
-  const manifestPath = join8(root, `${framework}.template.json`);
-  const content = readFileSync7(manifestPath, "utf8");
+  const manifestPath = join9(root, `${framework}.template.json`);
+  const content = readFileSync8(manifestPath, "utf8");
   return JSON.parse(content);
 }
 function readProductionTemplate(framework, ref) {
   const root = productionRoot();
-  return readFileSync7(join8(root, framework, ref), "utf8");
+  return readFileSync8(join9(root, framework, ref), "utf8");
 }
 function findClientLoginFile(state) {
   const candidates = [
@@ -2495,16 +2690,16 @@ ${indent}  .catch((e: unknown) => setError(String(e)));`
 function clientPatch(root, state) {
   const relPath = findClientLoginFile(state);
   if (relPath === null) return { status: "n/a" };
-  const fullPath = join8(root, relPath);
+  const fullPath = join9(root, relPath);
   let content;
   try {
-    content = readFileSync7(fullPath, "utf8");
+    content = readFileSync8(fullPath, "utf8");
   } catch {
     return { status: "skipped", file: relPath };
   }
   const next = rewriteLoginChain(content);
   if (next === null) return { status: "skipped", file: relPath };
-  writeFileSync4(fullPath, next, "utf8");
+  writeFileSync5(fullPath, next, "utf8");
   return { status: "applied", file: relPath, newChecksum: sha256(next) };
 }
 async function productionAuth(args) {
@@ -3041,19 +3236,19 @@ function printHumanReadable9(r) {
 }
 
 // src/commands/features.ts
-import { readFileSync as readFileSync8 } from "node:fs";
-import { join as join9 } from "node:path";
+import { readFileSync as readFileSync9 } from "node:fs";
+import { join as join10 } from "node:path";
 function isJsonMode11(args) {
   return args.flags.json === true || args.flags.json === "true";
 }
 function catalogPath() {
-  return join9(findRegistryRoot(), "v6", "features", "catalog.json");
+  return join10(findRegistryRoot(), "v6", "features", "catalog.json");
 }
 var cachedCatalog = null;
 function loadCatalog() {
   if (cachedCatalog) return cachedCatalog;
   const path = catalogPath();
-  cachedCatalog = JSON.parse(readFileSync8(path, "utf8"));
+  cachedCatalog = JSON.parse(readFileSync9(path, "utf8"));
   return cachedCatalog;
 }
 function nextStepsForFeature(feature) {
@@ -3066,6 +3261,7 @@ function nextStepsForFeature(feature) {
         ...feature.docs_topic ? [`For details, query the docs MCP for "${feature.docs_topic}" or visit https://www.cometchat.com/docs/ui-kit/react/${feature.docs_topic}`] : []
       ];
     case "dashboard-toggle": {
+      const docsUrl = feature.docs_topic ? `https://www.cometchat.com/docs/ui-kit/react/${feature.docs_topic}` : "https://www.cometchat.com/docs/ui-kit/react/extensions";
       const lines = [];
       if (feature.auto_wired_in_uikit) {
         lines.push(
@@ -3074,8 +3270,13 @@ function nextStepsForFeature(feature) {
           "Steps to enable:",
           `  1. Go to https://app.cometchat.com and select your app`,
           `  2. Navigate to: ${feature.dashboard_path ?? "Extensions \u2192 " + feature.name}`,
+          `     (this is a hint \u2014 if the dashboard UI has changed, see the canonical docs link below)`,
           `  3. Toggle the feature on (and configure any required values)`,
-          `  4. Refresh your dev server \u2014 no code changes required`
+          `  4. Refresh your dev server \u2014 no code changes required`,
+          "",
+          `  \u{1F4D6} Canonical docs (always-current \u2014 use this if the dashboard navigation above doesn't match what you see):`,
+          `     ${docsUrl}`,
+          `     For exact, up-to-date integration steps, query the cometchat-docs MCP for "${feature.id}".`
         );
       } else {
         lines.push(
@@ -3083,23 +3284,14 @@ function nextStepsForFeature(feature) {
           "",
           "Steps to enable:",
           `  1. Go to https://app.cometchat.com \u2192 ${feature.dashboard_path ?? "Extensions \u2192 " + feature.name}, toggle on`,
-          `  2. In your CometChat init (the file that calls UIKitSettingsBuilder), add the extension:`,
-          `       import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";`,
-          `       // Pseudocode \u2014 match your existing builder chain:`,
-          `       const settings = new UIKitSettingsBuilder()`,
-          `         .setAppId(APP_ID)`,
-          `         .setRegion(REGION)`,
-          `         .setAuthKey(AUTH_KEY)`,
-          `         .subscribePresenceForAllUsers()`,
-          `         .setExtensions([/* your extension instance here */])`,
-          `         .build();`,
-          `       CometChatUIKit.init(settings);`,
-          `  3. Restart your dev server`
+          `     (dashboard hint \u2014 see canonical docs link below if the navigation has changed)`,
+          `  2. Register the extension via UIKitSettingsBuilder.setExtensions([...]) in your CometChat init.`,
+          `     For the exact import path + extension class name + builder syntax, query the cometchat-docs MCP for "${feature.id}" \u2014 DO NOT invent the API from memory.`,
+          `  3. Restart your dev server`,
+          "",
+          `  \u{1F4D6} Canonical docs: ${docsUrl}`
         );
       }
-      if (feature.docs_topic) {
-        lines.push(`  Docs: https://www.cometchat.com/docs/ui-kit/react/${feature.docs_topic}`);
-      }
       return lines;
     }
     case "package-install":
@@ -3377,6 +3569,14 @@ function buildIssues(args) {
       fix: "Add the missing variables to your .env file. The chat will fail to initialize without them."
     });
   }
+  if (args.envPlaceholder.length > 0) {
+    issues.push({
+      severity: "warning",
+      code: "env-placeholder",
+      message: `${args.envPlaceholder.length} env var(s) still contain YOUR_*_HERE placeholders: ${args.envPlaceholder.join(", ")}`,
+      fix: `Open ${args.envFilePath ?? ".env"} and replace each YOUR_*_HERE value with the real one from https://app.cometchat.com \u2192 Your App \u2192 API & Auth Keys. Without this, the chat will fail to initialize at runtime.`
+    });
+  }
   return issues;
 }
 async function doctor(args) {
@@ -3419,17 +3619,34 @@ async function doctor(args) {
   } else if (expectedEnvVars[2]) {
     envMissing.push(expectedEnvVars[2]);
   }
+  const envFileName = stateInfo ? envFileNameFor(stateInfo.framework) : detected.framework ? envFileNameFor(detected.framework) : null;
+  const envFilePath = envFileName && pathExists(p(root, envFileName)) ? envFileName : null;
+  const envPlaceholder = [];
+  if (envFilePath) {
+    const content = readFileOrNull(p(root, envFilePath));
+    if (content) {
+      const pairs = parseEnvPairs(content);
+      for (const expected of expectedEnvVars) {
+        const value = pairs.get(expected);
+        if (value !== void 0 && isPlaceholder(value)) {
+          envPlaceholder.push(expected);
+        }
+      }
+    }
+  }
   const issues = buildIssues({
     drift,
     verify: verifyResult,
     envMissing,
+    envPlaceholder,
+    envFilePath,
     hasIntegration: stateInfo !== null
   });
   const errorCount = issues.filter((i) => i.severity === "error").length;
   const warnCount = issues.filter((i) => i.severity === "warning").length;
-  const status = errorCount > 0 ? "issues" : warnCount > 0 ? "warnings" : "healthy";
+  const status2 = errorCount > 0 ? "issues" : warnCount > 0 ? "warnings" : "healthy";
   const result = {
-    status,
+    status: status2,
     detect: {
       framework: detected.framework,
       framework_version: detected.framework_version,
@@ -3453,17 +3670,19 @@ async function doctor(args) {
     },
     environment: {
       env_vars_present: envPresent.filter(Boolean),
-      env_vars_missing: envMissing
+      env_vars_missing: envMissing,
+      env_vars_placeholder: envPlaceholder,
+      env_file_path: envFilePath
     },
     issues,
-    summary: buildSummary(status, errorCount, warnCount, stateInfo !== null)
+    summary: buildSummary(status2, errorCount, warnCount, stateInfo !== null)
   };
   return outputResult7(args, result, errorCount > 0 ? 1 : 0);
 }
-function buildSummary(status, errors, warnings, integrated) {
+function buildSummary(status2, errors, warnings, integrated) {
   if (!integrated) return "No CometChat integration found. Run `cometchat apply` to get started.";
-  if (status === "healthy") return "\u2713 All checks pass. Integration is healthy.";
-  if (status === "warnings") return `\u26A0 ${warnings} warning(s) found. Integration works but has minor issues.`;
+  if (status2 === "healthy") return "\u2713 All checks pass. Integration is healthy.";
+  if (status2 === "warnings") return `\u26A0 ${warnings} warning(s) found. Integration works but has minor issues.`;
   return `\u2717 ${errors} error(s) and ${warnings} warning(s) found. Integration may not work correctly.`;
 }
 function outputResult7(args, result, exitCode) {
@@ -3636,13 +3855,10 @@ async function init(args) {
       `Run \`cometchat install\` (or pass --install next time) to install ${applyResult.deps_to_install.length} npm package(s).`
     );
   }
-  try {
-    const manifest = loadManifest(6, detected.framework, parseInt(experienceArg, 10));
-    if (manifest.env_vars.length > 0) {
-      const envNames = manifest.env_vars.map((v) => v.name.replace("{{ENV_PREFIX}}", detected.env_prefix ?? "")).join(", ");
-      result.next_actions.unshift(`Add these env vars to .env: ${envNames}`);
-    }
-  } catch {
+  if (applyResult.env_file && applyResult.env_file.written.length > 0) {
+    result.next_actions.unshift(
+      `Open ${applyResult.env_file.path} and replace ${applyResult.env_file.written.length} YOUR_*_HERE placeholder(s) with real values from https://app.cometchat.com \u2192 Your App \u2192 API & Auth Keys.`
+    );
   }
   return outputResult8(args, result, 0);
 }
@@ -3685,8 +3901,8 @@ function printHumanReadable11(r) {
 }
 
 // src/commands/add-widget.ts
-import { readFileSync as readFileSync9 } from "node:fs";
-import { join as join10, resolve as resolve13 } from "node:path";
+import { readFileSync as readFileSync10 } from "node:fs";
+import { join as join11, resolve as resolve13 } from "node:path";
 var SUPPORTED = /* @__PURE__ */ new Set(["reactjs", "nextjs", "react-router", "astro"]);
 function isJsonMode14(args) {
   return args.flags.json === true || args.flags.json === "true";
@@ -3697,16 +3913,16 @@ function projectPath12(args) {
   return resolve13(process.cwd());
 }
 function widgetRoot() {
-  return join10(findRegistryRoot(), "v6", "widget");
+  return join11(findRegistryRoot(), "v6", "widget");
 }
 function loadWidgetManifest(framework) {
   const root = widgetRoot();
-  const path = join10(root, `${framework}.template.json`);
-  return JSON.parse(readFileSync9(path, "utf8"));
+  const path = join11(root, `${framework}.template.json`);
+  return JSON.parse(readFileSync10(path, "utf8"));
 }
 function readWidgetTemplate(framework, ref) {
   const root = widgetRoot();
-  return readFileSync9(join10(root, framework, ref), "utf8");
+  return readFileSync10(join11(root, framework, ref), "utf8");
 }
 async function addWidget(args) {
   const root = projectPath12(args);
@@ -3840,8 +4056,8 @@ function printHumanReadable12(r) {
 }
 
 // src/commands/add-user-mgmt.ts
-import { readFileSync as readFileSync10 } from "node:fs";
-import { join as join11, resolve as resolve14 } from "node:path";
+import { readFileSync as readFileSync11 } from "node:fs";
+import { join as join12, resolve as resolve14 } from "node:path";
 var SUPPORTED2 = /* @__PURE__ */ new Set(["nextjs", "react-router", "astro"]);
 function isJsonMode15(args) {
   return args.flags.json === true || args.flags.json === "true";
@@ -3852,15 +4068,15 @@ function projectPath13(args) {
   return resolve14(process.cwd());
 }
 function userMgmtRoot() {
-  return join11(findRegistryRoot(), "v6", "user-mgmt");
+  return join12(findRegistryRoot(), "v6", "user-mgmt");
 }
 function loadManifest2(framework) {
   const root = userMgmtRoot();
-  return JSON.parse(readFileSync10(join11(root, `${framework}.template.json`), "utf8"));
+  return JSON.parse(readFileSync11(join12(root, `${framework}.template.json`), "utf8"));
 }
 function readTemplate(framework, ref) {
   const root = userMgmtRoot();
-  return readFileSync10(join11(root, framework, ref), "utf8");
+  return readFileSync11(join12(root, framework, ref), "utf8");
 }
 async function addUserMgmt(args) {
   const root = projectPath13(args);
@@ -4017,8 +4233,8 @@ function printHumanReadable13(r) {
 }
 
 // src/commands/apply-feature.ts
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join12, resolve as resolve15 } from "node:path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync6 } from "node:fs";
+import { join as join13, resolve as resolve15 } from "node:path";
 function isJsonMode16(args) {
   return args.flags.json === true || args.flags.json === "true";
 }
@@ -4028,10 +4244,10 @@ function projectPath14(args) {
   return resolve15(process.cwd());
 }
 function catalogPath2() {
-  return join12(findRegistryRoot(), "v6", "features", "catalog.json");
+  return join13(findRegistryRoot(), "v6", "features", "catalog.json");
 }
 function loadCatalog2() {
-  return JSON.parse(readFileSync11(catalogPath2(), "utf8"));
+  return JSON.parse(readFileSync12(catalogPath2(), "utf8"));
 }
 function swapIdentifier(content, from, to) {
   const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -4107,16 +4323,16 @@ async function applyFeature(args) {
   const modified = [];
   let totalReplacements = 0;
   for (const relPath of state.files_owned) {
-    const fullPath = join12(root, relPath);
+    const fullPath = join13(root, relPath);
     let content;
     try {
-      content = readFileSync11(fullPath, "utf8");
+      content = readFileSync12(fullPath, "utf8");
     } catch {
       continue;
     }
     const [next, count] = swapIdentifier(content, feature.swap_from, feature.swap_to);
     if (count > 0) {
-      writeFileSync5(fullPath, next, "utf8");
+      writeFileSync6(fullPath, next, "utf8");
       newChecksums[relPath] = sha256(next);
       modified.push(relPath);
       totalReplacements += count;
@@ -4188,6 +4404,295 @@ function printHumanReadable14(r) {
   console.log(lines.join("\n"));
 }
 
+// src/commands/status.ts
+import { readFileSync as readFileSync13 } from "node:fs";
+import { resolve as resolve16 } from "node:path";
+function isJsonMode17(args) {
+  return args.flags.json === true || args.flags.json === "true";
+}
+function projectPath15(args) {
+  const fromFlag = args.flags.path;
+  if (typeof fromFlag === "string") return resolve16(fromFlag);
+  return resolve16(process.cwd());
+}
+function widgetMarkerPath(state) {
+  switch (state.framework) {
+    case "nextjs":
+      return state.router === "pages" ? "src/cometchat/CometChatWidget.tsx" : "src/app/cometchat/CometChatWidget.tsx";
+    case "react-router":
+      return "app/cometchat/CometChatWidget.tsx";
+    case "astro":
+      return "src/cometchat/CometChatWidget.tsx";
+    default:
+      return "src/cometchat/CometChatWidget.tsx";
+  }
+}
+function productionAuthMarkerPath(state) {
+  switch (state.framework) {
+    case "nextjs":
+      return state.router === "pages" ? "src/pages/api/cometchat-token.ts" : "src/app/api/cometchat-token/route.ts";
+    case "react-router":
+      return "app/routes/api.cometchat-token.ts";
+    case "astro":
+      return "src/pages/api/cometchat-token.ts";
+    default:
+      return "";
+  }
+}
+function userMgmtMarkerPath(state) {
+  switch (state.framework) {
+    case "nextjs":
+      return state.router === "pages" ? "src/pages/api/cometchat-user.ts" : "src/app/api/cometchat-user/route.ts";
+    case "react-router":
+      return "app/routes/api.cometchat-user.ts";
+    case "astro":
+      return "src/pages/api/cometchat-user.ts";
+    default:
+      return "";
+  }
+}
+function themeFilePath(state) {
+  switch (state.framework) {
+    case "nextjs":
+      return state.router === "pages" ? "src/styles/globals.css" : "src/app/globals.css";
+    case "react-router":
+      return "app/app.css";
+    case "astro":
+      return "src/cometchat/ChatApp.tsx";
+    // theme block lives inside the React island
+    default:
+      return "src/index.css";
+  }
+}
+function fileContains(root, relPath, marker) {
+  const fullPath = p(root, relPath);
+  if (!pathExists(fullPath)) return false;
+  try {
+    const content = readFileSync13(fullPath, "utf8");
+    return content.includes(marker);
+  } catch {
+    return false;
+  }
+}
+function countAuditEntries(root) {
+  const path = p(root, AUDIT_LOG_PATH);
+  if (!pathExists(path)) return 0;
+  try {
+    const content = readFileSync13(path, "utf8");
+    const matches = content.match(/^## \d{4}-\d{2}-\d{2}T/gm);
+    return matches ? matches.length : 0;
+  } catch {
+    return 0;
+  }
+}
+async function status(args) {
+  const root = projectPath15(args);
+  if (!hasState(root)) {
+    const result2 = {
+      integrated: false,
+      items: [],
+      audit_log_entries: 0,
+      audit_log_path: null,
+      files_owned_count: 0,
+      drift_count: 0,
+      next_suggested: "Run `cometchat init` to scaffold a CometChat integration in this project."
+    };
+    return outputResult12(args, result2, 0);
+  }
+  const state = readState(root);
+  if (!state) {
+    const result2 = {
+      integrated: false,
+      items: [],
+      audit_log_entries: 0,
+      audit_log_path: null,
+      files_owned_count: 0,
+      drift_count: 0,
+      next_suggested: "Could not parse .cometchat/state.json \u2014 schema mismatch?"
+    };
+    return outputResult12(args, result2, 1);
+  }
+  const items = [];
+  items.push({
+    step: 2,
+    state: "done",
+    label: "Base integration",
+    detail: `experience ${state.experience} (${state.experience_slug}) on ${state.framework}${state.router ? ` (${state.router} router)` : ""}`
+  });
+  for (const feature of state.applied_features ?? []) {
+    items.push({
+      step: 4,
+      state: "done",
+      label: "Feature applied",
+      detail: feature
+    });
+  }
+  const widgetPath = widgetMarkerPath(state);
+  if (widgetPath && pathExists(p(root, widgetPath))) {
+    items.push({
+      step: 4,
+      state: "done",
+      label: "Floating chat widget",
+      detail: widgetPath
+    });
+  } else {
+    items.push({
+      step: 4,
+      state: "todo",
+      label: "Floating chat widget",
+      detail: "not added",
+      next_command: "cometchat add-widget"
+    });
+  }
+  const userMgmtPath = userMgmtMarkerPath(state);
+  if (state.framework === "reactjs") {
+    items.push({
+      step: 4,
+      state: "skipped",
+      label: "Server user management",
+      detail: "reactjs has no built-in server (BYO backend)"
+    });
+  } else if (userMgmtPath && pathExists(p(root, userMgmtPath))) {
+    items.push({
+      step: 4,
+      state: "done",
+      label: "Server user management",
+      detail: userMgmtPath
+    });
+  } else {
+    items.push({
+      step: 4,
+      state: "todo",
+      label: "Server user management",
+      detail: "no /api/cometchat-user endpoint",
+      next_command: "cometchat add-user-mgmt"
+    });
+  }
+  const prodAuthPath = productionAuthMarkerPath(state);
+  if (state.framework === "reactjs") {
+    items.push({
+      step: 5,
+      state: "skipped",
+      label: "Production auth",
+      detail: "reactjs has no built-in server (BYO backend)"
+    });
+  } else if (state.credentials_source === "token-endpoint" || prodAuthPath && pathExists(p(root, prodAuthPath))) {
+    items.push({
+      step: 5,
+      state: "done",
+      label: "Production auth",
+      detail: prodAuthPath || "server-side token endpoint"
+    });
+  } else {
+    items.push({
+      step: 5,
+      state: "todo",
+      label: "Production auth",
+      detail: "still on dev Auth Key (insecure for prod)",
+      next_command: "cometchat production-auth"
+    });
+  }
+  const drift = detectDrift(root, state);
+  const customizationCount = drift.modified_files.length;
+  items.push({
+    step: 5,
+    state: customizationCount > 0 ? "done" : "todo",
+    label: "Customizations",
+    detail: customizationCount > 0 ? `${customizationCount} file modification(s) outside templates` : "0 modifications (still on default templates)",
+    next_command: customizationCount > 0 ? void 0 : void 0
+  });
+  const themePath = themeFilePath(state);
+  if (themePath && fileContains(root, themePath, "CometChat theme overrides")) {
+    items.push({
+      step: 7,
+      state: "done",
+      label: "Theme",
+      detail: `applied to ${themePath}`
+    });
+  } else {
+    items.push({
+      step: 7,
+      state: "todo",
+      label: "Theme",
+      detail: "no overrides applied (still on UI Kit defaults)",
+      next_command: "cometchat apply-theme --preset slack"
+    });
+  }
+  let nextSuggested;
+  const todoItems = items.filter((i) => i.state === "todo" && i.next_command);
+  const prodAuthTodo = todoItems.find((i) => i.label === "Production auth");
+  const widgetTodo = todoItems.find((i) => i.label === "Floating chat widget");
+  const themeTodo = todoItems.find((i) => i.label === "Theme");
+  if (prodAuthTodo) {
+    nextSuggested = `Run \`${prodAuthTodo.next_command}\` before deploying to production \u2014 your dev Auth Key is currently exposed to the browser.`;
+  } else if (themeTodo) {
+    nextSuggested = `Run \`${themeTodo.next_command}\` to brand the chat UI (or pick a different preset: whatsapp, imessage, discord, notion).`;
+  } else if (widgetTodo) {
+    nextSuggested = `Run \`${widgetTodo.next_command}\` to add a floating chat overlay.`;
+  } else if (todoItems.length === 0) {
+    nextSuggested = "Looks complete! Run `cometchat verify` for a final correctness check.";
+  } else {
+    nextSuggested = `Run \`/cometchat\` to open the iteration menu and pick what's next.`;
+  }
+  const result = {
+    integrated: true,
+    framework: state.framework,
+    framework_version: state.framework_version,
+    experience: state.experience,
+    experience_slug: state.experience_slug,
+    router: state.router,
+    items,
+    audit_log_entries: countAuditEntries(root),
+    audit_log_path: pathExists(p(root, AUDIT_LOG_PATH)) ? AUDIT_LOG_PATH : null,
+    files_owned_count: state.files_owned.length,
+    drift_count: drift.modified_files.length,
+    next_suggested: nextSuggested
+  };
+  return outputResult12(args, result, 0);
+}
+function outputResult12(args, result, exitCode) {
+  if (isJsonMode17(args)) {
+    console.log(JSON.stringify(result, null, 2));
+    return exitCode;
+  }
+  printHumanReadable15(result);
+  return exitCode;
+}
+function printHumanReadable15(r) {
+  const lines = [];
+  lines.push("");
+  if (!r.integrated) {
+    lines.push("  CometChat React integration \u2014 not yet started");
+    lines.push("");
+    if (r.next_suggested) lines.push(`  \u2192 ${r.next_suggested}`);
+    lines.push("");
+    console.log(lines.join("\n"));
+    return;
+  }
+  lines.push(`  CometChat React integration \u2014 your progress`);
+  lines.push("");
+  for (const item of r.items) {
+    const icon = item.state === "done" ? "\u2713" : item.state === "skipped" ? "\u2014" : "\u25CB";
+    const stepCol = `Step ${item.step}:`.padEnd(8);
+    const labelCol = item.label.padEnd(28);
+    const detail = item.detail ? `  (${item.detail})` : "";
+    lines.push(`  ${icon} ${stepCol} ${labelCol}${detail}`);
+  }
+  lines.push("");
+  lines.push(
+    `  Audit log:    ${r.audit_log_path ?? "none"}` + (r.audit_log_path ? `  (${r.audit_log_entries} entr${r.audit_log_entries === 1 ? "y" : "ies"})` : "")
+  );
+  lines.push(`  Files owned:  ${r.files_owned_count}`);
+  lines.push(`  Drift:        ${r.drift_count > 0 ? `${r.drift_count} customized file(s)` : "none"}`);
+  if (r.next_suggested) {
+    lines.push("");
+    lines.push("  Next suggested step:");
+    lines.push(`  \u2192 ${r.next_suggested}`);
+  }
+  lines.push("");
+  console.log(lines.join("\n"));
+}
+
 // src/index.ts
 var VERSION = "0.0.1";
 var HELP = `
@@ -4273,6 +4778,12 @@ Commands:
                              for production sign-up flows. Currently nextjs,
                              react-router, and astro.
 
+  status                     Journey-shaped progress summary. Aggregates state +
+                             applied_features + file markers into a checklist
+                             that mirrors the React UI Kit Integration Journey
+                             (base, features, widget, prod-auth, theme, etc.)
+                             and suggests the highest-leverage next action.
+
   apply-feature <id>         Apply a component-swap feature on top of the
                              current integration (e.g.
                              \`apply-feature rich-text-formatting\` swaps
@@ -4373,6 +4884,8 @@ async function run(argv) {
       return addUserMgmt(args);
     case "apply-feature":
       return applyFeature(args);
+    case "status":
+      return status(args);
     default:
       console.error(`Unknown command: ${args.command}`);
       console.error("Run `cometchat --help` for usage.");

package/dist/registry/v6/features/catalog.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "version": "1.0.0",
   "sdk_compatibility": ">=6.0.0 <7.0.0",
-  "description": "Catalog of CometChat features available in the React UI Kit. Categorized by what work is needed to enable each one.",
+  "description": "Catalog of CometChat features available in the React UI Kit. Categorized by what work is needed to enable each one. NOTE: this catalog stores OUR taxonomy (default vs dashboard-toggle vs package-install vs component-swap) plus a `dashboard_path` HINT for navigation. The hint is short and intentionally fragile — the canonical source is always the docs URL constructed from `docs_topic`. Agents must query the cometchat-docs MCP at runtime for current dashboard navigation, prop signatures, builder methods, and SDK reference. This catalog is for routing, not for SDK reference.",
   "feature_types": {
     "default": "Already enabled by default in the UI Kit components your integration uses. Zero code changes needed — the skill just shows you which component renders it.",
     "dashboard-toggle": "Requires flipping a toggle in the CometChat Dashboard at https://app.cometchat.com. Some have their UI decorator auto-attached by the UI Kit (auto_wired_in_uikit: true) — the dashboard flip is the only thing needed. Others additionally require passing the extension to UIKitSettingsBuilder.setExtensions([...]) before init.",

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@cometchat/skills-cli",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "CLI for the CometChat skills v2 architecture — detect, view, apply, verify CometChat integrations in React projects.",
   "type": "module",
   "license": "MIT",
   "bin": {
-    "cometchat": "./bin/cometchat.mjs"
+    "cometchat": "bin/cometchat.mjs"
   },
   "files": [
     "bin/",