@cometchat/skills 4.4.1 → 5.0.0

package/test-suite/scripts/build-registry.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * build-registry.mjs — generate the pack's "materials index", one registry per family.
+ *
+ * NOTHING is hardcoded per framework. The family list, its catalog, its oracles and
+ * which skills belong to it all come from the reviewer's families.json — the same
+ * single source the reviewer tools read. Adding a family there is enough; this script
+ * needs no edit.
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const CHECK = process.argv.includes("--check");
+const famArg = (() => { const i = process.argv.indexOf("--family"); return i >= 0 ? process.argv[i + 1] : null; })();
+const readJSON = (p) => JSON.parse(readFileSync(p, "utf8"));
+
+const FAMILIES = join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json");
+// families.json lives under .claude/, which package.json `files` does NOT ship — only
+// `.claude-plugin` and `peers.yaml` do. The registries themselves ARE shipped, pre-built, so a
+// consumer never needs to regenerate them; this is a dev-only tool. Exiting 2 there turned a
+// non-task into a hard failure for anyone who ran `npm run verify` from an installed package.
+// Degrade to a no-op with a clear reason instead.
+if (!existsSync(FAMILIES)) {
+  console.log("✅ build-registry: skipped — families.json is not present (dev-only tool; the shipped registries are pre-built).");
+  process.exit(0);
+}
+const { families } = readJSON(FAMILIES);
+
+const y = readFileSync(join(ROOT, "peers.yaml"), "utf8");
+const entry = (y.match(/^entry:\s*(\S+)/m) || [])[1] || "cometchat";
+const blocks = y.split(/^\s*-\s*platform:/m).slice(1).map((b) => "platform:" + b);
+
+// Every skill dir once; each family selects its own by the prefixes families.json declares.
+const skillsDir = join(ROOT, "skills");
+const allSkills = readdirSync(skillsDir, { withFileTypes: true })
+  .filter((d) => d.isDirectory()).map((d) => d.name)
+  .filter((name) => existsSync(join(skillsDir, name, "SKILL.md")))
+  .map((name) => {
+    const b = (readFileSync(join(skillsDir, name, "SKILL.md"), "utf8").match(/^---\n([\s\S]*?)\n---/) || [])[1] || "";
+    return { name, version: (b.match(/^\s+version:\s*"?([^"\n]+)"?/m) || [])[1] || null, role: name === entry ? "router" : "skill" };
+  });
+
+// Every platform-specific prefix any family declares — anything matching none of these is shared.
+const PLATFORM_PREFIXES = [...new Set(
+  Object.values(families).flatMap((f) => (f.reviewsSkills || []).filter((p) => p.endsWith("-"))),
+)];
+
+let stale = 0, wrote = 0, skipped = [];
+for (const [key, fam] of Object.entries(families)) {
+  if (/^template\b/i.test(fam._status || "")) { skipped.push(`${key} (template)`); continue; }
+
+  // registry name == catalog basename, so web-v7.json keeps its existing filename
+  const name = basename(fam.catalog || "", ".json");
+  const catalogPath = `test-suite/catalogs/${name}.json`;
+  if (!name || !existsSync(join(ROOT, catalogPath))) { skipped.push(`${key} (no catalog)`); continue; }
+
+  // peers block: match on this family's kit package, with the trailing @ so
+  // "@cometchat/chat-uikit-react" cannot swallow "@cometchat/chat-uikit-react-native"
+  const block = blocks.find((b) => b.includes(`kit_package: "${fam.kitPackage}@`)) || "";
+  const grab = (re) => (block.match(re) || [])[1];
+
+  // Legacy unsuffixed filenames are declared per-family in families.json, not guessed here.
+  const featPath = fam.features || `features.${name}.json`;
+  const conPath = fam.contracts || `contracts.${name}.json`;
+  const features = existsSync(join(ROOT, featPath)) ? readJSON(join(ROOT, featPath)) : null;
+  const contracts = existsSync(join(ROOT, conPath)) ? readJSON(join(ROOT, conPath)) : null;
+  const catalog = readJSON(join(ROOT, catalogPath));
+
+  // A skill carrying no platform prefix at all (the `cometchat` router, `cometchat-onboarding`)
+  // is SHARED and ships with every family. reviewsSkills is a *review* scope and cannot be
+  // reused as the ship list — it deliberately omits skills that emit no reviewable surface.
+  const prefixes = fam.reviewsSkills || [];
+  const skills = allSkills.filter(({ name: s }) =>
+    !PLATFORM_PREFIXES.some((p) => s.startsWith(p)) ||
+    prefixes.some((p) => (p.endsWith("-") ? s.startsWith(p) : s === p)));
+
+  const registry = {
+    family: name,
+    entry,
+    kit_package: grab(/kit_package:\s*"([^"]+)"/),
+    sdk_package: grab(/sdk_package:\s*"([^"]+)"/),
+    verified: /verified:\s*true/.test(block),
+    materials: {
+      catalog: { path: catalogPath, symbolCount: catalog.symbolCount, mode: catalog.mode },
+      features: { path: featPath, count: new Set((features?.features || []).map((f) => f.id).filter(Boolean)).size },
+      contracts: {
+        path: conPath,
+        count: Array.isArray(contracts?.contracts) ? contracts.contracts.length : Object.keys(contracts?.contracts || {}).length,
+      },
+    },
+    skills,
+  };
+
+  const outPath = join(ROOT, "registry", `${name}.json`);
+  const next = JSON.stringify(registry, null, 2) + "\n";
+  if (CHECK) {
+    if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : "") !== next) {
+      console.log(`❌ registry/${name}.json is stale — run: node test-suite/scripts/build-registry.mjs`); stale++;
+    }
+    continue;
+  }
+  mkdirSync(join(ROOT, "registry"), { recursive: true });
+  writeFileSync(outPath, next);
+  console.log(`✅ wrote registry/${name}.json — ${skills.length} skill(s), ${catalog.symbolCount} symbols, ${registry.materials.features.count} features, ${registry.materials.contracts.count} contracts.`);
+  wrote++;
+}
+
+if (skipped.length) console.log(`   skipped: ${skipped.join(", ")}`);
+if (CHECK) { if (stale) process.exit(1); console.log(`✅ all ${Object.keys(families).length - skipped.length - 1} registry file(s) up to date.`); process.exit(0); }
+// A family list that yields nothing means the discovery broke — never report green over zero.
+if (!wrote) { console.log("❌ build-registry: no families produced a registry — check families.json / catalog paths"); process.exit(2); }

package/test-suite/scripts/catalog-refresh-dart.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * catalog-refresh-dart.mjs — re-derive the flutter-v6 Tier-1 oracle from the pinned kit.
+ *
+ * The Dart sibling of catalog-refresh.mjs. It exists because the Flutter catalog is
+ * COMPILER-VERIFIED, not parsed: a declaration scan is wrong in both directions on this
+ * kit (it counts internals that are never exported, and misses the entire Chat SDK
+ * surface that the barrels re-export via `export 'package:...'`). So this script uses
+ * the scan only to propose CANDIDATES, then asks the Dart analyzer which of them
+ * actually resolve from each barrel. The analyzer's verdict is the oracle.
+ *
+ * It also records WHICH barrel each symbol comes from. That is not cosmetic: the calls
+ * widgets resolve only from cometchat_calls_uikit.dart, and a skill that imports the
+ * chat barrel and emits CometChatIncomingCall fails to compile.
+ *
+ * Usage:
+ *   node test-suite/scripts/catalog-refresh-dart.mjs            # rewrite the catalog
+ *   node test-suite/scripts/catalog-refresh-dart.mjs --check    # CI: fail on drift
+ * Requires the pinned project resolved (npm run verify:fences:flutter-v6:setup).
+ * Exit: 0 clean/written · 1 drift (--check) · 2 project not installed.
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_FAMILY, CATALOG_KEY, TYPECHECK_PROJECT, PROP_TABLES_DIR } from "./_dart-family.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PROJECT = TYPECHECK_PROJECT;
+const OUT = join(ROOT, "test-suite", "catalogs", "flutter-v6.json");
+const CHECK = process.argv.includes("--check");
+
+const CHAT_BARREL = "package:cometchat_chat_uikit/cometchat_chat_uikit.dart";
+const CALLS_BARREL = "package:cometchat_chat_uikit/cometchat_calls_uikit.dart";
+
+const cfgPath = join(PROJECT, ".dart_tool", "package_config.json");
+if (!existsSync(cfgPath)) {
+  console.error(`ERROR: pinned kit not installed.\n       Run: npm run verify:fences:flutter-v6:setup`);
+  process.exit(2);
+}
+const pkgCfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+const pkg = (name) => pkgCfg.packages.find((p) => p.name === name);
+const kit = pkg("cometchat_chat_uikit");
+if (!kit) { console.error("ERROR: cometchat_chat_uikit not in package_config.json"); process.exit(2); }
+const kitLib = new URL(kit.rootUri.endsWith("/") ? kit.rootUri + "lib/" : kit.rootUri + "/lib/", `file://${cfgPath}`).pathname;
+const kitVersion = (kit.rootUri.match(/cometchat_chat_uikit-([0-9][^/]*)/) || [])[1] || "unknown";
+const versionOf = (n) => (pkg(n)?.rootUri.match(new RegExp(`${n}-([0-9][^/]*)`)) || [])[1] || "unknown";
+
+// ── 1. CANDIDATES: every CometChat*-prefixed declaration anywhere in the kit, plus the
+// re-exported SDK packages. Over-inclusive on purpose — the analyzer prunes it.
+const DECL_RE = /(?:^|[\s;{])(?:abstract\s+|base\s+|final\s+|sealed\s+|interface\s+)*(?:class|mixin|enum|typedef|extension)\s+(CometChat[A-Za-z0-9_]*)/g;
+const candidates = new Set();
+const walk = (dir) => {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p);
+    else if (e.name.endsWith(".dart")) {
+      for (const m of readFileSync(p, "utf8").matchAll(DECL_RE)) candidates.add(m[1]);
+    }
+  }
+};
+walk(kitLib);
+for (const dep of ["cometchat_sdk", "cometchat_calls_sdk", "cometchat_cards"]) {
+  const d = pkg(dep);
+  if (!d) continue;
+  const lib = new URL(d.rootUri.endsWith("/") ? d.rootUri + "lib/" : d.rootUri + "/lib/", `file://${cfgPath}`).pathname;
+  if (existsSync(lib)) walk(lib);
+}
+const cands = [...candidates].sort();
+console.log(`candidates: ${cands.length} CometChat* declaration(s) across the kit + re-exported SDKs`);
+
+// ── 2. VERIFY: ask the analyzer which resolve from each barrel. One file per symbol so
+// a single bad name cannot poison the others and the error→symbol mapping is exact.
+const probeDir = join(PROJECT, "lib", "__catalogprobe");
+function resolveFrom(barrel) {
+  rmSync(probeDir, { recursive: true, force: true });
+  mkdirSync(probeDir, { recursive: true });
+  cands.forEach((sym, i) => {
+    writeFileSync(join(probeDir, `s${i}.dart`),
+      `// probe ${sym}\nimport '${barrel}';\n` +
+      `// ignore_for_file: unused_element, non_constant_identifier_names\n` +
+      `${sym}? _t${i};\nfinal _v${i} = ${sym};\n`);
+  });
+  let raw = "";
+  try {
+    raw = execSync("flutter analyze --no-pub lib/__catalogprobe", { cwd: PROJECT, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  } catch (e) { raw = `${e.stdout || ""}${e.stderr || ""}`; }
+  const missing = new Set(), proven = new Set();
+  for (const line of raw.split("\n")) {
+    const m = line.match(/lib\/__catalogprobe\/s(\d+)\.dart/);
+    if (!m) continue;
+    const sym = cands[+m[1]];
+    // An EXTENSION resolves but fits neither position; this diagnostic PROVES it exists.
+    if (/can't be used as an expression|extension_as_expression/.test(line)) { proven.add(sym); continue; }
+    if (/(isn't a class|Undefined name|isn't defined|not a type|isn't a type)/.test(line)) missing.add(sym);
+  }
+  for (const s of proven) missing.delete(s);
+  return cands.filter((s) => !missing.has(s));
+}
+const chat = new Set(resolveFrom(CHAT_BARREL));
+const calls = new Set(resolveFrom(CALLS_BARREL));
+rmSync(probeDir, { recursive: true, force: true });
+
+const symbols = [...new Set([...chat, ...calls])].sort();
+const rejected = cands.filter((s) => !chat.has(s) && !calls.has(s));
+
+const catalog = {
+  family: CATALOG_KEY,
+  generatedFrom: [
+    `cometchat_chat_uikit ${kitVersion} (pub.dev archive, resolved via test-suite/typecheck/flutter-v6)`,
+    "COMPILER-VERIFIED: every symbol was probed with `flutter analyze` and resolves from the stated barrel. A declaration scan generates candidates only — it over-counts (declared but not exported) and under-counts (skips `export 'package:...'`, i.e. the whole re-exported Chat SDK surface).",
+  ],
+  kitPackage: "cometchat_chat_uikit",
+  kitVersion,
+  sdkPackage: `cometchat_sdk ${versionOf("cometchat_sdk")} (re-exported through the kit barrels)`,
+  callsSdkPackage: `cometchat_calls_sdk ${versionOf("cometchat_calls_sdk")} (re-exported through the CALLS barrel only)`,
+  source: "compiler-verified",
+  mode: "analyzer-probe",
+  lang: "dart",
+  barrels: { chat: CHAT_BARREL, calls: CALLS_BARREL },
+  barrelNote: "TWO barrels, DIFFERENT surfaces — a real compile trap. The calls-only symbols are NOT importable from cometchat_chat_uikit.dart, and the calls barrel does not re-export the chat widgets, so a calls screen imports BOTH.",
+  symbolCount: symbols.length,
+  symbols,
+  symbolsByBarrel: {
+    "chat-only": [...chat].filter((s) => !calls.has(s)).sort(),
+    "calls-only": [...calls].filter((s) => !chat.has(s)).sort(),
+    both: [...chat].filter((s) => calls.has(s)).sort(),
+  },
+  internalOnlyExcluded: rejected,
+  internalOnlyExcludedNote: "Declared in the kit/SDK source but NOT resolvable from either barrel — phantoms if emitted.",
+};
+
+const next = JSON.stringify(catalog, null, 2) + "\n";
+const cur = existsSync(OUT) ? readFileSync(OUT, "utf8") : "";
+console.log(`resolved: ${symbols.length} symbol(s) — ${catalog.symbolsByBarrel["chat-only"].length} chat-only · ${catalog.symbolsByBarrel["calls-only"].length} calls-only · ${catalog.symbolsByBarrel.both.length} both · ${rejected.length} excluded`);
+
+if (CHECK) {
+  if (cur.trim() !== next.trim()) {
+    console.log(`\n❌ catalogs/flutter-v6.json is STALE vs the pinned kit ${kitVersion} — run: node test-suite/scripts/catalog-refresh-dart.mjs`);
+    const curSyms = new Set(cur ? JSON.parse(cur).symbols : []);
+    const added = symbols.filter((s) => !curSyms.has(s));
+    const removed = [...curSyms].filter((s) => !symbols.includes(s));
+    if (added.length) console.log(`   + added:   ${added.join(", ")}`);
+    if (removed.length) console.log(`   - removed: ${removed.join(", ")}   ← a skill fence using one of these will now fail Tier-1`);
+    process.exit(1);
+  }
+  console.log("✅ catalogs/flutter-v6.json matches the pinned kit.");
+  process.exit(0);
+}
+writeFileSync(OUT, next);
+console.log(`✅ wrote ${OUT.replace(ROOT + "/", "")}`);

package/test-suite/scripts/catalog-refresh.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * catalog-refresh.mjs — regenerate the Tier-1 symbol catalog from the installed
+ * kit and keep BOTH copies in sync (the shipped oracle + the reviewer's G0 oracle).
+ * This is the automation for oracle-rot (AUDIT-005): SDK minors add/rename symbols;
+ * a stale catalog silently false-passes Tier-1. Run on a schedule + on kit bumps.
+ *
+ *   node test-suite/scripts/catalog-refresh.mjs           # regenerate + write both copies
+ *   node test-suite/scripts/catalog-refresh.mjs --check   # diff only; exit 1 if the catalog would change (CI rot detector)
+ *   node test-suite/scripts/catalog-refresh.mjs --kit <dir> --sdk <dir>   # point at a different install
+ *
+ * Default: reads the kit from the demo app's node_modules (the pinned reference
+ * install). CI can point --kit/--sdk at the lean test-suite/typecheck/web-v7
+ * install instead. Delegates symbol extraction to the skill-creator's
+ * build-catalog.mjs so there is ONE generator, not two.
+ */
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdtempSync, rmSync } from "node:fs";
+import { join, dirname, isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const argv = process.argv.slice(2);
+const CHECK = argv.includes("--check");
+const flagDir = (f, def) => {
+  const i = argv.indexOf(f);
+  if (i < 0) return def;
+  const v = argv[i + 1];
+  return isAbsolute(v) ? v : join(ROOT, v);
+};
+
+const BUILDER = join(ROOT, ".claude/skills/cometchat-skill-creator/tools/build-catalog.mjs");
+const KIT = flagDir("--kit", join(ROOT, "cometchat-react-app/node_modules/@cometchat/chat-uikit-react"));
+const SDK = flagDir("--sdk", join(ROOT, "cometchat-react-app/node_modules/@cometchat/chat-sdk-javascript"));
+// Which family to refresh comes from families.json (RULES.md §22). This hardcoded web-v7,
+// so the scheduled refresh could never keep any other family's catalog from going stale.
+const _FJ = join(ROOT, ".claude/skills/cometchat-skill-reviewer/tools/families.json");
+// Reviewer oracle is DEV-ONLY / not in the tarball — skip cleanly from an installed pack.
+if (!existsSync(_FJ)) {
+  console.log("catalog: reviewer oracle (families.json) not present — dev-only refresh, skipping (installed pack).");
+  process.exit(0);
+}
+const _F = JSON.parse(readFileSync(_FJ, "utf8"));
+const _key = (f) => (f.catalog || "").replace(/^catalog\//, "").replace(/\.json$/, "");
+const _arg = (process.argv.find((a) => a.startsWith("--family=")) || "").split("=")[1]
+  || (process.argv.includes("--family") ? process.argv[process.argv.indexOf("--family") + 1] : null);
+const FAM_ENTRY = _arg
+  ? Object.values(_F.families).find((f) => _key(f) === _arg) || _F.families[_arg]
+  : _F.families[_F.default];
+if (!FAM_ENTRY) { console.error(`ERROR: unknown --family ${_arg}`); process.exit(2); }
+const FAMILY = _key(FAM_ENTRY);
+const CATALOG_MODE = FAM_ENTRY.catalog_build?.mode || ["--exports-only"];
+const SHIPPED = join(ROOT, `test-suite/catalogs/${FAMILY}.json`);
+const REVIEWER = join(ROOT, `.claude/skills/cometchat-skill-reviewer/tools/catalog/${FAMILY}.json`);
+
+if (!existsSync(KIT) || !existsSync(SDK)) {
+  console.error(`ERROR: kit not installed at node_modules/@cometchat.\n` +
+    `       Run:  npm i @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@4`);
+  process.exit(2);
+}
+
+const tmp = mkdtempSync(join(tmpdir(), "cc-catalog-"));
+const outFile = join(tmp, `${FAMILY}.json`);
+const res = spawnSync("node", [
+  BUILDER, "--family", FAMILY, ...CATALOG_MODE,
+  "--dir", KIT, "--dir", SDK, "--out", outFile,
+], { encoding: "utf8" });
+if (res.status !== 0) {
+  console.error(res.stdout || "", res.stderr || "");
+  console.error("ERROR: build-catalog.mjs failed");
+  rmSync(tmp, { recursive: true, force: true });
+  process.exit(2);
+}
+
+const next = JSON.parse(readFileSync(outFile, "utf8"));
+const prev = existsSync(SHIPPED) ? JSON.parse(readFileSync(SHIPPED, "utf8")) : { symbols: [] };
+const prevSet = new Set(prev.symbols || []);
+const nextSet = new Set(next.symbols || []);
+const added = [...nextSet].filter((s) => !prevSet.has(s));
+const removed = [...prevSet].filter((s) => !nextSet.has(s));
+
+console.log(`catalog-refresh: ${prevSet.size} → ${nextSet.size} symbols  (+${added.length} / -${removed.length})`);
+if (added.length) console.log(`  added:   ${added.slice(0, 20).join(", ")}${added.length > 20 ? " …" : ""}`);
+if (removed.length) console.log(`  removed: ${removed.slice(0, 20).join(", ")}${removed.length > 20 ? " …" : ""}`);
+
+if (CHECK) {
+  rmSync(tmp, { recursive: true, force: true });
+  if (added.length || removed.length) {
+    console.log(`\n❌ catalog is STALE — the installed kit's export surface changed. Run: npm run catalog:refresh`);
+    process.exit(1);
+  }
+  console.log(`\n✅ catalog is fresh (matches the installed kit).`);
+  process.exit(0);
+}
+
+copyFileSync(outFile, SHIPPED);
+copyFileSync(outFile, REVIEWER);
+rmSync(tmp, { recursive: true, force: true });
+console.log(`\n✅ wrote ${SHIPPED.replace(ROOT + "/", "")} and ${REVIEWER.replace(ROOT + "/", "")} (both oracles in sync).`);