Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
feat(agent-skills): add catalog.ts with getCatalog/filter/coverage/fetch helpers
diegosouzapwa0cc22be7378
diff --git a/src/lib/agentSkills/catalog.ts b/src/lib/agentSkills/catalog.tsnew file mode 100644index 0000000000..05e8c7119d--- /dev/null+++ b/src/lib/agentSkills/catalog.ts@@ -0,0 +1,248 @@+/**+ * catalog.ts — single source of truth for the 42-entry Agent Skills catalog.+ *+ * Consumers: REST routes (/api/agent-skills/*), MCP tools, A2A skill, Generator.+ * Do NOT import this from UI components directly — use the REST API instead.+ */++import fs from "node:fs";+import path from "node:path";+import type { AgentSkill, SkillCoverage, SkillMarkdown } from "./types";+import { CURATED_SKILLS, getAgentSkillRawUrl, getAgentSkillBlobUrl } from "@/shared/constants/agentSkills";++// ── Canonical ID lists (D28) ────────────────────────────────────────────────++/** 22 canonical API skill IDs, in spec order. */+export const API_SKILL_IDS: readonly string[] = [+ "omni-auth",+ "omni-providers",+ "omni-models",+ "omni-combos-routing",+ "omni-api-keys",+ "omni-usage-logs",+ "omni-budget",+ "omni-settings",+ "omni-proxies",+ "omni-cache",+ "omni-compression",+ "omni-context-rtk",+ "omni-resilience",+ "omni-cli-tools",+ "omni-tunnels",+ "omni-sync-cloud",+ "omni-db-backups",+ "omni-webhooks",+ "omni-mcp",+ "omni-agents-a2a",+ "omni-version-manager",+ "omni-inference",+] as const;++/** 20 canonical CLI skill IDs, in spec order. */+export const CLI_SKILL_IDS: readonly string[] = [+ "cli-serve",+ "cli-health",+ "cli-providers",+ "cli-keys",+ "cli-models",+ "cli-chat",+ "cli-routing",+ "cli-resilience",+ "cli-compression",+ "cli-contexts",+ "cli-cost-usage",+ "cli-mcp",+ "cli-a2a",+ "cli-tunnel",+ "cli-backup-sync",+ "cli-policy-audit",+ "cli-batches",+ "cli-eval",+ "cli-plugins-skills",+ "cli-setup",+] as const;++// ── Module-scope cache ──────────────────────────────────────────────────────++let _cache: AgentSkill[] | null = null;++// ── Helpers ─────────────────────────────────────────────────────────────────++function buildFullSkill(+ curated: (typeof CURATED_SKILLS)[number],+): AgentSkill {+ return {+ ...curated,+ endpoints: curated.category === "api" ? [] : undefined,+ cliCommands: curated.category === "cli" ? [] : undefined,+ rawUrl: getAgentSkillRawUrl(curated.id),+ githubUrl: getAgentSkillBlobUrl(curated.id),+ };+}++function deriveCatalog(): AgentSkill[] {+ return CURATED_SKILLS.map(buildFullSkill);+}++// ── Public API ───────────────────────────────────────────────────────────────++/**+ * Returns the full catalog (42 entries). Cached in module scope after first call.+ * Safe to call multiple times — re-derives only after `refreshCatalog()`.+ */+export function getCatalog(): AgentSkill[] {+ if (!_cache) {+ _cache = deriveCatalog();+ }+ return _cache;+}++/** Returns single skill metadata or null. */+export function getSkillById(id: string): AgentSkill | null {+ return getCatalog().find((s) => s.id === id) ?? null;+}++/** Filters catalog by category and/or area. */+export function filterCatalog(opts: { category?: "api" | "cli"; area?: string }): AgentSkill[] {+ let skills = getCatalog();+ if (opts.category) {+ skills = skills.filter((s) => s.category === opts.category);+ }+ if (opts.area) {+ skills = skills.filter((s) => s.area === opts.area);+ }+ return skills;+}++/**+ * Computes coverage stats: filesystem has SKILL.md vs catalog declares 42.+ * Reads `skills/` relative to the project root (CWD).+ */+export function computeCoverage(): SkillCoverage {+ const catalog = getCatalog();+ const skillsDir = path.resolve(process.cwd(), "skills");++ let presentIds: Set<string>;+ try {+ const entries = fs.readdirSync(skillsDir, { withFileTypes: true });+ presentIds = new Set(+ entries+ .filter((e) => e.isDirectory())+ .filter((e) => fs.existsSync(path.join(skillsDir, e.name, "SKILL.md")))+ .map((e) => e.name),+ );+ } catch {+ // Directory doesn't exist yet — zero coverage+ presentIds = new Set();+ }++ const apiHave = catalog.filter((s) => s.category === "api" && presentIds.has(s.id)).length;+ const cliHave = catalog.filter((s) => s.category === "cli" && presentIds.has(s.id)).length;++ return {+ api: { have: apiHave, total: 22 },+ cli: { have: cliHave, total: 20 },+ totalSkills: apiHave + cliHave,+ generatedAt: new Date().toISOString(),+ };+}++/**+ * Forces re-derivation of the catalog on next `getCatalog()` call.+ * Used by tests and by the generator after writing new SKILL.md files.+ */+export function refreshCatalog(): void {+ _cache = null;+}++/**+ * Fetches the SKILL.md content for a given skill ID.+ *+ * Resolution order:+ * 1. Local filesystem `skills/{id}/SKILL.md` (fast, used during dev + after generation)+ * 2. GitHub raw URL with 1-hour cache (production fallback when file not yet generated)+ *+ * Returns a `SkillMarkdown` shape. Throws if both sources fail.+ * Used by: F4 `/api/agent-skills/[id]/raw` route.+ */+export async function fetchSkillMarkdown(id: string): Promise<SkillMarkdown> {+ const localPath = path.resolve(process.cwd(), "skills", id, "SKILL.md");++ // 1. Try filesystem first+ try {+ const raw = fs.readFileSync(localPath, "utf-8");+ const parsed = parseMarkdownFrontmatter(raw);+ return {+ id,+ frontmatter: parsed.frontmatter,+ body: parsed.body,+ source: "filesystem",+ fetchedAt: new Date().toISOString(),+ };+ } catch {+ // File not present locally — fall through to GitHub+ }++ // 2. Fetch from GitHub raw (with Next.js revalidate cache if available)+ const skill = getSkillById(id);+ if (!skill) {+ throw new Error(`Skill not found in catalog: ${id}`);+ }++ const response = await fetch(skill.rawUrl, {+ // @ts-expect-error — Next.js extended fetch options+ next: { revalidate: 3600 },+ });++ if (!response.ok) {+ throw new Error(`GitHub raw fetch failed: HTTP ${response.status} for ${skill.rawUrl}`);+ }++ const raw = await response.text();+ const parsed = parseMarkdownFrontmatter(raw);++ return {+ id,+ frontmatter: parsed.frontmatter,+ body: parsed.body,+ source: "github",+ fetchedAt: new Date().toISOString(),+ };+}++// ── Internal helpers ─────────────────────────────────────────────────────────++/**+ * Parses YAML frontmatter from a markdown string.+ * Expects: `---\nkey: value\n---\n<body>` format.+ * Returns default values if frontmatter is absent or malformed.+ */+function parseMarkdownFrontmatter(content: string): {+ frontmatter: { name: string; description: string };+ body: string;+} {+ const FM_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;+ const match = FM_REGEX.exec(content);++ if (!match) {+ return {+ frontmatter: { name: "", description: "" },+ body: content,+ };+ }++ const yamlBlock = match[1];+ const body = match[2] ?? "";++ // Simple key: value extraction (avoids importing js-yaml here to stay lightweight)+ const nameMatch = /^name:\s*(.+)$/m.exec(yamlBlock);+ const descMatch = /^description:\s*(.+)$/m.exec(yamlBlock);++ return {+ frontmatter: {+ name: nameMatch ? nameMatch[1].trim().replace(/^["']|["']$/g, "") : "",+ description: descMatch ? descMatch[1].trim().replace(/^["']|["']$/g, "") : "",+ },+ body,+ };+}