agentikit 0.0.8 → 0.0.12

package/src/registry-resolve.ts

@@ -0,0 +1,341 @@
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+import { fetchWithTimeout } from "./common"
+import type { ParsedGitRef, ParsedGithubRef, ParsedNpmRef, ParsedRegistryRef, ResolvedRegistryArtifact } from "./registry-types"
+import { GITHUB_API_BASE, githubHeaders, asRecord, asString } from "./github"
+
+export function parseRegistryRef(rawRef: string): ParsedRegistryRef {
+  const ref = rawRef.trim()
+  if (!ref) throw new Error("Registry ref is required.")
+
+  if (ref.startsWith("npm:")) {
+    return parseNpmRef(ref.slice(4), ref)
+  }
+  if (ref.startsWith("github:")) {
+    return parseGithubShorthand(ref.slice(7), ref)
+  }
+  if (ref.startsWith("http://") || ref.startsWith("https://")) {
+    return parseGithubUrl(ref)
+  }
+  const localGitRef = tryParseLocalGitRef(ref, isPathLikeRef(ref))
+  if (localGitRef) {
+    return localGitRef
+  }
+
+  if (ref.startsWith("@") || !looksLikeGithubOwnerRepo(ref)) {
+    return parseNpmRef(ref, ref)
+  }
+
+  return parseGithubShorthand(ref, ref)
+}
+
+export async function resolveRegistryArtifact(parsed: ParsedRegistryRef): Promise<ResolvedRegistryArtifact> {
+  if (parsed.source === "npm") {
+    return resolveNpmArtifact(parsed)
+  }
+  if (parsed.source === "git") {
+    return resolveGitArtifact(parsed)
+  }
+  return resolveGithubArtifact(parsed)
+}
+
+function parseNpmRef(input: string, originalRef: string): ParsedNpmRef {
+  const trimmed = input.trim()
+  if (!trimmed) throw new Error("Invalid npm ref.")
+
+  const parsed = splitNpmNameAndVersion(trimmed)
+  validateNpmPackageName(parsed.packageName)
+
+  return {
+    source: "npm",
+    ref: originalRef,
+    id: `npm:${parsed.packageName}`,
+    packageName: parsed.packageName,
+    requestedVersionOrTag: parsed.requestedVersionOrTag,
+  }
+}
+
+function parseGithubShorthand(input: string, originalRef: string): ParsedGithubRef {
+  const [repoPart, requestedRef] = splitRefSuffix(input.trim())
+  const segments = repoPart.split("/").filter(Boolean)
+  if (segments.length !== 2) {
+    throw new Error("Invalid GitHub ref. Expected owner/repo or owner/repo#ref.")
+  }
+  const owner = segments[0]
+  const repo = segments[1].replace(/\.git$/i, "")
+  if (!owner || !repo) {
+    throw new Error("Invalid GitHub ref. Expected owner/repo.")
+  }
+  return {
+    source: "github",
+    ref: originalRef,
+    id: `github:${owner}/${repo}`,
+    owner,
+    repo,
+    requestedRef,
+  }
+}
+
+function parseGithubUrl(rawUrl: string): ParsedGithubRef {
+  let url: URL
+  try {
+    url = new URL(rawUrl)
+  } catch {
+    throw new Error("Invalid registry URL.")
+  }
+  if (url.hostname !== "github.com") {
+    throw new Error("Only GitHub URLs are currently supported for URL refs.")
+  }
+
+  const segments = url.pathname.split("/").filter(Boolean)
+  if (segments.length < 2) {
+    throw new Error("Invalid GitHub URL. Expected https://github.com/owner/repo.")
+  }
+  const owner = segments[0]
+  const repo = segments[1].replace(/\.git$/i, "")
+  const requestedRef = url.hash ? decodeURIComponent(url.hash.slice(1)) : undefined
+
+  return {
+    source: "github",
+    ref: rawUrl,
+    id: `github:${owner}/${repo}`,
+    owner,
+    repo,
+    requestedRef,
+  }
+}
+
+function tryParseLocalGitRef(rawRef: string, explicitPath: boolean): ParsedGitRef | undefined {
+  if (!explicitPath) {
+    return undefined
+  }
+
+  const resolvedPath = path.resolve(rawRef)
+  let stat: fs.Stats
+  try {
+    stat = fs.statSync(resolvedPath)
+  } catch {
+    throw new Error(`Local path not found: ${resolvedPath}`)
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error("Local add path must be a directory, but the provided path is not one.")
+  }
+
+  const repoRoot = findGitRepoRoot(resolvedPath)
+  if (!repoRoot) {
+    throw new Error("Local add path must be inside a git repository.")
+  }
+
+  return {
+    source: "git",
+    ref: rawRef,
+    id: `git:${encodeURIComponent(resolvedPath)}`,
+    repoRoot,
+    sourcePath: resolvedPath,
+  }
+}
+
+function isPathLikeRef(ref: string): boolean {
+  if (path.isAbsolute(ref)) return true
+  if (ref.startsWith("./") || ref.startsWith("../") || ref.startsWith(".\\") || ref.startsWith("..\\")) {
+    return true
+  }
+  return ref.includes("/") || ref.includes("\\")
+}
+
+async function resolveNpmArtifact(parsed: ParsedNpmRef): Promise<ResolvedRegistryArtifact> {
+  const encodedName = encodeURIComponent(parsed.packageName)
+  const metadata = await fetchJson<Record<string, unknown>>(`https://registry.npmjs.org/${encodedName}`)
+
+  const versions = asRecord(metadata.versions)
+  const distTags = asRecord(metadata["dist-tags"])
+
+  const requested = parsed.requestedVersionOrTag
+  let resolvedVersion: string | undefined
+  if (!requested) {
+    resolvedVersion = asString(distTags.latest)
+  } else if (requested in versions) {
+    resolvedVersion = requested
+  } else {
+    resolvedVersion = asString(distTags[requested])
+  }
+
+  if (!resolvedVersion || !(resolvedVersion in versions)) {
+    throw new Error(`Unable to resolve npm ref \"${parsed.ref}\".`)
+  }
+
+  const versionMeta = asRecord(versions[resolvedVersion])
+  const dist = asRecord(versionMeta.dist)
+  const tarballUrl = asString(dist.tarball)
+  if (!tarballUrl) {
+    throw new Error(`npm package ${parsed.packageName}@${resolvedVersion} does not expose a tarball URL.`)
+  }
+
+  const resolvedRevision = asString(dist.shasum) ?? asString(dist.integrity)
+
+  return {
+    id: parsed.id,
+    source: parsed.source,
+    ref: parsed.ref,
+    artifactUrl: tarballUrl,
+    resolvedVersion,
+    resolvedRevision,
+  }
+}
+
+async function resolveGithubArtifact(parsed: ParsedGithubRef): Promise<ResolvedRegistryArtifact> {
+  const headers = githubHeaders()
+
+  if (parsed.requestedRef) {
+    const commit = await tryFetchJson<Record<string, unknown>>(
+      `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/commits/${encodeURIComponent(parsed.requestedRef)}`,
+      headers,
+    )
+    const resolvedRevision = asString(commit?.sha) ?? parsed.requestedRef
+    return {
+      id: parsed.id,
+      source: parsed.source,
+      ref: parsed.ref,
+      artifactUrl: `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/tarball/${encodeURIComponent(parsed.requestedRef)}`,
+      resolvedRevision,
+      resolvedVersion: parsed.requestedRef,
+    }
+  }
+
+  const latestRelease = await tryFetchJson<Record<string, unknown>>(
+    `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/releases/latest`,
+    headers,
+  )
+  if (latestRelease) {
+    const tarballUrl = asString(latestRelease.tarball_url)
+    if (tarballUrl) {
+      return {
+        id: parsed.id,
+        source: parsed.source,
+        ref: parsed.ref,
+        artifactUrl: tarballUrl,
+        resolvedVersion: asString(latestRelease.tag_name),
+        resolvedRevision: asString(latestRelease.target_commitish),
+      }
+    }
+  }
+
+  const repoMeta = await fetchJson<Record<string, unknown>>(
+    `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}`,
+    headers,
+  )
+  const defaultBranch = asString(repoMeta.default_branch)
+  if (!defaultBranch) {
+    throw new Error(`Unable to resolve default branch for ${parsed.owner}/${parsed.repo}.`)
+  }
+
+  const commit = await tryFetchJson<Record<string, unknown>>(
+    `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/commits/${encodeURIComponent(defaultBranch)}`,
+    headers,
+  )
+
+  return {
+    id: parsed.id,
+    source: parsed.source,
+    ref: parsed.ref,
+    artifactUrl: `${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/tarball/${encodeURIComponent(defaultBranch)}`,
+    resolvedVersion: defaultBranch,
+    resolvedRevision: asString(commit?.sha) ?? defaultBranch,
+  }
+}
+
+async function resolveGitArtifact(parsed: ParsedGitRef): Promise<ResolvedRegistryArtifact> {
+  return {
+    id: parsed.id,
+    source: parsed.source,
+    ref: parsed.ref,
+    artifactUrl: pathToFileURL(parsed.sourcePath).toString(),
+    resolvedRevision: readGitValue(parsed.repoRoot, "rev-parse", "HEAD"),
+    resolvedVersion: readGitValue(parsed.repoRoot, "rev-parse", "--abbrev-ref", "HEAD"),
+  }
+}
+
+function splitNpmNameAndVersion(input: string): { packageName: string; requestedVersionOrTag?: string } {
+  if (input.startsWith("@")) {
+    const secondAt = input.indexOf("@", 1)
+    if (secondAt > 0) {
+      return {
+        packageName: input.slice(0, secondAt),
+        requestedVersionOrTag: input.slice(secondAt + 1) || undefined,
+      }
+    }
+    return { packageName: input }
+  }
+
+  const at = input.lastIndexOf("@")
+  if (at > 0) {
+    return {
+      packageName: input.slice(0, at),
+      requestedVersionOrTag: input.slice(at + 1) || undefined,
+    }
+  }
+  return { packageName: input }
+}
+
+function validateNpmPackageName(name: string): void {
+  if (!name) throw new Error('Invalid npm package name: name is required.')
+  if (name.length > 214) throw new Error(`Invalid npm package name: "${name}" exceeds 214 characters.`)
+  if (name !== name.toLowerCase() && !name.startsWith('@')) {
+    throw new Error(`Invalid npm package name: "${name}" must be lowercase.`)
+  }
+  if (name.startsWith('.') || name.startsWith('_')) {
+    throw new Error(`Invalid npm package name: "${name}" cannot start with . or _.`)
+  }
+  if (/[~'!()*]/.test(name) || name.includes(' ') || encodeURIComponent(name).replace(/%40/g, '@').replace(/%2[Ff]/g, '/') !== name) {
+    throw new Error(`Invalid npm package name: "${name}" contains invalid characters.`)
+  }
+}
+
+function looksLikeGithubOwnerRepo(ref: string): boolean {
+  const [repoPart] = splitRefSuffix(ref)
+  const parts = repoPart.split("/").filter(Boolean)
+  return parts.length === 2
+}
+
+function splitRefSuffix(value: string): [string, string | undefined] {
+  const hash = value.indexOf("#")
+  if (hash < 0) return [value, undefined]
+  return [value.slice(0, hash), value.slice(hash + 1) || undefined]
+}
+
+function findGitRepoRoot(startDir: string): string | undefined {
+  let current = path.resolve(startDir)
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) {
+      return current
+    }
+    const parent = path.dirname(current)
+    if (parent === current) return undefined
+    current = parent
+  }
+}
+
+function readGitValue(repoRoot: string, ...args: string[]): string | undefined {
+  const result = spawnSync("git", ["-C", repoRoot, ...args], { encoding: "utf8" })
+  if (result.status !== 0) return undefined
+  const value = result.stdout.trim()
+  return value || undefined
+}
+
+async function fetchJson<T>(url: string, headers?: HeadersInit): Promise<T> {
+  const response = await fetchWithTimeout(url, { headers })
+  if (!response.ok) {
+    throw new Error(`Request failed (${response.status}) for ${url}`)
+  }
+  return await response.json() as T
+}
+
+async function tryFetchJson<T>(url: string, headers?: HeadersInit): Promise<T | null> {
+  const response = await fetchWithTimeout(url, { headers })
+  if (!response.ok) return null
+  return await response.json() as T
+}
+

package/src/registry-search.ts

@@ -0,0 +1,335 @@
+import fs from "node:fs"
+import path from "node:path"
+import { fetchWithTimeout } from "./common"
+import type { RegistrySearchHit, RegistrySearchResponse } from "./registry-types"
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/** Default registry index URL. Override via config or AKM_REGISTRY_URL env var. */
+const DEFAULT_REGISTRY_URL =
+  "https://raw.githubusercontent.com/itlackey/agentikit-registry/main/index.json"
+
+/** Cache TTL in milliseconds (1 hour). */
+const CACHE_TTL_MS = 60 * 60 * 1000
+
+/** Maximum age before cache is considered stale but still usable as fallback (7 days). */
+const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface RegistryIndex {
+  version: number
+  updatedAt: string
+  kits: RegistryKitEntry[]
+}
+
+export interface RegistryKitEntry {
+  id: string
+  name: string
+  description?: string
+  ref: string
+  source: "npm" | "github" | "git"
+  homepage?: string
+  tags?: string[]
+  assetTypes?: string[]
+  author?: string
+  license?: string
+  latestVersion?: string
+  /** Whether this entry was manually reviewed and approved */
+  curated?: boolean
+}
+
+export interface RegistrySearchOptions {
+  limit?: number
+  /** Override registry URL(s). Accepts a single URL or an array. */
+  registryUrls?: string | string[]
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export async function searchRegistry(
+  query: string,
+  options?: RegistrySearchOptions,
+): Promise<RegistrySearchResponse> {
+  const trimmed = query.trim()
+  if (!trimmed) {
+    return { query: "", hits: [], warnings: [] }
+  }
+
+  const limit = clampLimit(options?.limit)
+  const urls = resolveRegistryUrls(options?.registryUrls)
+  const warnings: string[] = []
+
+  // Load index from all configured registries, merge kits
+  const allKits: RegistryKitEntry[] = []
+  for (const url of urls) {
+    try {
+      const index = await loadIndex(url)
+      if (index) {
+        allKits.push(...index.kits)
+      }
+    } catch (err) {
+      warnings.push(`Registry ${url}: ${toErrorMessage(err)}`)
+    }
+  }
+
+  // Score and rank
+  const hits = scoreKits(allKits, trimmed, limit)
+
+  return { query: trimmed, hits, warnings }
+}
+
+// ── Index loading with cache ────────────────────────────────────────────────
+
+async function loadIndex(url: string): Promise<RegistryIndex | null> {
+  const cachePath = indexCachePath(url)
+  const cached = readCachedIndex(cachePath)
+
+  // Fresh cache: return immediately
+  if (cached && !isCacheExpired(cached.mtime)) {
+    return cached.index
+  }
+
+  // Try to fetch fresh index
+  try {
+    const response = await fetchWithTimeout(url, undefined, 10_000)
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+    const data = (await response.json()) as unknown
+    const index = parseRegistryIndex(data)
+    if (index) {
+      writeCachedIndex(cachePath, index)
+      return index
+    }
+    throw new Error("Invalid registry index format")
+  } catch (err) {
+    // Fetch failed — use stale cache if available
+    if (cached && !isCacheStale(cached.mtime)) {
+      return cached.index
+    }
+    throw err
+  }
+}
+
+function readCachedIndex(
+  cachePath: string,
+): { index: RegistryIndex; mtime: number } | null {
+  try {
+    const stat = fs.statSync(cachePath)
+    const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"))
+    const index = parseRegistryIndex(raw)
+    if (!index) return null
+    return { index, mtime: stat.mtimeMs }
+  } catch {
+    return null
+  }
+}
+
+function writeCachedIndex(cachePath: string, index: RegistryIndex): void {
+  try {
+    const dir = path.dirname(cachePath)
+    fs.mkdirSync(dir, { recursive: true })
+    const tmpPath = cachePath + `.tmp.${process.pid}`
+    fs.writeFileSync(tmpPath, JSON.stringify(index), "utf8")
+    fs.renameSync(tmpPath, cachePath)
+  } catch {
+    // Best-effort caching — don't fail the search if we can't write
+  }
+}
+
+function indexCachePath(url: string): string {
+  const cacheRoot = resolveCacheDir()
+  // Deterministic filename from URL
+  const slug = url
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 120)
+  return path.join(cacheRoot, "registry-index", `${slug}.json`)
+}
+
+function resolveCacheDir(): string {
+  const xdgCache = process.env.XDG_CACHE_HOME?.trim()
+  if (xdgCache) return path.join(path.resolve(xdgCache), "agentikit")
+  const home = process.env.HOME?.trim()
+  if (!home) return path.join("/tmp", "agentikit-cache")
+  return path.join(path.resolve(home), ".cache", "agentikit")
+}
+
+function isCacheExpired(mtimeMs: number): boolean {
+  return Date.now() - mtimeMs > CACHE_TTL_MS
+}
+
+function isCacheStale(mtimeMs: number): boolean {
+  return Date.now() - mtimeMs > CACHE_STALE_MS
+}
+
+// ── Index parsing ───────────────────────────────────────────────────────────
+
+function parseRegistryIndex(data: unknown): RegistryIndex | null {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return null
+  const obj = data as Record<string, unknown>
+
+  if (typeof obj.version !== "number" || obj.version !== 1) return null
+  if (typeof obj.updatedAt !== "string") return null
+  if (!Array.isArray(obj.kits)) return null
+
+  const kits = obj.kits.flatMap((raw): RegistryKitEntry[] => {
+    const kit = parseKitEntry(raw)
+    return kit ? [kit] : []
+  })
+
+  return { version: 1, updatedAt: obj.updatedAt, kits }
+}
+
+function parseKitEntry(raw: unknown): RegistryKitEntry | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null
+  const obj = raw as Record<string, unknown>
+
+  const id = asString(obj.id)
+  const name = asString(obj.name)
+  const ref = asString(obj.ref)
+  const source = asSource(obj.source)
+  if (!id || !name || !ref || !source) return null
+
+  return {
+    id,
+    name,
+    ref,
+    source,
+    description: asString(obj.description),
+    homepage: asString(obj.homepage),
+    tags: asStringArray(obj.tags),
+    assetTypes: asStringArray(obj.assetTypes),
+    author: asString(obj.author),
+    license: asString(obj.license),
+    latestVersion: asString(obj.latestVersion),
+    curated: obj.curated === true ? true : undefined,
+  }
+}
+
+// ── Scoring ─────────────────────────────────────────────────────────────────
+
+function scoreKits(
+  kits: RegistryKitEntry[],
+  query: string,
+  limit: number,
+): RegistrySearchHit[] {
+  const tokens = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean)
+
+  const scored: Array<{ kit: RegistryKitEntry; score: number }> = []
+
+  for (const kit of kits) {
+    const score = scoreKit(kit, tokens)
+    if (score > 0) {
+      scored.push({ kit, score })
+    }
+  }
+
+  scored.sort((a, b) => b.score - a.score)
+
+  return scored.slice(0, limit).map(({ kit, score }) => toSearchHit(kit, score))
+}
+
+function scoreKit(kit: RegistryKitEntry, tokens: string[]): number {
+  let score = 0
+  const nameLower = kit.name.toLowerCase()
+  const descLower = (kit.description ?? "").toLowerCase()
+  const tagsLower = (kit.tags ?? []).map((t) => t.toLowerCase())
+
+  for (const token of tokens) {
+    // Exact name match is strongest signal
+    if (nameLower === token) {
+      score += 1.0
+    } else if (nameLower.includes(token)) {
+      score += 0.6
+    }
+
+    // Tag matches are high-signal (curated keywords)
+    if (tagsLower.some((tag) => tag === token)) {
+      score += 0.5
+    } else if (tagsLower.some((tag) => tag.includes(token))) {
+      score += 0.25
+    }
+
+    // Description substring
+    if (descLower.includes(token)) {
+      score += 0.2
+    }
+
+    // Author match
+    if (kit.author?.toLowerCase().includes(token)) {
+      score += 0.15
+    }
+  }
+
+  // Normalize by token count so multi-word queries don't inflate scores
+  return tokens.length > 0 ? score / tokens.length : 0
+}
+
+function toSearchHit(kit: RegistryKitEntry, score: number): RegistrySearchHit {
+  const metadata: Record<string, string> = {}
+  if (kit.latestVersion) metadata.version = kit.latestVersion
+  if (kit.author) metadata.author = kit.author
+  if (kit.license) metadata.license = kit.license
+  if (kit.assetTypes?.length) metadata.assetTypes = kit.assetTypes.join(", ")
+
+  return {
+    source: kit.source,
+    id: kit.id,
+    title: kit.name,
+    description: kit.description,
+    ref: kit.ref,
+    homepage: kit.homepage,
+    score: Math.round(score * 1000) / 1000,
+    metadata,
+    curated: kit.curated,
+  }
+}
+
+// ── Registry URL resolution ─────────────────────────────────────────────────
+
+function resolveRegistryUrls(override?: string | string[]): string[] {
+  if (override) {
+    const urls = Array.isArray(override) ? override : [override]
+    return urls.filter(Boolean)
+  }
+
+  // Allow env var override (comma-separated)
+  const envUrls = process.env.AKM_REGISTRY_URL?.trim()
+  if (envUrls) {
+    return envUrls.split(",").map((u) => u.trim()).filter(Boolean)
+  }
+
+  return [DEFAULT_REGISTRY_URL]
+}
+
+// ── Utilities ───────────────────────────────────────────────────────────────
+
+function clampLimit(limit: number | undefined): number {
+  if (!limit || !Number.isFinite(limit)) return 20
+  return Math.min(100, Math.max(1, Math.trunc(limit)))
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined
+}
+
+function asSource(value: unknown): "npm" | "github" | "git" | undefined {
+  return value === "npm" || value === "github" || value === "git"
+    ? value
+    : undefined
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const filtered = value.filter((v): v is string => typeof v === "string")
+  return filtered.length > 0 ? filtered : undefined
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}