diff --git a/src/market.ts b/src/market.ts new file mode 100644 index 0000000..29301b9 --- /dev/null +++ b/src/market.ts @@ -0,0 +1,306 @@ +/** + * Skill market providers (P3). + * + * A provider answers `search` / `getDetail` / `resolveArtifact` for ONE + * configured, verified source. The browser half never passes a repository URL: + * it only names a provider id and an entry id, so no request can make the host + * fetch an arbitrary address or clone an arbitrary repository. + * + * First provider: the Claude Code plugin marketplace manifest that lives at + * `.claude-plugin/marketplace.json` in a public GitHub repository. That format + * lists plugins, each with a description and the relative folders of the skills + * it ships. Installing an entry reuses the same staged plan/commit pipeline as + * a manual git install, pinned to the commit resolved here. + */ +import { parseSkillFrontmatter } from './skill-sync.ts' + +/** One provider as the card lists it (no credentials, no local paths). */ +export interface MarketProviderInfo { + id: string + label: string + description: string + /** `owner/repo` the manifest is read from. */ + source: string + homepage: string +} + +/** One normalized marketplace entry. */ +export interface MarketEntry { + id: string + providerId: string + name: string + description: string + version?: string + author?: string + /** Skill folder names (basename of each skill path). */ + skills: string[] + /** Relative paths as written in the manifest, e.g. `./skills/xlsx`. */ + skillPaths: string[] + sourceRepo: string + sourceUrl: string +} + +/** Detail adds per-skill metadata read from each SKILL.md (best effort). */ +export interface MarketDetail extends MarketEntry { + skillDetails: { folder: string; path: string; name?: string; description?: string; ok: boolean }[] + fetchedAt: number +} + +/** What an install plan needs to clone a pinned artifact. */ +export interface MarketArtifact { + repoUrl: string + /** A ref git can fetch (branch, tag or commit SHA). */ + ref: string + /** Resolved commit SHA when the host could look it up. */ + commit?: string + version?: string + folders: string[] +} + +export interface MarketProvider { + info(): MarketProviderInfo + search(query: string, cursor: number): Promise<{ entries: MarketEntry[]; nextCursor?: number }> + getDetail(entryId: string): Promise + resolveArtifact(entryId: string, version?: string): Promise +} + +/** Typed failure so routes can map it to a status code. */ +export class MarketError extends Error { + constructor(public readonly code: string, message: string) { + super(message) + this.name = 'MarketError' + } +} + +/** Row shape of `.claude-plugin/marketplace.json`. */ +interface MarketplaceManifest { + name?: string + owner?: { name?: string } + metadata?: { version?: string; description?: string } + plugins?: { + name?: string + description?: string + source?: string + skills?: string[] + }[] +} + +/** Normalize a manifest skill path to a folder name (its basename). */ +function folderOf(skillPath: string): string { + const trimmed = skillPath.replace(/^\.\//, '').replace(/\/+$/, '') + const parts = trimmed.split('/') + return parts[parts.length - 1] ?? trimmed +} + +/** Small TTL cache so one search + one detail does not refetch the manifest. */ +interface CacheEntry { + at: number + value: unknown +} + +/** Provider over a Claude Code plugin marketplace manifest on GitHub. */ +export class ClaudePluginMarketplaceProvider implements MarketProvider { + private readonly cache = new Map() + private readonly fetchImpl: typeof fetch + + constructor( + private readonly options: { + id: string + label: string + description: string + repo: string + ref?: string + homepage?: string + timeoutMs?: number + fetchImpl?: typeof fetch + }, + ) { + this.fetchImpl = options.fetchImpl ?? fetch + } + + info(): MarketProviderInfo { + return { + id: this.options.id, + label: this.options.label, + description: this.options.description, + source: this.options.repo, + homepage: this.options.homepage ?? `https://github.com/${this.options.repo}`, + } + } + + private ref(): string { + return this.options.ref ?? 'main' + } + + private timeoutMs(): number { + return this.options.timeoutMs ?? 8000 + } + + private rawUrl(path: string): string { + const clean = path.replace(/^\.\//, '') + return `https://raw.githubusercontent.com/${this.options.repo}/${encodeURIComponent(this.ref())}/${clean}` + } + + private async fetchText(url: string): Promise { + let response: Response + try { + response = await this.fetchImpl(url, { + headers: { accept: 'application/json, text/plain, */*', 'user-agent': 'dsh-brain-market' }, + signal: AbortSignal.timeout(this.timeoutMs()), + }) + } catch (error) { + throw new MarketError('unreachable', `市场来源不可达:${error instanceof Error ? error.message : String(error)}`) + } + if (!response.ok) { + throw new MarketError('http_' + String(response.status), `市场来源返回 HTTP ${response.status}`) + } + return response.text() + } + + private async fetchJson(url: string, ttlMs = 60_000): Promise { + const hit = this.cache.get(url) + if (hit !== undefined && Date.now() - hit.at < ttlMs) return hit.value as T + const text = await this.fetchText(url) + let parsed: unknown + try { + parsed = JSON.parse(text) + } catch { + throw new MarketError('invalid_manifest', '市场清单不是合法 JSON。') + } + this.cache.set(url, { at: Date.now(), value: parsed }) + return parsed as T + } + + private async manifest(): Promise { + const parsed = await this.fetchJson(this.rawUrl('.claude-plugin/marketplace.json')) + if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) { + throw new MarketError('invalid_manifest', '市场清单结构不正确。') + } + return parsed as MarketplaceManifest + } + + private entriesOf(manifest: MarketplaceManifest): MarketEntry[] { + const list = Array.isArray(manifest.plugins) ? manifest.plugins : [] + const version = manifest.metadata?.version + const author = manifest.owner?.name + const entries: MarketEntry[] = [] + for (const plugin of list) { + const name = typeof plugin.name === 'string' ? plugin.name : '' + if (name === '') continue + const paths = Array.isArray(plugin.skills) ? plugin.skills.filter((p): p is string => typeof p === 'string') : [] + const entry: MarketEntry = { + id: name, + providerId: this.options.id, + name, + description: typeof plugin.description === 'string' ? plugin.description : '', + skills: paths.map(folderOf), + skillPaths: paths, + sourceRepo: this.options.repo, + sourceUrl: `https://github.com/${this.options.repo}`, + } + if (typeof version === 'string') entry.version = version + if (typeof author === 'string') entry.author = author + entries.push(entry) + } + return entries + } + + async search(query: string, cursor: number): Promise<{ entries: MarketEntry[]; nextCursor?: number }> { + const entries = this.entriesOf(await this.manifest()) + const needle = query.trim().toLowerCase() + const filtered = needle === '' + ? entries + : entries.filter((entry) => + `${entry.name}\n${entry.description}\n${entry.skills.join(' ')}`.toLowerCase().includes(needle), + ) + const pageSize = 10 + const start = Number.isFinite(cursor) && cursor > 0 ? Math.floor(cursor) : 0 + const page = filtered.slice(start, start + pageSize) + const next = start + pageSize < filtered.length ? start + pageSize : undefined + return next === undefined ? { entries: page } : { entries: page, nextCursor: next } + } + + private findEntry(manifest: MarketplaceManifest, entryId: string): MarketEntry { + const entry = this.entriesOf(manifest).find((item) => item.id === entryId) + if (entry === undefined) throw new MarketError('not_found', `市场里没有条目:${entryId}`) + return entry + } + + async getDetail(entryId: string): Promise { + const entry = this.findEntry(await this.manifest(), entryId) + const skillDetails: MarketDetail['skillDetails'] = [] + // Bound the fan-out: a manifest can list dozens of skills. + for (const path of entry.skillPaths.slice(0, 24)) { + const folder = folderOf(path) + try { + const markdown = await this.fetchText(this.rawUrl(`${path.replace(/^\.\//, '')}/SKILL.md`)) + const frontmatter = parseSkillFrontmatter(markdown) + const detail: MarketDetail['skillDetails'][number] = { folder, path, ok: true } + if (typeof frontmatter.name === 'string') detail.name = frontmatter.name + if (typeof frontmatter.description === 'string') detail.description = frontmatter.description.slice(0, 300) + skillDetails.push(detail) + } catch { + skillDetails.push({ folder, path, ok: false }) + } + } + return { ...entry, skillDetails, fetchedAt: Date.now() } + } + + async resolveArtifact(entryId: string, _version?: string): Promise { + const entry = this.findEntry(await this.manifest(), entryId) + let commit: string | undefined + try { + const payload = await this.fetchJson<{ sha?: unknown }>( + `https://api.github.com/repos/${this.options.repo}/commits/${encodeURIComponent(this.ref())}`, + 30_000, + ) + if (typeof payload.sha === 'string' && /^[0-9a-f]{7,40}$/i.test(payload.sha)) commit = payload.sha + } catch { + // Rate-limited or offline: fall back to the branch ref; git checkout pins + // the actual commit at clone time and the install records it. + } + const artifact: MarketArtifact = { + repoUrl: `https://github.com/${this.options.repo}.git`, + ref: commit ?? this.ref(), + folders: entry.skills, + } + if (commit !== undefined) artifact.commit = commit + if (entry.version !== undefined) artifact.version = entry.version + return artifact + } +} + +/** A small registry of providers; the browser can only ask for one by id. */ +export class MarketService { + private readonly byId = new Map() + + constructor(providers: MarketProvider[]) { + for (const provider of providers) this.byId.set(provider.info().id, provider) + } + + list(): MarketProviderInfo[] { + return [...this.byId.values()].map((provider) => provider.info()) + } + + has(providerId: string): boolean { + return this.byId.has(providerId) + } + + get(providerId: string): MarketProvider { + const provider = this.byId.get(providerId) + if (provider === undefined) throw new MarketError('unknown_provider', `未知的市场来源:${providerId}`) + return provider + } + + search(providerId: string, query: string, cursor: number): ReturnType { + return this.get(providerId).search(query, cursor) + } + + detail(providerId: string, entryId: string): ReturnType { + return this.get(providerId).getDetail(entryId) + } + + resolve(providerId: string, entryId: string, version?: string): ReturnType { + return this.get(providerId).resolveArtifact(entryId, version) + } +}