magus-cli 0.0.0-placeholder → 7.0.0

package/src/services/skillsmp-client.ts

@@ -0,0 +1,193 @@
+/**
+ * Skills API client — calls our Firebase aggregator function
+ * instead of hitting SkillsMP/GitHub APIs directly.
+ *
+ * The Firebase function handles:
+ * - SkillsMP keyword + AI search (with server-side API key)
+ * - GitHub Tree API with ETag caching
+ * - Recommended skills list
+ */
+
+// Deployed `skills` Gen2 Cloud Function (project claudish-6da10, us-central1).
+// Firebase keeps this cloudfunctions.net alias stable for the function.
+const SKILLS_API_BASE =
+	process.env.SKILLS_API_URL ||
+	"https://us-central1-claudish-6da10.cloudfunctions.net/skills";
+
+export interface SkillSearchResult {
+	name: string;
+	displayName?: string;
+	repo: string;
+	skillPath: string;
+	description?: string;
+	source?: string;
+	stars?: number;
+	installCommand?: string;
+}
+
+export interface RepoSkillResult {
+	name: string;
+	skillPath: string;
+	treeSha?: string;
+	description?: string;
+}
+
+export interface CuratedSkillSetResult {
+	name: string;
+	repo: string;
+	description: string;
+	icon: string;
+	stars?: number;
+	skillCount?: number;
+}
+
+export interface CuratedSkillResult extends SkillSearchResult {
+	description: string;
+	category: string;
+}
+
+export interface CuratedSkillsCatalogResult {
+	schemaVersion: number;
+	version: number;
+	generatedAt: string;
+	skills: CuratedSkillResult[];
+	skillSets: CuratedSkillSetResult[];
+}
+
+function isCuratedSkill(value: unknown): value is CuratedSkillResult {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const skill = value as Record<string, unknown>;
+	return (
+		typeof skill.name === "string" &&
+		typeof skill.repo === "string" &&
+		typeof skill.skillPath === "string" &&
+		typeof skill.description === "string" &&
+		typeof skill.category === "string" &&
+		(skill.stars === undefined || typeof skill.stars === "number")
+	);
+}
+
+function isCuratedSkillSet(value: unknown): value is CuratedSkillSetResult {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const set = value as Record<string, unknown>;
+	return (
+		typeof set.name === "string" &&
+		typeof set.repo === "string" &&
+		typeof set.description === "string" &&
+		typeof set.icon === "string" &&
+		(set.stars === undefined || typeof set.stars === "number") &&
+		(set.skillCount === undefined || typeof set.skillCount === "number")
+	);
+}
+
+/**
+ * Thrown when the skills API is unreachable or returns a non-OK status.
+ * Lets callers distinguish "search service is down" from "no skills matched",
+ * which a bare `[]` return cannot express.
+ */
+export class SkillsApiError extends Error {
+	constructor(
+		message: string,
+		readonly status?: number,
+	) {
+		super(message);
+		this.name = "SkillsApiError";
+	}
+}
+
+/**
+ * Search skills across all sources (SkillsMP keyword + AI search).
+ *
+ * Throws {@link SkillsApiError} on transport/HTTP failure so the caller can
+ * surface a distinct "search unavailable" state. An empty array means the
+ * query genuinely matched nothing.
+ */
+export async function searchSkills(
+	query: string,
+	options?: { page?: number; limit?: number },
+): Promise<SkillSearchResult[]> {
+	const params = new URLSearchParams({ q: query });
+	if (options?.page) params.set("page", String(options.page));
+	if (options?.limit) params.set("limit", String(options.limit));
+
+	let res: Response;
+	try {
+		res = await fetch(`${SKILLS_API_BASE}/search?${params}`, {
+			signal: AbortSignal.timeout(12000),
+		});
+	} catch (cause) {
+		throw new SkillsApiError(
+			`Skills search request failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+		);
+	}
+
+	if (!res.ok) {
+		throw new SkillsApiError(
+			`Skills search returned HTTP ${res.status}`,
+			res.status,
+		);
+	}
+
+	const data = (await res.json()) as { skills?: SkillSearchResult[] };
+	return data.skills || [];
+}
+
+/**
+ * Fetch skills from a specific GitHub repo (via our proxy)
+ */
+export async function fetchRepoSkills(
+	owner: string,
+	repo: string,
+): Promise<RepoSkillResult[]> {
+	try {
+		const res = await fetch(`${SKILLS_API_BASE}/repo/${owner}/${repo}`, {
+			signal: AbortSignal.timeout(10000),
+		});
+		if (!res.ok) return [];
+		const data = (await res.json()) as { skills: RepoSkillResult[] };
+		return data.skills || [];
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Get recommended skills list (curated, server-side)
+ */
+export async function fetchRecommendedSkills(): Promise<SkillSearchResult[]> {
+	return (await fetchCuratedSkillsCatalog()).skills;
+}
+
+/** Load the versioned install-ready catalog and skill-set definitions. */
+export async function fetchCuratedSkillsCatalog(): Promise<CuratedSkillsCatalogResult> {
+	let res: Response;
+	try {
+		res = await fetch(`${SKILLS_API_BASE}/recommended`, {
+			signal: AbortSignal.timeout(10000),
+		});
+	} catch (cause) {
+		throw new SkillsApiError(
+			`Curated skills request failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+		);
+	}
+	if (!res.ok) {
+		throw new SkillsApiError(
+			`Curated skills returned HTTP ${res.status}`,
+			res.status,
+		);
+	}
+
+	const data = (await res.json()) as Partial<CuratedSkillsCatalogResult>;
+	if (
+		typeof data.schemaVersion !== "number" ||
+		typeof data.version !== "number" ||
+		typeof data.generatedAt !== "string" ||
+		!Array.isArray(data.skills) ||
+		!data.skills.every(isCuratedSkill) ||
+		!Array.isArray(data.skillSets) ||
+		!data.skillSets.every(isCuratedSkillSet)
+	) {
+		throw new SkillsApiError("Curated skills returned a malformed response");
+	}
+	return data as CuratedSkillsCatalogResult;
+}