agentikit 0.0.7 → 0.0.9

package/src/registry-resolve.ts

@@ -0,0 +1,272 @@
+import type { ParsedGithubRef, ParsedNpmRef, ParsedRegistryRef, ResolvedRegistryArtifact } from "./registry-types"
+
+const GITHUB_API_BASE = "https://api.github.com"
+
+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)
+  }
+
+  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)
+  }
+  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,
+  }
+}
+
+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,
+  }
+}
+
+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 || name.includes(" ")) {
+    throw new Error(`Invalid npm package name: \"${name}\".`)
+  }
+}
+
+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 githubHeaders(): HeadersInit {
+  const token = process.env.GITHUB_TOKEN?.trim()
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "agentikit-registry",
+  }
+  if (token) headers.Authorization = `Bearer ${token}`
+  return headers
+}
+
+async function fetchJson<T>(url: string, headers?: HeadersInit): Promise<T> {
+  const response = await fetch(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 fetch(url, { headers })
+  if (!response.ok) return null
+  return await response.json() as T
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined
+}

package/src/registry-search.ts

@@ -0,0 +1,145 @@
+import type { RegistrySearchHit, RegistrySearchResponse } from "./registry-types"
+
+const GITHUB_API_BASE = "https://api.github.com"
+
+export interface RegistrySearchOptions {
+  limit?: number
+}
+
+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 [npmResult, githubResult] = await Promise.allSettled([
+    searchNpm(trimmed, limit),
+    searchGithub(trimmed, limit),
+  ])
+
+  const hits: RegistrySearchHit[] = []
+  const warnings: string[] = []
+
+  if (npmResult.status === "fulfilled") {
+    hits.push(...npmResult.value)
+  } else {
+    warnings.push(`npm search failed: ${toErrorMessage(npmResult.reason)}`)
+  }
+
+  if (githubResult.status === "fulfilled") {
+    hits.push(...githubResult.value)
+  } else {
+    warnings.push(`GitHub search failed: ${toErrorMessage(githubResult.reason)}`)
+  }
+
+  hits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+
+  return {
+    query: trimmed,
+    hits: hits.slice(0, limit * 2),
+    warnings,
+  }
+}
+
+async function searchNpm(query: string, limit: number): Promise<RegistrySearchHit[]> {
+  const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`
+  const response = await fetch(url)
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`)
+  }
+  const data = await response.json() as Record<string, unknown>
+  const objects = Array.isArray(data.objects) ? data.objects : []
+
+  return objects.flatMap((raw): RegistrySearchHit[] => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return []
+    const obj = raw as Record<string, unknown>
+    const pkg = asRecord(obj.package)
+    const name = asString(pkg.name)
+    if (!name) return []
+
+    const version = asString(pkg.version)
+    const metadata: Record<string, string> = {}
+    if (version) metadata.version = version
+    const date = asString(pkg.date)
+    if (date) metadata.updatedAt = date
+
+    return [{
+      source: "npm",
+      id: `npm:${name}`,
+      title: name,
+      description: asString(pkg.description),
+      ref: name,
+      homepage: asString(asRecord(pkg.links).homepage),
+      score: asNumber(obj.score),
+      metadata,
+    }]
+  })
+}
+
+async function searchGithub(query: string, limit: number): Promise<RegistrySearchHit[]> {
+  const q = encodeURIComponent(`${query} in:name,description,readme`)
+  const url = `${GITHUB_API_BASE}/search/repositories?q=${q}&sort=stars&order=desc&per_page=${limit}`
+  const response = await fetch(url, { headers: githubHeaders() })
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`)
+  }
+  const data = await response.json() as Record<string, unknown>
+  const items = Array.isArray(data.items) ? data.items : []
+
+  return items.flatMap((raw): RegistrySearchHit[] => {
+    const repo = asRecord(raw)
+    const fullName = asString(repo.full_name)
+    if (!fullName) return []
+
+    const metadata: Record<string, string> = {}
+    const stars = asNumber(repo.stargazers_count)
+    if (stars > 0) metadata.stars = String(stars)
+    const language = asString(repo.language)
+    if (language) metadata.language = language
+
+    return [{
+      source: "github",
+      id: `github:${fullName}`,
+      title: fullName,
+      description: asString(repo.description),
+      ref: fullName,
+      homepage: asString(repo.html_url),
+      score: stars,
+      metadata,
+    }]
+  })
+}
+
+function githubHeaders(): HeadersInit {
+  const token = process.env.GITHUB_TOKEN?.trim()
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "agentikit-registry",
+  }
+  if (token) headers.Authorization = `Bearer ${token}`
+  return headers
+}
+
+function clampLimit(limit: number | undefined): number {
+  if (!limit || !Number.isFinite(limit)) return 20
+  return Math.min(100, Math.max(1, Math.trunc(limit)))
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined
+}
+
+function asNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/registry-types.ts

@@ -0,0 +1,64 @@
+export type RegistrySource = "npm" | "github"
+
+export interface RegistryRefBase {
+  source: RegistrySource
+  ref: string
+  id: string
+}
+
+export interface ParsedNpmRef extends RegistryRefBase {
+  source: "npm"
+  packageName: string
+  requestedVersionOrTag?: string
+}
+
+export interface ParsedGithubRef extends RegistryRefBase {
+  source: "github"
+  owner: string
+  repo: string
+  requestedRef?: string
+}
+
+export type ParsedRegistryRef = ParsedNpmRef | ParsedGithubRef
+
+export interface ResolvedRegistryArtifact {
+  id: string
+  source: RegistrySource
+  ref: string
+  artifactUrl: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+}
+
+export interface RegistryInstalledEntry {
+  id: string
+  source: RegistrySource
+  ref: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+  artifactUrl: string
+  stashRoot: string
+  cacheDir: string
+  installedAt: string
+}
+
+export interface RegistryInstallResult extends RegistryInstalledEntry {
+  extractedDir: string
+}
+
+export interface RegistrySearchHit {
+  source: RegistrySource
+  id: string
+  title: string
+  description?: string
+  ref: string
+  homepage?: string
+  score?: number
+  metadata?: Record<string, string>
+}
+
+export interface RegistrySearchResponse {
+  query: string
+  hits: RegistrySearchHit[]
+  warnings: string[]
+}

package/src/ripgrep-install.ts

@@ -0,0 +1,200 @@
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import { IS_WINDOWS } from "./common"
+import { RG_BINARY, resolveRg } from "./ripgrep-resolve"
+
+/**
+ * Platform and architecture detection for ripgrep binary downloads.
+ */
+function getRgPlatformTarget(): { platform: string; arch: string; ext: string } | null {
+  const platform = process.platform
+  const arch = process.arch
+
+  if (platform === "linux" && arch === "x64") {
+    return { platform: "x86_64-unknown-linux-musl", arch: "x64", ext: ".tar.gz" }
+  }
+  if (platform === "linux" && arch === "arm64") {
+    return { platform: "aarch64-unknown-linux-gnu", arch: "arm64", ext: ".tar.gz" }
+  }
+  if (platform === "darwin" && arch === "x64") {
+    return { platform: "x86_64-apple-darwin", arch: "x64", ext: ".tar.gz" }
+  }
+  if (platform === "darwin" && arch === "arm64") {
+    return { platform: "aarch64-apple-darwin", arch: "arm64", ext: ".tar.gz" }
+  }
+  if (platform === "win32" && arch === "x64") {
+    return { platform: "x86_64-pc-windows-msvc", arch: "x64", ext: ".zip" }
+  }
+
+  return null
+}
+
+const RG_VERSION = "14.1.1"
+
+export interface EnsureRgResult {
+  rgPath: string
+  installed: boolean
+  version: string
+}
+
+/**
+ * Ensure ripgrep is available. If not found on PATH or in stash/bin,
+ * download and install it to stash/bin.
+ *
+ * Returns the path to the ripgrep binary and whether it was newly installed.
+ */
+export function ensureRg(stashDir: string): EnsureRgResult {
+  // Already available?
+  const existing = resolveRg(stashDir)
+  if (existing) {
+    return { rgPath: existing, installed: false, version: getRgVersion(existing) }
+  }
+
+  // Determine platform
+  const target = getRgPlatformTarget()
+  if (!target) {
+    throw new Error(
+      `Unsupported platform for ripgrep auto-install: ${process.platform}/${process.arch}. ` +
+      `Install ripgrep manually: https://github.com/BurntSushi/ripgrep#installation`
+    )
+  }
+
+  const binDir = path.join(stashDir, "bin")
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true })
+  }
+
+  const archiveName = `ripgrep-${RG_VERSION}-${target.platform}`
+  const url = `https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${archiveName}${target.ext}`
+  const destBinary = path.join(binDir, RG_BINARY)
+
+  if (target.ext === ".tar.gz") {
+    downloadAndExtractTarGz(url, archiveName, destBinary)
+  } else {
+    downloadAndExtractZip(url, archiveName, destBinary)
+  }
+
+  // Make executable
+  if (!IS_WINDOWS) {
+    fs.chmodSync(destBinary, 0o755)
+  }
+
+  return { rgPath: destBinary, installed: true, version: RG_VERSION }
+}
+
+function downloadAndExtractTarGz(url: string, archiveName: string, destBinary: string): void {
+  const destDir = path.dirname(destBinary)
+  const tmpTarGz = path.join(destDir, "rg-download.tar.gz")
+
+  try {
+    // Download archive to a temporary file without using a shell
+    const curlResult = spawnSync(
+      "curl",
+      ["-fsSL", "-o", tmpTarGz, url],
+      {
+        encoding: "utf8",
+        timeout: 60_000,
+      }
+    )
+
+    if (curlResult.status !== 0) {
+      const err = curlResult.stderr?.trim() || curlResult.error?.message || "unknown error"
+      throw new Error(`Failed to download ripgrep from ${url}: ${err}`)
+    }
+
+    // Extract the specific binary from the archive into destDir
+    const tarResult = spawnSync(
+      "tar",
+      [
+        "xzf",
+        tmpTarGz,
+        "--strip-components=1",
+        "-C",
+        destDir,
+        `${archiveName}/rg`,
+      ],
+      {
+        encoding: "utf8",
+        timeout: 60_000,
+      }
+    )
+
+    if (tarResult.status !== 0) {
+      const err = tarResult.stderr?.trim() || tarResult.error?.message || "unknown error"
+      throw new Error(`Failed to extract ripgrep from ${url}: ${err}`)
+    }
+
+    if (!fs.existsSync(destBinary)) {
+      throw new Error(`ripgrep binary not found at ${destBinary} after extraction`)
+    }
+  } finally {
+    // Best-effort cleanup of temporary archive
+    try {
+      if (fs.existsSync(tmpTarGz)) {
+        fs.unlinkSync(tmpTarGz)
+      }
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+function downloadAndExtractZip(url: string, archiveName: string, destBinary: string): void {
+  const destDir = path.dirname(destBinary)
+  const tmpZip = path.join(destDir, "rg-download.zip")
+  const expandedDir = path.join(destDir, archiveName)
+  try {
+    // Download
+    const dlResult = spawnSync("curl", ["-fsSL", "-o", tmpZip, url], {
+      encoding: "utf8",
+      timeout: 60_000,
+    })
+    if (dlResult.status !== 0) {
+      throw new Error(dlResult.stderr?.trim() || "download failed")
+    }
+
+    // Extract the zip archive using separate spawnSync calls with argument arrays
+    // to avoid shell injection via path interpolation in PowerShell -Command strings
+    const expandResult = spawnSync("powershell", [
+      "-Command",
+      "Expand-Archive",
+      "-Path", tmpZip,
+      "-DestinationPath", destDir,
+      "-Force",
+    ], {
+      encoding: "utf8",
+      timeout: 60_000,
+    })
+    if (expandResult.status !== 0) {
+      throw new Error(expandResult.stderr?.trim() || "extraction failed")
+    }
+
+    const srcRgExe = path.join(destDir, archiveName, "rg.exe")
+    const moveResult = spawnSync("powershell", [
+      "-Command",
+      "Move-Item",
+      "-Force",
+      "-Path", srcRgExe,
+      "-Destination", destBinary,
+    ], {
+      encoding: "utf8",
+      timeout: 60_000,
+    })
+    if (moveResult.status !== 0) {
+      throw new Error(moveResult.stderr?.trim() || "move failed")
+    }
+  } finally {
+    if (fs.existsSync(tmpZip)) fs.unlinkSync(tmpZip)
+    if (fs.existsSync(expandedDir)) fs.rmSync(expandedDir, { recursive: true, force: true })
+  }
+}
+
+function getRgVersion(rgPath: string): string {
+  const result = spawnSync(rgPath, ["--version"], { encoding: "utf8", timeout: 5_000 })
+  if (result.status === 0 && result.stdout) {
+    const match = result.stdout.match(/ripgrep\s+([\d.]+)/)
+    return match ? match[1] : "unknown"
+  }
+  return "unknown"
+}