Context7 Platform -- Up-to-date docs for AI agents
feat(cli): enumerate popularity and trust in skill search results (#2192)
Fahreddin Özcan62dc278b7672
diff --git a/.changeset/crisp-dots-bake.md b/.changeset/crisp-dots-bake.mdnew file mode 100644index 00000000..34d935b8--- /dev/null+++ b/.changeset/crisp-dots-bake.md@@ -0,0 +1,7 @@+---+"ctx7": patch+---++- feat(cli): enumerate popularity with a 4-star scale in skill search, install, and suggest results+- feat(cli): show install count range and trust score in skill hover details+- fix(cli): rename "docs" skill to "find-docs" in setup output and promptsdiff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.tsindex 5ca470bd..be70da2e 100644--- a/packages/cli/src/commands/setup.ts+++ b/packages/cli/src/commands/setup.ts@@ -138,12 +138,12 @@ async function resolveMode(options: SetupOptions): Promise<SetupMode> {message: "How should your agent access Context7?",choices: [{- name: `MCP server\n ${pc.dim("Agent calls Context7 tools via MCP protocol to retrieve up-to-date library docs")}`,- value: "mcp" as SetupMode,+ name: `CLI + Skills\n ${pc.dim("Installs a find-docs skill that guides your agent to fetch up-to-date library docs using ")}${pc.dim(pc.bold("ctx7"))}${pc.dim(" CLI commands")}`,+ value: "cli" as SetupMode,},{- name: `CLI + Skills\n ${pc.dim("Installs a docs skill that guides your agent to fetch up-to-date library docs using ")}${pc.dim(pc.bold("ctx7"))}${pc.dim(" CLI commands")}`,- value: "cli" as SetupMode,+ name: `MCP server\n ${pc.dim("Agent calls Context7 tools via MCP protocol to retrieve up-to-date library docs")}`,+ value: "mcp" as SetupMode,},],theme: {@@ -204,7 +204,9 @@ async function promptAgents(scope: Scope, mode: SetupMode): Promise<SetupAgent[]}const message =- mode === "cli" ? "Install docs skill for which agents?" : "Which agents do you want to set up?";+ mode === "cli"+ ? "Install find-docs skill for which agents?"+ : "Which agents do you want to set up?";try {return await checkboxWithHover(@@ -376,7 +378,7 @@ async function setupCli(options: SetupOptions): Promise<void> {}log.blank();- const spinner = ora("Downloading docs skill...").start();+ const spinner = ora("Downloading find-docs skill...").start();const downloadData = await downloadSkill("/upstash/context7", "find-docs");if (downloadData.error || downloadData.files.length === 0) {@@ -401,7 +403,7 @@ async function setupCli(options: SetupOptions): Promise<void> {log.blank();for (const dir of targetDirs) {log.itemAdd(- `docs ${pc.dim("Guides your agent to fetch up-to-date library docs on demand using ctx7 CLI commands")}`+ `find-docs ${pc.dim("Guides your agent to fetch up-to-date library docs on demand using ctx7 CLI commands")}`);log.plain(` ${pc.dim(dir)}`);}diff --git a/packages/cli/src/commands/skill.ts b/packages/cli/src/commands/skill.tsindex d6cbdba2..bd1c09f4 100644--- a/packages/cli/src/commands/skill.ts+++ b/packages/cli/src/commands/skill.ts@@ -24,8 +24,10 @@ import {import {checkboxWithHover,terminalLink,- formatInstallCount,- formatTrustScore,+ formatPopularity,+ formatTrust,+ formatInstallRange,+ getTrustLabel,} from "../utils/prompts.js";import { installSkillFiles, symlinkSkill } from "../utils/installer.js";import { trackEvent } from "../utils/tracking.js";@@ -279,15 +281,12 @@ async function installCommand(} else {const indexWidth = data.skills.length.toString().length;const maxNameLen = Math.max(...data.skills.map((s) => s.name.length));- const installsColWidth = 10;+ const popularityColWidth = 13;const choices = skillsWithRepo.map((s, index) => {const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);const paddedName = s.name.padEnd(maxNameLen);- const installsRaw = s.installCount ? String(s.installCount) : "-";- const paddedInstalls =- formatInstallCount(s.installCount, pc.dim("-")) +- " ".repeat(installsColWidth - installsRaw.length);- const trust = formatTrustScore(s.trustScore);+ const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4);+ const trust = formatTrust(s.trustScore);const skillUrl = `https://context7.com/skills${s.project}/${s.name}`;const skillLink = terminalLink(s.name, skillUrl, pc.white);@@ -297,12 +296,14 @@ async function installCommand("",`${pc.yellow("Skill:")} ${skillLink}`,`${pc.yellow("Repo:")} ${repoLink}`,+ `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`,+ `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`,`${pc.yellow("Description:")}`,pc.white(s.description || "No description"),];return {- name: `${indexStr} ${paddedName} ${paddedInstalls}${trust}`,+ name: `${indexStr} ${paddedName} ${popularity}${trust}`,value: s,description: metadataLines.join("\n"),};@@ -313,7 +314,7 @@ async function installCommand(const checkboxPrefixWidth = 3;const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);const headerLine =- headerPad + pc.dim("Installs".padEnd(installsColWidth)) + pc.dim("Trust(0-10)");+ headerPad + pc.dim("Popularity".padEnd(popularityColWidth)) + pc.dim("Trust");try {selectedSkills = await checkboxWithHover({@@ -456,16 +457,13 @@ async function searchCommand(query: string): Promise<void> {const nameWithRepo = (s: SkillSearchResult) => `${s.name} ${pc.dim(`(${s.project})`)}`;const nameWithRepoLen = (s: SkillSearchResult) => `${s.name} (${s.project})`.length;const maxNameLen = Math.max(...data.results.map(nameWithRepoLen));- const installsColWidth = 10;+ const popularityColWidth = 13;const choices = data.results.map((s, index) => {const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);const rawLen = nameWithRepoLen(s);const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen);- const installsRaw = s.installCount ? String(s.installCount) : "-";- const paddedInstalls =- formatInstallCount(s.installCount, pc.dim("-")) +- " ".repeat(installsColWidth - installsRaw.length);- const trust = formatTrustScore(s.trustScore);+ const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4);+ const trust = formatTrust(s.trustScore);const skillLink = terminalLink(s.name,@@ -478,12 +476,14 @@ async function searchCommand(query: string): Promise<void> {"",`${pc.yellow("Skill:")} ${skillLink}`,`${pc.yellow("Repo:")} ${repoLink}`,+ `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`,+ `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`,`${pc.yellow("Description:")}`,pc.white(s.description || "No description"),];return {- name: `${indexStr} ${displayName} ${paddedInstalls}${trust}`,+ name: `${indexStr} ${displayName} ${popularity}${trust}`,value: s,description: metadataLines.join("\n"),};@@ -491,8 +491,7 @@ async function searchCommand(query: string): Promise<void> {const checkboxPrefixWidth = 3; // "❯◯ " or " ◯ "const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);- const headerLine =- headerPad + pc.dim("Installs".padEnd(installsColWidth)) + pc.dim("Trust(0-10)");+ const headerLine = headerPad + pc.dim("Popularity".padEnd(popularityColWidth)) + pc.dim("Trust");let selectedSkills: SkillSearchResult[];try {@@ -790,8 +789,8 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {const nameWithRepo = (s: SkillSearchResult) => `${s.name} ${pc.dim(`(${s.project})`)}`;const nameWithRepoLen = (s: SkillSearchResult) => `${s.name} (${s.project})`.length;const maxNameLen = Math.max(...skills.map(nameWithRepoLen));- const installsColWidth = 10;- const trustColWidth = 12;+ const popularityColWidth = 13;+ const trustColWidth = 8;const maxMatchedLen = Math.max(...skills.map((s) => s.matchedDep.length));const indexWidth = skills.length.toString().length;@@ -799,13 +798,9 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {const indexStr = pc.dim(`${(index + 1).toString().padStart(indexWidth)}.`);const rawLen = nameWithRepoLen(s);const displayName = nameWithRepo(s) + " ".repeat(maxNameLen - rawLen);- const installsRaw = s.installCount ? String(s.installCount) : "-";- const paddedInstalls =- formatInstallCount(s.installCount, pc.dim("-")) +- " ".repeat(installsColWidth - installsRaw.length);- const trustRaw =- s.trustScore !== undefined && s.trustScore >= 0 ? s.trustScore.toFixed(1) : "-";- const trust = formatTrustScore(s.trustScore) + " ".repeat(trustColWidth - trustRaw.length);+ const popularity = formatPopularity(s.installCount) + " ".repeat(popularityColWidth - 4);+ const trustLabel = getTrustLabel(s.trustScore);+ const trust = formatTrust(s.trustScore) + " ".repeat(trustColWidth - trustLabel.length);const matched = pc.yellow(s.matchedDep.padEnd(maxMatchedLen));const skillLink = terminalLink(@@ -819,13 +814,15 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {"",`${pc.yellow("Skill:")} ${skillLink}`,`${pc.yellow("Repo:")} ${repoLink}`,+ `${pc.yellow("Installs:")} ${pc.white(formatInstallRange(s.installCount))}`,+ `${pc.yellow("Trust:")} ${s.trustScore !== undefined && s.trustScore >= 0 ? pc.white(s.trustScore.toFixed(1)) : pc.dim("-")}`,`${pc.yellow("Relevant:")} ${pc.white(s.matchedDep)}`,`${pc.yellow("Description:")}`,pc.white(s.description || "No description"),];return {- name: `${indexStr} ${displayName} ${paddedInstalls}${trust}${matched}`,+ name: `${indexStr} ${displayName} ${popularity}${trust}${matched}`,value: s,description: metadataLines.join("\n"),};@@ -835,8 +832,8 @@ async function suggestCommand(options: SuggestOptions): Promise<void> {const headerPad = " ".repeat(checkboxPrefixWidth + indexWidth + 1 + 1 + maxNameLen + 1);const headerLine =headerPad +- pc.dim("Installs".padEnd(installsColWidth)) +- pc.dim("Trust(0-10)".padEnd(trustColWidth)) ++ pc.dim("Popularity".padEnd(popularityColWidth)) ++ pc.dim("Trust".padEnd(trustColWidth)) +pc.dim("Relevant");let selectedSkills: SkillSearchResult[];diff --git a/packages/cli/src/utils/prompts.ts b/packages/cli/src/utils/prompts.tsindex 80b8395f..11e75b6d 100644--- a/packages/cli/src/utils/prompts.ts+++ b/packages/cli/src/utils/prompts.ts@@ -14,19 +14,56 @@ export function terminalLink(text: string, url: string, color?: (s: string) => s}/**- * Formats install count for display.+ * Formats install count into a popularity star rating (4 stars).+ * 0/unknown → ☆☆☆☆, <100 → ★☆☆☆, <500 → ★★☆☆, <1000 → ★★★☆, 1000+ → ★★★★*/-export function formatInstallCount(count: number | undefined, placeholder = ""): string {- if (count === undefined || count === 0) return placeholder;+export function formatPopularity(count: number | undefined): string {+ const filled = "★";+ const empty = "☆";+ const max = 4;+ let stars: number;+ if (count === undefined || count === 0) stars = 0;+ else if (count < 100) stars = 1;+ else if (count < 500) stars = 2;+ else if (count < 1000) stars = 3;+ else stars = 4;- return pc.yellow(String(count));+ const filledPart = filled.repeat(stars);+ const emptyPart = empty.repeat(max - stars);+ if (stars === 0) return pc.dim(emptyPart);+ return pc.yellow(filledPart) + pc.dim(emptyPart);}-export function formatTrustScore(score: number | undefined): string {+/**+ * Returns the install count as a human-readable range string.+ */+export function formatInstallRange(count: number | undefined): string {+ if (count === undefined || count === 0) return "Unknown";+ if (count < 100) return "<100";+ if (count < 500) return "<500";+ if (count < 1000) return "<1,000";+ return "1,000+";+}++/**+ * Formats trust score as High / Medium / Low label.+ * Uses MCP reputation thresholds: >=7 High, >=4 Medium, <4 Low.+ */+export function formatTrust(score: number | undefined): string {if (score === undefined || score < 0) return pc.dim("-");+ if (score >= 7) return pc.green("High");+ if (score >= 4) return pc.yellow("Medium");+ return pc.red("Low");+}- if (score < 3) return pc.red(score.toFixed(1));- return pc.yellow(score.toFixed(1));+/**+ * Returns the raw trust label string (uncolored) for width calculations.+ */+export function getTrustLabel(score: number | undefined): string {+ if (score === undefined || score < 0) return "-";+ if (score >= 7) return "High";+ if (score >= 4) return "Medium";+ return "Low";}export interface CheckboxWithHoverOptions<T> {/** Function to extract display name from value. Defaults to (v) => v.name */