agentikit 0.0.9 → 0.0.12

package/src/origin-resolve.ts

@@ -0,0 +1,67 @@
+import path from "node:path"
+import type { StashSource } from "./stash-source"
+import { parseRegistryRef } from "./registry-resolve"
+
+/**
+ * Given an origin string (from an AssetRef) and the full list of stash
+ * sources, return the subset of sources to search.
+ *
+ * Resolution order:
+ *   1. undefined   → all sources (working → mounted → installed)
+ *   2. "local"     → working stash only
+ *   3. exact match → installed source whose registryId matches verbatim
+ *   4. parsed match → parse origin as a registry ref, match by parsed ID
+ *   5. path match  → mounted source whose path matches
+ *   6. empty       → indicates a remote/uninstalled origin (caller decides)
+ */
+export function resolveSourcesForOrigin(
+  origin: string | undefined,
+  allSources: StashSource[],
+): StashSource[] {
+  if (!origin) return allSources
+
+  if (origin === "local") {
+    return allSources.filter((s) => s.kind === "working")
+  }
+
+  // Exact registryId match (e.g. origin is "npm:@scope/pkg")
+  const byExactId = allSources.filter(
+    (s) => s.kind === "installed" && s.registryId === origin,
+  )
+  if (byExactId.length > 0) return byExactId
+
+  // Parse origin as a registry ref and match by parsed ID.
+  // Allows shorthand: "owner/repo" matches "github:owner/repo",
+  // "@scope/pkg" matches "npm:@scope/pkg".
+  try {
+    const parsed = parseRegistryRef(origin)
+    const byParsedId = allSources.filter(
+      (s) => s.kind === "installed" && s.registryId === parsed.id,
+    )
+    if (byParsedId.length > 0) return byParsedId
+  } catch {
+    // Not a valid registry ref — continue to path matching
+  }
+
+  // Mounted stash by resolved path
+  const resolvedOrigin = path.resolve(origin)
+  const byPath = allSources.filter(
+    (s) => s.kind === "mounted" && path.resolve(s.path) === resolvedOrigin,
+  )
+  if (byPath.length > 0) return byPath
+
+  // No match — origin may be remote/uninstalled
+  return []
+}
+
+/**
+ * Check whether an origin refers to something that could be fetched remotely
+ * (i.e. it looks like a registry ref but isn't installed locally).
+ */
+export function isRemoteOrigin(
+  origin: string,
+  allSources: StashSource[],
+): boolean {
+  if (origin === "local") return false
+  return resolveSourcesForOrigin(origin, allSources).length === 0
+}

package/src/registry-install.ts

@@ -1,10 +1,10 @@
 import { spawnSync } from "node:child_process"
 import fs from "node:fs"
 import path from "node:path"
-import { TYPE_DIRS } from "./common"
+import { fetchWithTimeout, isWithin, TYPE_DIRS } from "./common"
 import { loadConfig, saveConfig, type AgentikitConfig } from "./config"
 import { parseRegistryRef, resolveRegistryArtifact } from "./registry-resolve"
-import type { RegistryInstallResult, RegistryInstalledEntry, RegistrySource } from "./registry-types"
+import type { ParsedGitRef, RegistryInstallResult, RegistryInstalledEntry, RegistrySource } from "./registry-types"
 
 const REGISTRY_STASH_DIR_NAMES = new Set<string>(Object.values(TYPE_DIRS))
 
@@ -15,6 +15,9 @@ export interface InstallRegistryRefOptions {
 
 export async function installRegistryRef(ref: string, options?: InstallRegistryRefOptions): Promise<RegistryInstallResult> {
   const parsed = parseRegistryRef(ref)
+  if (parsed.source === "git") {
+    return installGitRegistryRef(parsed, options)
+  }
   const resolved = await resolveRegistryArtifact(parsed)
 
   const installedAt = (options?.now ?? new Date()).toISOString()
@@ -28,6 +31,42 @@ export async function installRegistryRef(ref: string, options?: InstallRegistryR
   await downloadArchive(resolved.artifactUrl, archivePath)
   extractTarGzSecure(archivePath, extractedDir)
 
+  const provisionalKitRoot = detectStashRoot(extractedDir)
+  const installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot
+  const stashRoot = detectStashRoot(installRoot)
+
+  return {
+    id: resolved.id,
+    source: resolved.source,
+    ref: resolved.ref,
+    artifactUrl: resolved.artifactUrl,
+    resolvedVersion: resolved.resolvedVersion,
+    resolvedRevision: resolved.resolvedRevision,
+    installedAt,
+    cacheDir,
+    extractedDir,
+    stashRoot,
+  }
+}
+
+async function installGitRegistryRef(parsed: ParsedGitRef, options?: InstallRegistryRefOptions): Promise<RegistryInstallResult> {
+  const resolved = await resolveRegistryArtifact(parsed)
+  const installedAt = (options?.now ?? new Date()).toISOString()
+  const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir()
+  const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id)
+  const extractedDir = path.join(cacheDir, "extracted")
+
+  fs.mkdirSync(cacheDir, { recursive: true })
+  fs.rmSync(extractedDir, { recursive: true, force: true })
+  fs.mkdirSync(extractedDir, { recursive: true })
+
+  const includeConfig = findNearestAgentikitIncludeConfig(parsed.sourcePath, parsed.repoRoot)
+  if (includeConfig) {
+    copyIncludedPaths(includeConfig.baseDir, includeConfig.include, extractedDir)
+  } else {
+    copyDirectoryContents(parsed.sourcePath, extractedDir)
+  }
+
   const stashRoot = detectStashRoot(extractedDir)
 
   return {
@@ -44,49 +83,30 @@ export async function installRegistryRef(ref: string, options?: InstallRegistryR
   }
 }
 
-export function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry, stashDir?: string): AgentikitConfig {
-  const current = loadConfig(stashDir)
+export function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry): AgentikitConfig {
+  const current = loadConfig()
   const currentInstalled = current.registry?.installed ?? []
-  const previousRegistryRoots = new Set(currentInstalled.map((item) => path.resolve(item.stashRoot)))
-
   const withoutExisting = currentInstalled.filter((item) => item.id !== entry.id)
   const nextInstalled = [...withoutExisting, normalizeInstalledEntry(entry)]
-  const nextRegistryRoots = new Set(nextInstalled.map((item) => path.resolve(item.stashRoot)))
-  const preservedAdditional = current.additionalStashDirs.filter(
-    (dir) => !previousRegistryRoots.has(path.resolve(dir)),
-  )
-  const syncedAdditional = uniquePaths([...preservedAdditional, ...nextRegistryRoots])
 
   const nextConfig: AgentikitConfig = {
     ...current,
-    additionalStashDirs: syncedAdditional,
-    registry: {
-      installed: nextInstalled,
-    },
+    registry: { installed: nextInstalled },
   }
-  saveConfig(nextConfig, stashDir)
+  saveConfig(nextConfig)
   return nextConfig
 }
 
-export function removeInstalledRegistryEntry(id: string, stashDir?: string): AgentikitConfig {
-  const current = loadConfig(stashDir)
+export function removeInstalledRegistryEntry(id: string): AgentikitConfig {
+  const current = loadConfig()
   const currentInstalled = current.registry?.installed ?? []
-  const previousRegistryRoots = new Set(currentInstalled.map((item) => path.resolve(item.stashRoot)))
-
   const nextInstalled = currentInstalled.filter((item) => item.id !== id)
-  const nextRegistryRoots = new Set(nextInstalled.map((item) => path.resolve(item.stashRoot)))
-
-  const preservedAdditional = current.additionalStashDirs.filter(
-    (dir) => !previousRegistryRoots.has(path.resolve(dir)),
-  )
-  const syncedAdditional = uniquePaths([...preservedAdditional, ...nextRegistryRoots])
 
   const nextConfig: AgentikitConfig = {
     ...current,
-    additionalStashDirs: syncedAdditional,
     registry: nextInstalled.length > 0 ? { installed: nextInstalled } : undefined,
   }
-  saveConfig(nextConfig, stashDir)
+  saveConfig(nextConfig)
   return nextConfig
 }
 
@@ -131,13 +151,37 @@ function buildInstallCacheDir(cacheRootDir: string, source: RegistrySource, id:
   return path.join(cacheRootDir, slug || source, stamp)
 }
 
+function applyAgentikitIncludeConfig(
+  sourceRoot: string,
+  cacheDir: string,
+  searchRoot: string = sourceRoot,
+): string | undefined {
+  const includeConfig = findNearestAgentikitIncludeConfig(sourceRoot, searchRoot)
+  if (!includeConfig) return undefined
+
+  const selectedDir = path.join(cacheDir, "selected")
+  fs.rmSync(selectedDir, { recursive: true, force: true })
+  fs.mkdirSync(selectedDir, { recursive: true })
+  copyIncludedPaths(includeConfig.baseDir, includeConfig.include, selectedDir)
+  return selectedDir
+}
+
 async function downloadArchive(url: string, destination: string): Promise<void> {
-  const response = await fetch(url)
+  const response = await fetchWithTimeout(url, undefined, 120_000)
   if (!response.ok) {
     throw new Error(`Failed to download archive (${response.status}) from ${url}`)
   }
-  const arrayBuffer = await response.arrayBuffer()
-  fs.writeFileSync(destination, Buffer.from(arrayBuffer))
+  // Stream response to disk instead of buffering the entire archive in memory.
+  // Uses Bun.write which handles Response streaming natively.
+  const BunRuntime: { write(path: string, body: Response): Promise<number> } =
+    (globalThis as Record<string, unknown>).Bun as typeof BunRuntime
+  if (BunRuntime?.write) {
+    await BunRuntime.write(destination, response)
+  } else {
+    // Fallback for non-Bun environments (e.g., tests)
+    const arrayBuffer = await response.arrayBuffer()
+    fs.writeFileSync(destination, Buffer.from(arrayBuffer))
+  }
 }
 
 function extractTarGzSecure(archivePath: string, destinationDir: string): void {
@@ -195,6 +239,89 @@ function isDirectory(target: string): boolean {
   }
 }
 
+function readAgentikitIncludeConfigAtDir(dirPath: string): { baseDir: string; include: string[] } | undefined {
+  const packageJsonPath = path.join(dirPath, "package.json")
+  if (!fs.existsSync(packageJsonPath)) return undefined
+
+  let pkg: unknown
+  try {
+    pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"))
+  } catch {
+    return undefined
+  }
+  if (typeof pkg !== "object" || pkg === null || Array.isArray(pkg)) return undefined
+
+  const agentikit = (pkg as Record<string, unknown>).agentikit
+  if (typeof agentikit !== "object" || agentikit === null || Array.isArray(agentikit)) return undefined
+
+  const include = (agentikit as Record<string, unknown>).include
+  if (!Array.isArray(include)) return undefined
+
+  const parsedInclude = include
+    .filter((value): value is string => typeof value === "string")
+    .map((value) => value.trim())
+    .filter(Boolean)
+
+  return parsedInclude.length > 0 ? { baseDir: dirPath, include: parsedInclude } : undefined
+}
+
+function findNearestAgentikitIncludeConfig(
+  startDir: string,
+  stopDir: string,
+): { baseDir: string; include: string[] } | undefined {
+  let current = path.resolve(startDir)
+  const boundary = path.resolve(stopDir)
+
+  while (isWithin(current, boundary)) {
+    const config = readAgentikitIncludeConfigAtDir(current)
+    if (config) return config
+    if (current === boundary) break
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+
+  return undefined
+}
+
+function copyIncludedPaths(baseDir: string, include: string[], destinationDir: string): void {
+  for (const entry of include) {
+    const resolvedSource = path.resolve(baseDir, entry)
+    if (!isWithin(resolvedSource, baseDir)) {
+      throw new Error(`Path in agentikit.include escapes the package root: ${entry}`)
+    }
+    if (!fs.existsSync(resolvedSource)) {
+      throw new Error(`Path in agentikit.include does not exist: ${entry}`)
+    }
+    if (path.basename(resolvedSource) === ".git") {
+      continue
+    }
+    const relativePath = path.relative(baseDir, resolvedSource)
+    if (!relativePath || relativePath === ".") {
+      copyDirectoryContents(baseDir, destinationDir)
+      continue
+    }
+    copyPath(resolvedSource, path.join(destinationDir, relativePath))
+  }
+}
+
+function copyDirectoryContents(sourceDir: string, destinationDir: string): void {
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    if (entry.name === ".git") continue
+    copyPath(path.join(sourceDir, entry.name), path.join(destinationDir, entry.name))
+  }
+}
+
+function copyPath(sourcePath: string, destinationPath: string): void {
+  const stat = fs.statSync(sourcePath)
+  fs.mkdirSync(path.dirname(destinationPath), { recursive: true })
+  if (stat.isDirectory()) {
+    fs.cpSync(sourcePath, destinationPath, { recursive: true, force: true })
+    return
+  }
+  fs.copyFileSync(sourcePath, destinationPath)
+}
+
 function hasStashDirs(dirPath: string): boolean {
   if (!isDirectory(dirPath)) return false
   const entries = fs.readdirSync(dirPath, { withFileTypes: true })
@@ -232,14 +359,3 @@ function normalizeInstalledEntry(entry: RegistryInstalledEntry): RegistryInstall
   }
 }
 
-function uniquePaths(paths: Iterable<string>): string[] {
-  const seen = new Set<string>()
-  const result: string[] = []
-  for (const candidate of paths) {
-    const normalized = path.resolve(candidate)
-    if (seen.has(normalized)) continue
-    seen.add(normalized)
-    result.push(normalized)
-  }
-  return result
-}

package/src/registry-resolve.ts

@@ -1,6 +1,10 @@
-import type { ParsedGithubRef, ParsedNpmRef, ParsedRegistryRef, ResolvedRegistryArtifact } from "./registry-types"
-
-const GITHUB_API_BASE = "https://api.github.com"
+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()
@@ -15,6 +19,10 @@ export function parseRegistryRef(rawRef: string): ParsedRegistryRef {
   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)
@@ -27,6 +35,9 @@ export async function resolveRegistryArtifact(parsed: ParsedRegistryRef): Promis
   if (parsed.source === "npm") {
     return resolveNpmArtifact(parsed)
   }
+  if (parsed.source === "git") {
+    return resolveGitArtifact(parsed)
+  }
   return resolveGithubArtifact(parsed)
 }
 
@@ -96,6 +107,45 @@ function parseGithubUrl(rawUrl: string): ParsedGithubRef {
   }
 }
 
+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}`)
@@ -197,6 +247,17 @@ async function resolveGithubArtifact(parsed: ParsedGithubRef): Promise<ResolvedR
   }
 }
 
+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)
@@ -220,8 +281,16 @@ function splitNpmNameAndVersion(input: string): { packageName: string; requested
 }
 
 function validateNpmPackageName(name: string): void {
-  if (!name || name.includes(" ")) {
-    throw new Error(`Invalid npm package name: \"${name}\".`)
+  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.`)
   }
 }
 
@@ -237,18 +306,27 @@ function splitRefSuffix(value: string): [string, string | 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",
+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
   }
-  if (token) headers.Authorization = `Bearer ${token}`
-  return headers
+}
+
+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 fetch(url, { headers })
+  const response = await fetchWithTimeout(url, { headers })
   if (!response.ok) {
     throw new Error(`Request failed (${response.status}) for ${url}`)
   }
@@ -256,17 +334,8 @@ async function fetchJson<T>(url: string, headers?: HeadersInit): Promise<T> {
 }
 
 async function tryFetchJson<T>(url: string, headers?: HeadersInit): Promise<T | null> {
-  const response = await fetch(url, { headers })
+  const response = await fetchWithTimeout(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
-}