agentikit 0.0.9 → 0.0.13

package/src/registry-search.ts

@@ -1,143 +1,333 @@
+import fs from "node:fs"
+import path from "node:path"
+import { fetchWithTimeout } from "./common"
 import type { RegistrySearchHit, RegistrySearchResponse } from "./registry-types"
 
-const GITHUB_API_BASE = "https://api.github.com"
+// ── 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[]
 }
 
-export async function searchRegistry(query: string, options?: RegistrySearchOptions): Promise<RegistrySearchResponse> {
+// ── 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 [npmResult, githubResult] = await Promise.allSettled([
-    searchNpm(trimmed, limit),
-    searchGithub(trimmed, limit),
-  ])
-
-  const hits: RegistrySearchHit[] = []
+  const urls = resolveRegistryUrls(options?.registryUrls)
   const warnings: string[] = []
 
-  if (npmResult.status === "fulfilled") {
-    hits.push(...npmResult.value)
-  } else {
-    warnings.push(`npm search failed: ${toErrorMessage(npmResult.reason)}`)
+  // 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)}`)
+    }
   }
 
-  if (githubResult.status === "fulfilled") {
-    hits.push(...githubResult.value)
-  } else {
-    warnings.push(`GitHub search failed: ${toErrorMessage(githubResult.reason)}`)
+  // 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
   }
 
-  hits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+  // 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
+  }
+}
 
-  return {
-    query: trimmed,
-    hits: hits.slice(0, limit * 2),
-    warnings,
+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
   }
 }
 
-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}`)
+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
   }
-  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,
-    }]
+}
+
+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,
+  }
 }
 
-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}`)
+// ── 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 })
+    }
   }
-  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,
-    }]
-  })
+
+  scored.sort((a, b) => b.score - a.score)
+
+  return scored.slice(0, limit).map(({ kit, score }) => toSearchHit(kit, score))
 }
 
-function githubHeaders(): HeadersInit {
-  const token = process.env.GITHUB_TOKEN?.trim()
-  const headers: Record<string, string> = {
-    Accept: "application/vnd.github+json",
-    "User-Agent": "agentikit-registry",
+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
+    }
   }
-  if (token) headers.Authorization = `Bearer ${token}`
-  return headers
+
+  // 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 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 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 {

package/src/registry-types.ts

@@ -1,4 +1,4 @@
-export type RegistrySource = "npm" | "github"
+export type RegistrySource = "npm" | "github" | "git"
 
 export interface RegistryRefBase {
   source: RegistrySource
@@ -19,7 +19,13 @@ export interface ParsedGithubRef extends RegistryRefBase {
   requestedRef?: string
 }
 
-export type ParsedRegistryRef = ParsedNpmRef | ParsedGithubRef
+export interface ParsedGitRef extends RegistryRefBase {
+  source: "git"
+  repoRoot: string
+  sourcePath: string
+}
+
+export type ParsedRegistryRef = ParsedNpmRef | ParsedGithubRef | ParsedGitRef
 
 export interface ResolvedRegistryArtifact {
   id: string
@@ -55,6 +61,8 @@ export interface RegistrySearchHit {
   homepage?: string
   score?: number
   metadata?: Record<string, string>
+  /** Whether this entry was manually reviewed and approved */
+  curated?: boolean
 }
 
 export interface RegistrySearchResponse {

package/src/stash-add.ts

@@ -7,25 +7,22 @@ import type { AddResponse } from "./stash-types"
 
 export async function agentikitAdd(input: { ref: string }): Promise<AddResponse> {
   const ref = input.ref.trim()
-  if (!ref) throw new Error("Registry ref is required.")
+  if (!ref) throw new Error("Install ref or local git directory is required.")
 
   const stashDir = resolveStashDir()
   const installed = await installRegistryRef(ref)
-  const replaced = loadConfig(stashDir).registry?.installed.find((entry) => entry.id === installed.id)
-  const config = upsertInstalledRegistryEntry(
-    {
-      id: installed.id,
-      source: installed.source,
-      ref: installed.ref,
-      artifactUrl: installed.artifactUrl,
-      resolvedVersion: installed.resolvedVersion,
-      resolvedRevision: installed.resolvedRevision,
-      stashRoot: installed.stashRoot,
-      cacheDir: installed.cacheDir,
-      installedAt: installed.installedAt,
-    },
-    stashDir,
-  )
+  const replaced = loadConfig().registry?.installed.find((entry) => entry.id === installed.id)
+  const config = upsertInstalledRegistryEntry({
+    id: installed.id,
+    source: installed.source,
+    ref: installed.ref,
+    artifactUrl: installed.artifactUrl,
+    resolvedVersion: installed.resolvedVersion,
+    resolvedRevision: installed.resolvedRevision,
+    stashRoot: installed.stashRoot,
+    cacheDir: installed.cacheDir,
+    installedAt: installed.installedAt,
+  })
 
   if (replaced && replaced.cacheDir !== installed.cacheDir) {
     try {
@@ -53,7 +50,7 @@ export async function agentikitAdd(input: { ref: string }): Promise<AddResponse>
       installedAt: installed.installedAt,
     },
     config: {
-      additionalStashDirs: config.additionalStashDirs,
+      mountedStashDirs: config.mountedStashDirs,
       installedRegistryCount: config.registry?.installed.length ?? 0,
     },
     index: {

package/src/stash-clone.ts

@@ -0,0 +1,127 @@
+import fs from "node:fs"
+import path from "node:path"
+import { TYPE_DIRS } from "./asset-spec"
+import { parseAssetRef, makeAssetRef } from "./stash-ref"
+import { resolveSourcesForOrigin } from "./origin-resolve"
+import { resolveAssetPath } from "./stash-resolve"
+import { resolveStashSources, findSourceForPath, type StashSource, type StashSourceKind } from "./stash-source"
+
+export interface CloneOptions {
+  /** Source ref (e.g., npm:@scope/pkg//tool:deploy.sh) */
+  sourceRef: string
+  /** Optional new name for the cloned asset */
+  newName?: string
+  /** If true, overwrite existing asset in working stash */
+  force?: boolean
+}
+
+export interface CloneResponse {
+  source: {
+    path: string
+    sourceKind: StashSourceKind
+    registryId?: string
+  }
+  destination: {
+    path: string
+    ref: string
+  }
+  overwritten: boolean
+}
+
+export async function agentikitClone(options: CloneOptions): Promise<CloneResponse> {
+  const parsed = parseAssetRef(options.sourceRef)
+  const allSources = resolveStashSources()
+  const workingSource = allSources.find((s) => s.kind === "working")
+  if (!workingSource) {
+    throw new Error("No working stash configured. Run `akm init` first.")
+  }
+
+  const searchSources = resolveSourcesForOrigin(parsed.origin, allSources)
+
+  let sourcePath: string | undefined
+  let lastError: Error | undefined
+  for (const source of searchSources) {
+    try {
+      sourcePath = resolveAssetPath(source.path, parsed.type, parsed.name)
+      break
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err))
+    }
+  }
+  if (!sourcePath) {
+    throw lastError ?? new Error(`Source asset not found for ref: ${options.sourceRef}`)
+  }
+
+  const sourceSource = findSourceForPath(sourcePath, allSources)
+  const sourceKind = sourceSource?.kind ?? "working"
+
+  const destName = options.newName ?? parsed.name
+  const typeDir = TYPE_DIRS[parsed.type]
+  const workingDir = workingSource.path
+
+  // Guard against self-clone
+  if (parsed.type === "skill") {
+    const sourceSkillDir = path.resolve(path.dirname(sourcePath))
+    const destSkillDir = path.resolve(path.join(workingDir, typeDir, destName))
+    if (sourceSkillDir === destSkillDir) {
+      throw new Error(
+        `Source and destination are the same path. Use --name to provide a new name for the clone.`,
+      )
+    }
+  } else {
+    const resolvedSource = path.resolve(sourcePath)
+    const resolvedDest = path.resolve(path.join(workingDir, typeDir, destName))
+    if (resolvedSource === resolvedDest) {
+      throw new Error(
+        `Source and destination are the same path. Use --name to provide a new name for the clone.`,
+      )
+    }
+  }
+
+  let destPath: string
+  if (parsed.type === "skill") {
+    const sourceSkillDir = path.dirname(sourcePath)
+    const destSkillDir = path.join(workingDir, typeDir, destName)
+    const overwritten = fs.existsSync(destSkillDir)
+
+    if (overwritten && !options.force) {
+      throw new Error(
+        `Asset already exists in working stash: ${destSkillDir}. Use --force to overwrite.`,
+      )
+    }
+
+    if (overwritten) {
+      fs.rmSync(destSkillDir, { recursive: true, force: true })
+    }
+    fs.cpSync(sourceSkillDir, destSkillDir, { recursive: true })
+
+    destPath = path.join(destSkillDir, "SKILL.md")
+    const ref = makeAssetRef(parsed.type, destName, "local")
+
+    return {
+      source: { path: sourcePath, sourceKind, registryId: sourceSource?.registryId },
+      destination: { path: destPath, ref },
+      overwritten,
+    }
+  }
+
+  destPath = path.join(workingDir, typeDir, destName)
+  const overwritten = fs.existsSync(destPath)
+
+  if (overwritten && !options.force) {
+    throw new Error(
+      `Asset already exists in working stash: ${destPath}. Use --force to overwrite.`,
+    )
+  }
+
+  fs.mkdirSync(path.dirname(destPath), { recursive: true })
+  fs.copyFileSync(sourcePath, destPath)
+
+  const ref = makeAssetRef(parsed.type, destName, "local")
+
+  return {
+    source: { path: sourcePath, sourceKind, registryId: sourceSource?.registryId },
+    destination: { path: destPath, ref },
+    overwritten,
+  }
+}