assistant-ui 0.0.94 → 0.0.95

package/dist/commands/doctor.d.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+
+//#region src/commands/doctor.d.ts
+interface DiscoveredPackage {
+  name: string;
+  version: string;
+  installPath: string;
+}
+declare function discoverInstalledPackages(cwd: string): DiscoveredPackage[];
+interface DuplicateGroup {
+  name: string;
+  installations: DiscoveredPackage[];
+}
+declare function findDuplicates(packages: DiscoveredPackage[]): DuplicateGroup[];
+declare function uniquePackageNames(packages: DiscoveredPackage[]): string[];
+declare function compareSemver(a: string, b: string): number;
+interface OutdatedPackage {
+  name: string;
+  current: string;
+  latest: string;
+}
+declare function findOutdated(packages: DiscoveredPackage[], latest: Map<string, string | null>): OutdatedPackage[];
+declare const doctor: Command;
+//#endregion
+export { DiscoveredPackage, DuplicateGroup, OutdatedPackage, compareSemver, discoverInstalledPackages, doctor, findDuplicates, findOutdated, uniquePackageNames };
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","names":[],"sources":["../../src/commands/doctor.ts"],"mappings":";;;UAiBiB,iBAAA;EACf,IAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,iBA2Fc,yBAAA,CAA0B,GAAA,WAAc,iBAAiB;AAAA,UAOxD,cAAA;EACf,IAAA;EACA,aAAA,EAAe,iBAAiB;AAAA;AAAA,iBAGlB,cAAA,CACd,QAAA,EAAU,iBAAA,KACT,cAAc;AAAA,iBAmBD,kBAAA,CAAmB,QAA6B,EAAnB,iBAAiB;AAAA,iBAqD9C,aAAA,CAAc,CAAA,UAAW,CAAS;AAAA,UAkBjC,eAAA;EACf,IAAA;EACA,OAAA;EACA,MAAA;AAAA;AAAA,iBAGc,YAAA,CACd,QAAA,EAAU,iBAAA,IACV,MAAA,EAAQ,GAAA,0BACP,eAAA;AAAA,cAsFU,MAAA,EAAM,OA6Df"}

package/dist/commands/doctor.js

@@ -0,0 +1,219 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs$1 from "node:fs";
+import * as path$1 from "node:path";
+//#region src/commands/doctor.ts
+const ASSISTANT_UI_PACKAGE_NAMES = new Set([
+	"assistant-stream",
+	"assistant-cloud",
+	"assistant-ui"
+]);
+function isTrackedPackage(name) {
+	if (!name) return false;
+	if (name.startsWith("@assistant-ui/")) return true;
+	return ASSISTANT_UI_PACKAGE_NAMES.has(name);
+}
+function readJson(file) {
+	try {
+		return JSON.parse(fs$1.readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+function processPackageDir(pkgDir, results, visited) {
+	const real = (() => {
+		try {
+			return fs$1.realpathSync(pkgDir);
+		} catch {
+			return pkgDir;
+		}
+	})();
+	if (visited.set.has(real)) return;
+	visited.set.add(real);
+	const pkgJson = readJson(path$1.join(pkgDir, "package.json"));
+	let isTracked = false;
+	if (pkgJson) {
+		const name = pkgJson.name;
+		const version = pkgJson.version;
+		if (name && version && isTrackedPackage(name)) {
+			results.push({
+				name,
+				version,
+				installPath: pkgDir
+			});
+			isTracked = true;
+		}
+	}
+	if (isTracked) walkNodeModulesAt(pkgDir, results, visited);
+}
+function walkNodeModulesAt(baseDir, results, visited) {
+	const nm = path$1.join(baseDir, "node_modules");
+	if (!fs$1.existsSync(nm)) return;
+	let entries;
+	try {
+		entries = fs$1.readdirSync(nm, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+		if (entry.name.startsWith("@")) {
+			const scopeDir = path$1.join(nm, entry.name);
+			let scoped;
+			try {
+				scoped = fs$1.readdirSync(scopeDir, { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const s of scoped) {
+				if (!s.isDirectory() && !s.isSymbolicLink()) continue;
+				processPackageDir(path$1.join(scopeDir, s.name), results, visited);
+			}
+		} else processPackageDir(path$1.join(nm, entry.name), results, visited);
+	}
+}
+function discoverInstalledPackages(cwd) {
+	const results = [];
+	walkNodeModulesAt(cwd, results, { set: /* @__PURE__ */ new Set() });
+	return results;
+}
+function findDuplicates(packages) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		const list = byName.get(pkg.name) ?? [];
+		list.push(pkg);
+		byName.set(pkg.name, list);
+	}
+	const duplicates = [];
+	for (const [name, installations] of byName) if (new Set(installations.map((i) => i.version)).size > 1) duplicates.push({
+		name,
+		installations
+	});
+	duplicates.sort((a, b) => a.name.localeCompare(b.name));
+	return duplicates;
+}
+function uniquePackageNames(packages) {
+	return Array.from(new Set(packages.map((p) => p.name))).sort();
+}
+const VALID_NPM_NAME = /^(@[a-z0-9._~-]+\/)?[a-z0-9._~-]+$/;
+async function fetchLatestVersion(name) {
+	if (!VALID_NPM_NAME.test(name)) return null;
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { headers: { Accept: "application/json" } });
+		if (!res.ok) return null;
+		return (await res.json()).version ?? null;
+	} catch {
+		return null;
+	}
+}
+async function fetchAllLatestVersions(names) {
+	const entries = await Promise.all(names.map(async (n) => [n, await fetchLatestVersion(n)]));
+	return new Map(entries);
+}
+function parseSemver(v) {
+	const m = /^(\d+)\.(\d+)\.(\d+)(?:-([^+\s]+))?/.exec(v);
+	if (!m) return null;
+	return {
+		major: parseInt(m[1], 10),
+		minor: parseInt(m[2], 10),
+		patch: parseInt(m[3], 10),
+		prerelease: m[4] ?? ""
+	};
+}
+function compareSemver(a, b) {
+	const pa = parseSemver(a);
+	const pb = parseSemver(b);
+	if (!pa || !pb) return a.localeCompare(b);
+	if (pa.major !== pb.major) return pa.major - pb.major;
+	if (pa.minor !== pb.minor) return pa.minor - pb.minor;
+	if (pa.patch !== pb.patch) return pa.patch - pb.patch;
+	if (pa.prerelease === pb.prerelease) return 0;
+	if (!pa.prerelease) return 1;
+	if (!pb.prerelease) return -1;
+	return pa.prerelease.localeCompare(pb.prerelease);
+}
+function findOutdated(packages, latest) {
+	const newestByName = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		const existing = newestByName.get(pkg.name);
+		if (!existing || compareSemver(pkg.version, existing) > 0) newestByName.set(pkg.name, pkg.version);
+	}
+	const result = [];
+	for (const [name, current] of newestByName) {
+		const latestVersion = latest.get(name);
+		if (!latestVersion) continue;
+		if (compareSemver(current, latestVersion) < 0) result.push({
+			name,
+			current,
+			latest: latestVersion
+		});
+	}
+	result.sort((a, b) => a.name.localeCompare(b.name));
+	return result;
+}
+function relativeInstallPath(installPath, cwd) {
+	const rel = path$1.relative(cwd, installPath);
+	return rel.startsWith("..") ? installPath : rel;
+}
+function reportDuplicates(duplicates, cwd, lines) {
+	if (duplicates.length === 0) {
+		lines.push(chalk.green("✓ No duplicate versions detected."));
+		return;
+	}
+	lines.push(chalk.red.bold("✗ Duplicate versions detected:"));
+	for (const dup of duplicates) {
+		const versions = Array.from(new Set(dup.installations.map((i) => i.version))).sort(compareSemver).join(", ");
+		lines.push(chalk.red(`  ${dup.name} → ${versions}`));
+		for (const inst of dup.installations) lines.push(chalk.dim(`    ${inst.version}  ${relativeInstallPath(inst.installPath, cwd)}`));
+	}
+	lines.push("");
+	lines.push(chalk.yellow("Duplicates almost always cause subtle runtime bugs (see https://github.com/assistant-ui/assistant-ui/issues/4101)."));
+	lines.push(chalk.yellow("Fix by aligning all @assistant-ui/* packages to compatible versions — run:"));
+	lines.push(chalk.cyan("    npx assistant-ui update"));
+}
+function reportOutdated(outdated, lines) {
+	if (outdated.length === 0) {
+		lines.push(chalk.green("✓ All assistant-ui packages are up to date."));
+		return;
+	}
+	lines.push(chalk.yellow.bold("! Outdated packages:"));
+	const maxLen = Math.max(...outdated.map((o) => o.name.length));
+	for (const o of outdated) lines.push(chalk.yellow(`  ${o.name.padEnd(maxLen)}  ${o.current} → ${o.latest} (latest)`));
+	lines.push("");
+	lines.push(chalk.yellow("Run the following to upgrade everything:"));
+	lines.push(chalk.cyan("    npx assistant-ui update"));
+}
+const doctor = new Command().name("doctor").description("Diagnose mismatched or outdated assistant-ui packages (including transitive ones).").option("-c, --cwd <cwd>", "the working directory. defaults to the current directory.", process.cwd()).option("--no-network", "Skip the npm registry check for latest versions.").action(async (opts) => {
+	const cwd = path$1.resolve(opts.cwd);
+	const packageJsonPath = path$1.join(cwd, "package.json");
+	if (!fs$1.existsSync(packageJsonPath)) {
+		console.error(chalk.red("No package.json found in the current directory."));
+		process.exit(1);
+	}
+	console.log("");
+	console.log(chalk.bold("Running assistant-ui doctor..."));
+	console.log("");
+	const installed = discoverInstalledPackages(cwd);
+	if (installed.length === 0) {
+		console.log(chalk.yellow("No assistant-ui packages found in node_modules. Did you run `npm install`?"));
+		console.log("");
+		return;
+	}
+	const duplicates = findDuplicates(installed);
+	let latest = /* @__PURE__ */ new Map();
+	if (opts.network) latest = await fetchAllLatestVersions(uniquePackageNames(installed));
+	const outdated = findOutdated(installed, latest);
+	const lines = [];
+	reportDuplicates(duplicates, cwd, lines);
+	lines.push("");
+	if (opts.network) reportOutdated(outdated, lines);
+	else lines.push(chalk.dim("Skipped npm registry check (--no-network)."));
+	for (const line of lines) console.log(line);
+	console.log("");
+	if (duplicates.length > 0) process.exitCode = 1;
+});
+//#endregion
+export { compareSemver, discoverInstalledPackages, doctor, findDuplicates, findOutdated, uniquePackageNames };
+
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","names":["fs","path"],"sources":["../../src/commands/doctor.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport chalk from \"chalk\";\n\nconst ASSISTANT_UI_PACKAGE_NAMES = new Set([\n  \"assistant-stream\",\n  \"assistant-cloud\",\n  \"assistant-ui\",\n]);\n\nfunction isTrackedPackage(name: string | undefined): boolean {\n  if (!name) return false;\n  if (name.startsWith(\"@assistant-ui/\")) return true;\n  return ASSISTANT_UI_PACKAGE_NAMES.has(name);\n}\n\nexport interface DiscoveredPackage {\n  name: string;\n  version: string;\n  installPath: string;\n}\n\ninterface ProcessedDir {\n  set: Set<string>;\n}\n\nfunction readJson(file: string): Record<string, unknown> | null {\n  try {\n    return JSON.parse(fs.readFileSync(file, \"utf8\"));\n  } catch {\n    return null;\n  }\n}\n\nfunction processPackageDir(\n  pkgDir: string,\n  results: DiscoveredPackage[],\n  visited: ProcessedDir,\n): void {\n  const real = (() => {\n    try {\n      return fs.realpathSync(pkgDir);\n    } catch {\n      return pkgDir;\n    }\n  })();\n  if (visited.set.has(real)) return;\n  visited.set.add(real);\n\n  const pkgJson = readJson(path.join(pkgDir, \"package.json\"));\n  let isTracked = false;\n  if (pkgJson) {\n    const name = pkgJson.name as string | undefined;\n    const version = pkgJson.version as string | undefined;\n    if (name && version && isTrackedPackage(name)) {\n      results.push({ name, version, installPath: pkgDir });\n      isTracked = true;\n    }\n  }\n\n  // Only descend into nested node_modules of tracked packages. Transitive\n  // copies of @assistant-ui/* live inside packages that depend on them,\n  // which are themselves tracked. Walking every unrelated package's\n  // subtree turns a doctor run on a large repo into thousands of stat\n  // calls for no gain.\n  if (isTracked) {\n    walkNodeModulesAt(pkgDir, results, visited);\n  }\n}\n\nfunction walkNodeModulesAt(\n  baseDir: string,\n  results: DiscoveredPackage[],\n  visited: ProcessedDir,\n): void {\n  const nm = path.join(baseDir, \"node_modules\");\n  if (!fs.existsSync(nm)) return;\n\n  let entries: fs.Dirent[];\n  try {\n    entries = fs.readdirSync(nm, { withFileTypes: true });\n  } catch {\n    return;\n  }\n\n  for (const entry of entries) {\n    if (entry.name.startsWith(\".\")) continue;\n    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;\n\n    if (entry.name.startsWith(\"@\")) {\n      const scopeDir = path.join(nm, entry.name);\n      let scoped: fs.Dirent[];\n      try {\n        scoped = fs.readdirSync(scopeDir, { withFileTypes: true });\n      } catch {\n        continue;\n      }\n      for (const s of scoped) {\n        if (!s.isDirectory() && !s.isSymbolicLink()) continue;\n        processPackageDir(path.join(scopeDir, s.name), results, visited);\n      }\n    } else {\n      processPackageDir(path.join(nm, entry.name), results, visited);\n    }\n  }\n}\n\n// Discover every installation of an assistant-ui-family package reachable\n// from `cwd`. Recurses into nested node_modules so transitive copies\n// (the real source of duplicate-version bugs) are not missed.\nexport function discoverInstalledPackages(cwd: string): DiscoveredPackage[] {\n  const results: DiscoveredPackage[] = [];\n  const visited: ProcessedDir = { set: new Set() };\n  walkNodeModulesAt(cwd, results, visited);\n  return results;\n}\n\nexport interface DuplicateGroup {\n  name: string;\n  installations: DiscoveredPackage[];\n}\n\nexport function findDuplicates(\n  packages: DiscoveredPackage[],\n): DuplicateGroup[] {\n  const byName = new Map<string, DiscoveredPackage[]>();\n  for (const pkg of packages) {\n    const list = byName.get(pkg.name) ?? [];\n    list.push(pkg);\n    byName.set(pkg.name, list);\n  }\n\n  const duplicates: DuplicateGroup[] = [];\n  for (const [name, installations] of byName) {\n    const versions = new Set(installations.map((i) => i.version));\n    if (versions.size > 1) {\n      duplicates.push({ name, installations });\n    }\n  }\n  duplicates.sort((a, b) => a.name.localeCompare(b.name));\n  return duplicates;\n}\n\nexport function uniquePackageNames(packages: DiscoveredPackage[]): string[] {\n  return Array.from(new Set(packages.map((p) => p.name))).sort();\n}\n\n// Package names use a restricted character set (`[a-z0-9._~-]` plus a\n// leading `@scope/` for scoped packages — see the npm package-name spec)\n// and the npm registry expects the scope's `@` and `/` un-encoded. So a\n// simple validation + concatenation is both correct and avoids the\n// CodeQL \"incomplete string escaping\" foot-gun of `encodeURIComponent`\n// + targeted un-escape.\nconst VALID_NPM_NAME = /^(@[a-z0-9._~-]+\\/)?[a-z0-9._~-]+$/;\n\nasync function fetchLatestVersion(name: string): Promise<string | null> {\n  if (!VALID_NPM_NAME.test(name)) return null;\n  try {\n    const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {\n      headers: { Accept: \"application/json\" },\n    });\n    if (!res.ok) return null;\n    const data = (await res.json()) as { version?: string };\n    return data.version ?? null;\n  } catch {\n    return null;\n  }\n}\n\nasync function fetchAllLatestVersions(\n  names: string[],\n): Promise<Map<string, string | null>> {\n  const entries = await Promise.all(\n    names.map(async (n) => [n, await fetchLatestVersion(n)] as const),\n  );\n  return new Map(entries);\n}\n\ninterface SemverParts {\n  major: number;\n  minor: number;\n  patch: number;\n  prerelease: string;\n}\n\nfunction parseSemver(v: string): SemverParts | null {\n  const m = /^(\\d+)\\.(\\d+)\\.(\\d+)(?:-([^+\\s]+))?/.exec(v);\n  if (!m) return null;\n  return {\n    major: parseInt(m[1]!, 10),\n    minor: parseInt(m[2]!, 10),\n    patch: parseInt(m[3]!, 10),\n    prerelease: m[4] ?? \"\",\n  };\n}\n\nexport function compareSemver(a: string, b: string): number {\n  const pa = parseSemver(a);\n  const pb = parseSemver(b);\n  if (!pa || !pb) return a.localeCompare(b);\n  if (pa.major !== pb.major) return pa.major - pb.major;\n  if (pa.minor !== pb.minor) return pa.minor - pb.minor;\n  if (pa.patch !== pb.patch) return pa.patch - pb.patch;\n\n  // Per SemVer §11: a version with a prerelease tag is *less than* the\n  // same x.y.z without one. We compare tags lexically for a stable\n  // ordering across prereleases — good enough for doctor's \"is X older\n  // than the npm latest\" check.\n  if (pa.prerelease === pb.prerelease) return 0;\n  if (!pa.prerelease) return 1;\n  if (!pb.prerelease) return -1;\n  return pa.prerelease.localeCompare(pb.prerelease);\n}\n\nexport interface OutdatedPackage {\n  name: string;\n  current: string;\n  latest: string;\n}\n\nexport function findOutdated(\n  packages: DiscoveredPackage[],\n  latest: Map<string, string | null>,\n): OutdatedPackage[] {\n  const newestByName = new Map<string, string>();\n  for (const pkg of packages) {\n    const existing = newestByName.get(pkg.name);\n    if (!existing || compareSemver(pkg.version, existing) > 0) {\n      newestByName.set(pkg.name, pkg.version);\n    }\n  }\n\n  const result: OutdatedPackage[] = [];\n  for (const [name, current] of newestByName) {\n    const latestVersion = latest.get(name);\n    if (!latestVersion) continue;\n    if (compareSemver(current, latestVersion) < 0) {\n      result.push({ name, current, latest: latestVersion });\n    }\n  }\n  result.sort((a, b) => a.name.localeCompare(b.name));\n  return result;\n}\n\nfunction relativeInstallPath(installPath: string, cwd: string): string {\n  const rel = path.relative(cwd, installPath);\n  return rel.startsWith(\"..\") ? installPath : rel;\n}\n\nfunction reportDuplicates(\n  duplicates: DuplicateGroup[],\n  cwd: string,\n  lines: string[],\n): void {\n  if (duplicates.length === 0) {\n    lines.push(chalk.green(\"✓ No duplicate versions detected.\"));\n    return;\n  }\n\n  lines.push(chalk.red.bold(\"✗ Duplicate versions detected:\"));\n  for (const dup of duplicates) {\n    const versions = Array.from(\n      new Set(dup.installations.map((i) => i.version)),\n    )\n      .sort(compareSemver)\n      .join(\", \");\n    lines.push(chalk.red(`  ${dup.name} → ${versions}`));\n    for (const inst of dup.installations) {\n      lines.push(\n        chalk.dim(\n          `    ${inst.version}  ${relativeInstallPath(inst.installPath, cwd)}`,\n        ),\n      );\n    }\n  }\n  lines.push(\"\");\n  lines.push(\n    chalk.yellow(\n      \"Duplicates almost always cause subtle runtime bugs (see https://github.com/assistant-ui/assistant-ui/issues/4101).\",\n    ),\n  );\n  lines.push(\n    chalk.yellow(\n      \"Fix by aligning all @assistant-ui/* packages to compatible versions — run:\",\n    ),\n  );\n  lines.push(chalk.cyan(\"    npx assistant-ui update\"));\n}\n\nfunction reportOutdated(outdated: OutdatedPackage[], lines: string[]): void {\n  if (outdated.length === 0) {\n    lines.push(chalk.green(\"✓ All assistant-ui packages are up to date.\"));\n    return;\n  }\n\n  lines.push(chalk.yellow.bold(\"! Outdated packages:\"));\n  const maxLen = Math.max(...outdated.map((o) => o.name.length));\n  for (const o of outdated) {\n    lines.push(\n      chalk.yellow(\n        `  ${o.name.padEnd(maxLen)}  ${o.current} → ${o.latest} (latest)`,\n      ),\n    );\n  }\n  lines.push(\"\");\n  lines.push(chalk.yellow(\"Run the following to upgrade everything:\"));\n  lines.push(chalk.cyan(\"    npx assistant-ui update\"));\n}\n\nexport const doctor = new Command()\n  .name(\"doctor\")\n  .description(\n    \"Diagnose mismatched or outdated assistant-ui packages (including transitive ones).\",\n  )\n  .option(\n    \"-c, --cwd <cwd>\",\n    \"the working directory. defaults to the current directory.\",\n    process.cwd(),\n  )\n  .option(\"--no-network\", \"Skip the npm registry check for latest versions.\")\n  .action(async (opts: { cwd: string; network: boolean }) => {\n    const cwd = path.resolve(opts.cwd);\n    const packageJsonPath = path.join(cwd, \"package.json\");\n\n    if (!fs.existsSync(packageJsonPath)) {\n      console.error(\n        chalk.red(\"No package.json found in the current directory.\"),\n      );\n      process.exit(1);\n    }\n\n    console.log(\"\");\n    console.log(chalk.bold(\"Running assistant-ui doctor...\"));\n    console.log(\"\");\n\n    const installed = discoverInstalledPackages(cwd);\n\n    if (installed.length === 0) {\n      console.log(\n        chalk.yellow(\n          \"No assistant-ui packages found in node_modules. Did you run `npm install`?\",\n        ),\n      );\n      console.log(\"\");\n      return;\n    }\n\n    const duplicates = findDuplicates(installed);\n\n    let latest = new Map<string, string | null>();\n    if (opts.network) {\n      latest = await fetchAllLatestVersions(uniquePackageNames(installed));\n    }\n    const outdated = findOutdated(installed, latest);\n\n    const lines: string[] = [];\n    reportDuplicates(duplicates, cwd, lines);\n    lines.push(\"\");\n    if (opts.network) {\n      reportOutdated(outdated, lines);\n    } else {\n      lines.push(chalk.dim(\"Skipped npm registry check (--no-network).\"));\n    }\n\n    for (const line of lines) console.log(line);\n    console.log(\"\");\n\n    if (duplicates.length > 0) {\n      process.exitCode = 1;\n    }\n  });\n"],"mappings":"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"}

package/dist/index.js

@@ -7,6 +7,7 @@ import { update } from "./commands/update.js";
 import { mcp } from "./commands/mcp.js";
 import { agent } from "./commands/agent.js";
 import { info } from "./commands/info.js";
+import { doctor } from "./commands/doctor.js";
 import { Command } from "commander";
 //#region src/index.ts
 process.on("SIGINT", () => process.exit(0));
@@ -22,6 +23,7 @@ function main() {
 	program.addCommand(update);
 	program.addCommand(agent);
 	program.addCommand(info);
+	program.addCommand(doctor);
 	program.parse();
 }
 main();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { Command } from \"commander\";\nimport { create } from \"./commands/create\";\nimport { add } from \"./commands/add\";\nimport { codemodCommand, upgradeCommand } from \"./commands/upgrade\";\nimport { init } from \"./commands/init\";\nimport { update } from \"./commands/update\";\nimport { mcp } from \"./commands/mcp\";\nimport { agent } from \"./commands/agent\";\nimport { info } from \"./commands/info\";\n\nprocess.on(\"SIGINT\", () => process.exit(0));\nprocess.on(\"SIGTERM\", () => process.exit(0));\n\nfunction main() {\n  const program = new Command()\n    .name(\"assistant-ui\")\n    .description(\"add components and dependencies to your project\");\n\n  program.addCommand(add);\n  program.addCommand(create);\n  program.addCommand(init);\n  program.addCommand(mcp);\n  program.addCommand(codemodCommand);\n  program.addCommand(upgradeCommand);\n  program.addCommand(update);\n  program.addCommand(agent);\n  program.addCommand(info);\n\n  program.parse();\n}\n\nmain();\n"],"mappings":";;;;;;;;;;;AAYA,QAAQ,GAAG,gBAAgB,QAAQ,KAAK,CAAC,CAAC;AAC1C,QAAQ,GAAG,iBAAiB,QAAQ,KAAK,CAAC,CAAC;AAE3C,SAAS,OAAO;CACd,MAAM,UAAU,IAAI,QAAQ,EACzB,KAAK,cAAc,EACnB,YAAY,iDAAiD;CAEhE,QAAQ,WAAW,GAAG;CACtB,QAAQ,WAAW,MAAM;CACzB,QAAQ,WAAW,IAAI;CACvB,QAAQ,WAAW,GAAG;CACtB,QAAQ,WAAW,cAAc;CACjC,QAAQ,WAAW,cAAc;CACjC,QAAQ,WAAW,MAAM;CACzB,QAAQ,WAAW,KAAK;CACxB,QAAQ,WAAW,IAAI;CAEvB,QAAQ,MAAM;AAChB;AAEA,KAAK"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { Command } from \"commander\";\nimport { create } from \"./commands/create\";\nimport { add } from \"./commands/add\";\nimport { codemodCommand, upgradeCommand } from \"./commands/upgrade\";\nimport { init } from \"./commands/init\";\nimport { update } from \"./commands/update\";\nimport { mcp } from \"./commands/mcp\";\nimport { agent } from \"./commands/agent\";\nimport { info } from \"./commands/info\";\nimport { doctor } from \"./commands/doctor\";\n\nprocess.on(\"SIGINT\", () => process.exit(0));\nprocess.on(\"SIGTERM\", () => process.exit(0));\n\nfunction main() {\n  const program = new Command()\n    .name(\"assistant-ui\")\n    .description(\"add components and dependencies to your project\");\n\n  program.addCommand(add);\n  program.addCommand(create);\n  program.addCommand(init);\n  program.addCommand(mcp);\n  program.addCommand(codemodCommand);\n  program.addCommand(upgradeCommand);\n  program.addCommand(update);\n  program.addCommand(agent);\n  program.addCommand(info);\n  program.addCommand(doctor);\n\n  program.parse();\n}\n\nmain();\n"],"mappings":";;;;;;;;;;;;AAaA,QAAQ,GAAG,gBAAgB,QAAQ,KAAK,CAAC,CAAC;AAC1C,QAAQ,GAAG,iBAAiB,QAAQ,KAAK,CAAC,CAAC;AAE3C,SAAS,OAAO;CACd,MAAM,UAAU,IAAI,QAAQ,EACzB,KAAK,cAAc,EACnB,YAAY,iDAAiD;CAEhE,QAAQ,WAAW,GAAG;CACtB,QAAQ,WAAW,MAAM;CACzB,QAAQ,WAAW,IAAI;CACvB,QAAQ,WAAW,GAAG;CACtB,QAAQ,WAAW,cAAc;CACjC,QAAQ,WAAW,cAAc;CACjC,QAAQ,WAAW,MAAM;CACzB,QAAQ,WAAW,KAAK;CACxB,QAAQ,WAAW,IAAI;CACvB,QAAQ,WAAW,MAAM;CAEzB,QAAQ,MAAM;AAChB;AAEA,KAAK"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-ui",
-  "version": "0.0.94",
+  "version": "0.0.95",
   "description": "CLI for assistant-ui",
   "keywords": [
     "cli",

package/src/commands/doctor.ts

@@ -0,0 +1,372 @@
+import { Command } from "commander";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import chalk from "chalk";
+
+const ASSISTANT_UI_PACKAGE_NAMES = new Set([
+  "assistant-stream",
+  "assistant-cloud",
+  "assistant-ui",
+]);
+
+function isTrackedPackage(name: string | undefined): boolean {
+  if (!name) return false;
+  if (name.startsWith("@assistant-ui/")) return true;
+  return ASSISTANT_UI_PACKAGE_NAMES.has(name);
+}
+
+export interface DiscoveredPackage {
+  name: string;
+  version: string;
+  installPath: string;
+}
+
+interface ProcessedDir {
+  set: Set<string>;
+}
+
+function readJson(file: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function processPackageDir(
+  pkgDir: string,
+  results: DiscoveredPackage[],
+  visited: ProcessedDir,
+): void {
+  const real = (() => {
+    try {
+      return fs.realpathSync(pkgDir);
+    } catch {
+      return pkgDir;
+    }
+  })();
+  if (visited.set.has(real)) return;
+  visited.set.add(real);
+
+  const pkgJson = readJson(path.join(pkgDir, "package.json"));
+  let isTracked = false;
+  if (pkgJson) {
+    const name = pkgJson.name as string | undefined;
+    const version = pkgJson.version as string | undefined;
+    if (name && version && isTrackedPackage(name)) {
+      results.push({ name, version, installPath: pkgDir });
+      isTracked = true;
+    }
+  }
+
+  // Only descend into nested node_modules of tracked packages. Transitive
+  // copies of @assistant-ui/* live inside packages that depend on them,
+  // which are themselves tracked. Walking every unrelated package's
+  // subtree turns a doctor run on a large repo into thousands of stat
+  // calls for no gain.
+  if (isTracked) {
+    walkNodeModulesAt(pkgDir, results, visited);
+  }
+}
+
+function walkNodeModulesAt(
+  baseDir: string,
+  results: DiscoveredPackage[],
+  visited: ProcessedDir,
+): void {
+  const nm = path.join(baseDir, "node_modules");
+  if (!fs.existsSync(nm)) return;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(nm, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+    if (entry.name.startsWith("@")) {
+      const scopeDir = path.join(nm, entry.name);
+      let scoped: fs.Dirent[];
+      try {
+        scoped = fs.readdirSync(scopeDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const s of scoped) {
+        if (!s.isDirectory() && !s.isSymbolicLink()) continue;
+        processPackageDir(path.join(scopeDir, s.name), results, visited);
+      }
+    } else {
+      processPackageDir(path.join(nm, entry.name), results, visited);
+    }
+  }
+}
+
+// Discover every installation of an assistant-ui-family package reachable
+// from `cwd`. Recurses into nested node_modules so transitive copies
+// (the real source of duplicate-version bugs) are not missed.
+export function discoverInstalledPackages(cwd: string): DiscoveredPackage[] {
+  const results: DiscoveredPackage[] = [];
+  const visited: ProcessedDir = { set: new Set() };
+  walkNodeModulesAt(cwd, results, visited);
+  return results;
+}
+
+export interface DuplicateGroup {
+  name: string;
+  installations: DiscoveredPackage[];
+}
+
+export function findDuplicates(
+  packages: DiscoveredPackage[],
+): DuplicateGroup[] {
+  const byName = new Map<string, DiscoveredPackage[]>();
+  for (const pkg of packages) {
+    const list = byName.get(pkg.name) ?? [];
+    list.push(pkg);
+    byName.set(pkg.name, list);
+  }
+
+  const duplicates: DuplicateGroup[] = [];
+  for (const [name, installations] of byName) {
+    const versions = new Set(installations.map((i) => i.version));
+    if (versions.size > 1) {
+      duplicates.push({ name, installations });
+    }
+  }
+  duplicates.sort((a, b) => a.name.localeCompare(b.name));
+  return duplicates;
+}
+
+export function uniquePackageNames(packages: DiscoveredPackage[]): string[] {
+  return Array.from(new Set(packages.map((p) => p.name))).sort();
+}
+
+// Package names use a restricted character set (`[a-z0-9._~-]` plus a
+// leading `@scope/` for scoped packages — see the npm package-name spec)
+// and the npm registry expects the scope's `@` and `/` un-encoded. So a
+// simple validation + concatenation is both correct and avoids the
+// CodeQL "incomplete string escaping" foot-gun of `encodeURIComponent`
+// + targeted un-escape.
+const VALID_NPM_NAME = /^(@[a-z0-9._~-]+\/)?[a-z0-9._~-]+$/;
+
+async function fetchLatestVersion(name: string): Promise<string | null> {
+  if (!VALID_NPM_NAME.test(name)) return null;
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {
+      headers: { Accept: "application/json" },
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { version?: string };
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchAllLatestVersions(
+  names: string[],
+): Promise<Map<string, string | null>> {
+  const entries = await Promise.all(
+    names.map(async (n) => [n, await fetchLatestVersion(n)] as const),
+  );
+  return new Map(entries);
+}
+
+interface SemverParts {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string;
+}
+
+function parseSemver(v: string): SemverParts | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([^+\s]+))?/.exec(v);
+  if (!m) return null;
+  return {
+    major: parseInt(m[1]!, 10),
+    minor: parseInt(m[2]!, 10),
+    patch: parseInt(m[3]!, 10),
+    prerelease: m[4] ?? "",
+  };
+}
+
+export function compareSemver(a: string, b: string): number {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return a.localeCompare(b);
+  if (pa.major !== pb.major) return pa.major - pb.major;
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch - pb.patch;
+
+  // Per SemVer §11: a version with a prerelease tag is *less than* the
+  // same x.y.z without one. We compare tags lexically for a stable
+  // ordering across prereleases — good enough for doctor's "is X older
+  // than the npm latest" check.
+  if (pa.prerelease === pb.prerelease) return 0;
+  if (!pa.prerelease) return 1;
+  if (!pb.prerelease) return -1;
+  return pa.prerelease.localeCompare(pb.prerelease);
+}
+
+export interface OutdatedPackage {
+  name: string;
+  current: string;
+  latest: string;
+}
+
+export function findOutdated(
+  packages: DiscoveredPackage[],
+  latest: Map<string, string | null>,
+): OutdatedPackage[] {
+  const newestByName = new Map<string, string>();
+  for (const pkg of packages) {
+    const existing = newestByName.get(pkg.name);
+    if (!existing || compareSemver(pkg.version, existing) > 0) {
+      newestByName.set(pkg.name, pkg.version);
+    }
+  }
+
+  const result: OutdatedPackage[] = [];
+  for (const [name, current] of newestByName) {
+    const latestVersion = latest.get(name);
+    if (!latestVersion) continue;
+    if (compareSemver(current, latestVersion) < 0) {
+      result.push({ name, current, latest: latestVersion });
+    }
+  }
+  result.sort((a, b) => a.name.localeCompare(b.name));
+  return result;
+}
+
+function relativeInstallPath(installPath: string, cwd: string): string {
+  const rel = path.relative(cwd, installPath);
+  return rel.startsWith("..") ? installPath : rel;
+}
+
+function reportDuplicates(
+  duplicates: DuplicateGroup[],
+  cwd: string,
+  lines: string[],
+): void {
+  if (duplicates.length === 0) {
+    lines.push(chalk.green("✓ No duplicate versions detected."));
+    return;
+  }
+
+  lines.push(chalk.red.bold("✗ Duplicate versions detected:"));
+  for (const dup of duplicates) {
+    const versions = Array.from(
+      new Set(dup.installations.map((i) => i.version)),
+    )
+      .sort(compareSemver)
+      .join(", ");
+    lines.push(chalk.red(`  ${dup.name} → ${versions}`));
+    for (const inst of dup.installations) {
+      lines.push(
+        chalk.dim(
+          `    ${inst.version}  ${relativeInstallPath(inst.installPath, cwd)}`,
+        ),
+      );
+    }
+  }
+  lines.push("");
+  lines.push(
+    chalk.yellow(
+      "Duplicates almost always cause subtle runtime bugs (see https://github.com/assistant-ui/assistant-ui/issues/4101).",
+    ),
+  );
+  lines.push(
+    chalk.yellow(
+      "Fix by aligning all @assistant-ui/* packages to compatible versions — run:",
+    ),
+  );
+  lines.push(chalk.cyan("    npx assistant-ui update"));
+}
+
+function reportOutdated(outdated: OutdatedPackage[], lines: string[]): void {
+  if (outdated.length === 0) {
+    lines.push(chalk.green("✓ All assistant-ui packages are up to date."));
+    return;
+  }
+
+  lines.push(chalk.yellow.bold("! Outdated packages:"));
+  const maxLen = Math.max(...outdated.map((o) => o.name.length));
+  for (const o of outdated) {
+    lines.push(
+      chalk.yellow(
+        `  ${o.name.padEnd(maxLen)}  ${o.current} → ${o.latest} (latest)`,
+      ),
+    );
+  }
+  lines.push("");
+  lines.push(chalk.yellow("Run the following to upgrade everything:"));
+  lines.push(chalk.cyan("    npx assistant-ui update"));
+}
+
+export const doctor = new Command()
+  .name("doctor")
+  .description(
+    "Diagnose mismatched or outdated assistant-ui packages (including transitive ones).",
+  )
+  .option(
+    "-c, --cwd <cwd>",
+    "the working directory. defaults to the current directory.",
+    process.cwd(),
+  )
+  .option("--no-network", "Skip the npm registry check for latest versions.")
+  .action(async (opts: { cwd: string; network: boolean }) => {
+    const cwd = path.resolve(opts.cwd);
+    const packageJsonPath = path.join(cwd, "package.json");
+
+    if (!fs.existsSync(packageJsonPath)) {
+      console.error(
+        chalk.red("No package.json found in the current directory."),
+      );
+      process.exit(1);
+    }
+
+    console.log("");
+    console.log(chalk.bold("Running assistant-ui doctor..."));
+    console.log("");
+
+    const installed = discoverInstalledPackages(cwd);
+
+    if (installed.length === 0) {
+      console.log(
+        chalk.yellow(
+          "No assistant-ui packages found in node_modules. Did you run `npm install`?",
+        ),
+      );
+      console.log("");
+      return;
+    }
+
+    const duplicates = findDuplicates(installed);
+
+    let latest = new Map<string, string | null>();
+    if (opts.network) {
+      latest = await fetchAllLatestVersions(uniquePackageNames(installed));
+    }
+    const outdated = findOutdated(installed, latest);
+
+    const lines: string[] = [];
+    reportDuplicates(duplicates, cwd, lines);
+    lines.push("");
+    if (opts.network) {
+      reportOutdated(outdated, lines);
+    } else {
+      lines.push(chalk.dim("Skipped npm registry check (--no-network)."));
+    }
+
+    for (const line of lines) console.log(line);
+    console.log("");
+
+    if (duplicates.length > 0) {
+      process.exitCode = 1;
+    }
+  });

package/src/index.ts

@@ -9,6 +9,7 @@ import { update } from "./commands/update";
 import { mcp } from "./commands/mcp";
 import { agent } from "./commands/agent";
 import { info } from "./commands/info";
+import { doctor } from "./commands/doctor";
 
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
@@ -27,6 +28,7 @@ function main() {
   program.addCommand(update);
   program.addCommand(agent);
   program.addCommand(info);
+  program.addCommand(doctor);
 
   program.parse();
 }