agentikit 0.0.13 → 0.0.14

package/src/registry-install.ts

@@ -1,361 +0,0 @@
-import { spawnSync } from "node:child_process"
-import fs from "node:fs"
-import path from "node:path"
-import { fetchWithTimeout, isWithin, TYPE_DIRS } from "./common"
-import { loadConfig, saveConfig, type AgentikitConfig } from "./config"
-import { parseRegistryRef, resolveRegistryArtifact } from "./registry-resolve"
-import type { ParsedGitRef, RegistryInstallResult, RegistryInstalledEntry, RegistrySource } from "./registry-types"
-
-const REGISTRY_STASH_DIR_NAMES = new Set<string>(Object.values(TYPE_DIRS))
-
-export interface InstallRegistryRefOptions {
-  cacheRootDir?: string
-  now?: Date
-}
-
-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()
-  const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir()
-  const cacheDir = buildInstallCacheDir(cacheRootDir, resolved.source, resolved.id)
-  const archivePath = path.join(cacheDir, "artifact.tar.gz")
-  const extractedDir = path.join(cacheDir, "extracted")
-
-  fs.mkdirSync(cacheDir, { recursive: true })
-
-  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 {
-    id: resolved.id,
-    source: resolved.source,
-    ref: resolved.ref,
-    artifactUrl: resolved.artifactUrl,
-    resolvedVersion: resolved.resolvedVersion,
-    resolvedRevision: resolved.resolvedRevision,
-    installedAt,
-    cacheDir,
-    extractedDir,
-    stashRoot,
-  }
-}
-
-export function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry): AgentikitConfig {
-  const current = loadConfig()
-  const currentInstalled = current.registry?.installed ?? []
-  const withoutExisting = currentInstalled.filter((item) => item.id !== entry.id)
-  const nextInstalled = [...withoutExisting, normalizeInstalledEntry(entry)]
-
-  const nextConfig: AgentikitConfig = {
-    ...current,
-    registry: { installed: nextInstalled },
-  }
-  saveConfig(nextConfig)
-  return nextConfig
-}
-
-export function removeInstalledRegistryEntry(id: string): AgentikitConfig {
-  const current = loadConfig()
-  const currentInstalled = current.registry?.installed ?? []
-  const nextInstalled = currentInstalled.filter((item) => item.id !== id)
-
-  const nextConfig: AgentikitConfig = {
-    ...current,
-    registry: nextInstalled.length > 0 ? { installed: nextInstalled } : undefined,
-  }
-  saveConfig(nextConfig)
-  return nextConfig
-}
-
-export function getRegistryCacheRootDir(): string {
-  const xdgCache = process.env.XDG_CACHE_HOME?.trim()
-  if (xdgCache) {
-    return path.join(path.resolve(xdgCache), "agentikit", "registry")
-  }
-  const home = process.env.HOME?.trim()
-  if (!home) {
-    throw new Error("Unable to determine cache directory. Set XDG_CACHE_HOME or HOME.")
-  }
-  return path.join(path.resolve(home), ".cache", "agentikit", "registry")
-}
-
-export function detectStashRoot(extractedDir: string): string {
-  const root = path.resolve(extractedDir)
-
-  const rootDotStash = path.join(root, ".stash")
-  if (isDirectory(rootDotStash)) {
-    return root
-  }
-
-  if (hasStashDirs(root)) {
-    return root
-  }
-
-  const opencodeDir = path.join(root, "opencode")
-  if (hasStashDirs(opencodeDir)) {
-    return opencodeDir
-  }
-
-  const shallowest = findShallowestDotStashRoot(root)
-  if (shallowest) return shallowest
-
-  return root
-}
-
-function buildInstallCacheDir(cacheRootDir: string, source: RegistrySource, id: string): string {
-  const slug = `${source}-${id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "")}`
-  const stamp = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
-  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 fetchWithTimeout(url, undefined, 120_000)
-  if (!response.ok) {
-    throw new Error(`Failed to download archive (${response.status}) from ${url}`)
-  }
-  // 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 {
-  const listResult = spawnSync("tar", ["tzf", archivePath], { encoding: "utf8" })
-  if (listResult.status !== 0) {
-    const err = listResult.stderr?.trim() || listResult.error?.message || "unknown error"
-    throw new Error(`Failed to inspect archive ${archivePath}: ${err}`)
-  }
-
-  validateTarEntries(listResult.stdout)
-
-  fs.rmSync(destinationDir, { recursive: true, force: true })
-  fs.mkdirSync(destinationDir, { recursive: true })
-
-  const extractResult = spawnSync("tar", ["xzf", archivePath, "--strip-components=1", "-C", destinationDir], {
-    encoding: "utf8",
-  })
-  if (extractResult.status !== 0) {
-    const err = extractResult.stderr?.trim() || extractResult.error?.message || "unknown error"
-    throw new Error(`Failed to extract archive ${archivePath}: ${err}`)
-  }
-}
-
-function validateTarEntries(listOutput: string): void {
-  const lines = listOutput.split(/\r?\n/).filter(Boolean)
-  for (const rawLine of lines) {
-    const entry = rawLine.trim()
-    if (!entry || entry.includes("\0")) {
-      throw new Error(`Archive contains an invalid entry: ${JSON.stringify(rawLine)}`)
-    }
-    if (entry.startsWith("/")) {
-      throw new Error(`Archive contains an absolute path entry: ${entry}`)
-    }
-
-    const normalized = path.posix.normalize(entry)
-    if (normalized === ".." || normalized.startsWith("../")) {
-      throw new Error(`Archive contains a path traversal entry: ${entry}`)
-    }
-
-    const parts = normalized.split("/").filter(Boolean)
-    const stripped = parts.slice(1).join("/")
-    if (!stripped) continue
-    const normalizedStripped = path.posix.normalize(stripped)
-    if (normalizedStripped === ".." || normalizedStripped.startsWith("../") || path.posix.isAbsolute(normalizedStripped)) {
-      throw new Error(`Archive contains an unsafe entry after strip-components: ${entry}`)
-    }
-  }
-}
-
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
-
-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 })
-  return entries.some((entry) => entry.isDirectory() && REGISTRY_STASH_DIR_NAMES.has(entry.name))
-}
-
-function findShallowestDotStashRoot(root: string): string | undefined {
-  const queue: string[] = [root]
-  while (queue.length > 0) {
-    const current = queue.shift()!
-    const dotStash = path.join(current, ".stash")
-    if (isDirectory(dotStash)) {
-      return current
-    }
-    let children: fs.Dirent[]
-    try {
-      children = fs.readdirSync(current, { withFileTypes: true })
-    } catch {
-      continue
-    }
-    for (const child of children) {
-      if (!child.isDirectory()) continue
-      if (child.name === ".git" || child.name === "node_modules") continue
-      queue.push(path.join(current, child.name))
-    }
-  }
-  return undefined
-}
-
-function normalizeInstalledEntry(entry: RegistryInstalledEntry): RegistryInstalledEntry {
-  return {
-    ...entry,
-    stashRoot: path.resolve(entry.stashRoot),
-    cacheDir: path.resolve(entry.cacheDir),
-  }
-}
-

package/src/registry-resolve.ts

@@ -1,341 +0,0 @@
-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
-}
-