agentikit 0.0.8 → 0.0.12

package/src/asset-type-handler.ts

@@ -0,0 +1,77 @@
+import type { StashEntry } from "./metadata"
+import type { LocalSearchHit, ShowResponse, KnowledgeView } from "./stash-types"
+
+// ── Interface ────────────────────────────────────────────────────────────────
+
+export interface ShowInput {
+  name: string
+  path: string
+  content: string
+  view?: KnowledgeView
+  stashDirs?: string[]
+}
+
+export interface AssetTypeHandler {
+  /** The type name, e.g. "tool", "script" */
+  readonly typeName: string
+  /** Directory inside the stash root, e.g. "tools", "scripts" */
+  readonly stashDir: string
+
+  // -- File system spec --
+  isRelevantFile(fileName: string): boolean
+  toCanonicalName(typeRoot: string, filePath: string): string | undefined
+  toAssetPath(typeRoot: string, name: string): string
+
+  // -- Show behavior --
+  buildShowResponse(input: ShowInput): ShowResponse
+
+  // -- Search enrichment --
+  enrichSearchHit?(hit: LocalSearchHit, stashDir: string): void
+
+  // -- Usage guide --
+  readonly defaultUsageGuide: string[]
+
+  // -- Metadata generation hooks --
+  extractTypeMetadata?(entry: StashEntry, file: string, ext: string): void
+}
+
+// ── Registry ─────────────────────────────────────────────────────────────────
+
+const handlers = new Map<string, AssetTypeHandler>()
+
+let handlersInitialized = false
+
+function ensureHandlersRegistered(): void {
+  if (handlersInitialized) return
+  handlersInitialized = true
+  // Import handler registrations
+  require("./handlers/index")
+}
+
+export function registerAssetType(handler: AssetTypeHandler): void {
+  handlers.set(handler.typeName, handler)
+}
+
+export function getHandler(type: string): AssetTypeHandler {
+  ensureHandlersRegistered()
+  const handler = handlers.get(type)
+  if (!handler) {
+    throw new Error(`Unknown asset type: "${type}"`)
+  }
+  return handler
+}
+
+export function tryGetHandler(type: string): AssetTypeHandler | undefined {
+  ensureHandlersRegistered()
+  return handlers.get(type)
+}
+
+export function getAllHandlers(): AssetTypeHandler[] {
+  ensureHandlersRegistered()
+  return Array.from(handlers.values())
+}
+
+export function getRegisteredTypeNames(): string[] {
+  ensureHandlersRegistered()
+  return Array.from(handlers.keys())
+}

package/src/cli.ts

@@ -1,16 +1,39 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty"
-import { agentikitSearch, agentikitShow, type KnowledgeView } from "./stash"
+import {
+  agentikitAdd,
+  agentikitList,
+  agentikitReinstall,
+  agentikitRemove,
+  agentikitSearch,
+  agentikitShow,
+  agentikitUpdate,
+  type KnowledgeView,
+} from "./stash"
+import type { SearchSource, SearchUsageMode } from "./stash-types"
 import { agentikitInit } from "./init"
 import { agentikitIndex } from "./indexer"
-import { loadConfig, updateConfig, type AgentikitConfig } from "./config"
-import { resolveStashDir } from "./common"
+import { agentikitClone } from "./stash-clone"
+
+import { resolveStashSources } from "./stash-source"
+import { loadConfig, saveConfig } from "./config"
+import {
+  getConfigValue,
+  listConfig,
+  listProviders,
+  parseConfigValue,
+  setConfigValue,
+  unsetConfigValue,
+  useProvider,
+} from "./config-cli"
 
 const initCommand = defineCommand({
-  meta: { name: "init", description: "Initialize agentikit stash directory and set AGENTIKIT_STASH_DIR" },
-  run() {
-    const result = agentikitInit()
-    console.log(JSON.stringify(result, null, 2))
+  meta: { name: "init", description: "Initialize Agent-i-Kit's working stash directory and set AKM_STASH_DIR" },
+  async run() {
+    await runWithJsonErrors(async () => {
+      const result = await agentikitInit()
+      console.log(JSON.stringify(result, null, 2))
+    })
   },
 })
 
@@ -20,8 +43,10 @@ const indexCommand = defineCommand({
     full: { type: "boolean", description: "Force full reindex", default: false },
   },
   async run({ args }) {
-    const result = await agentikitIndex({ full: args.full })
-    console.log(JSON.stringify(result, null, 2))
+    await runWithJsonErrors(async () => {
+      const result = await agentikitIndex({ full: args.full })
+      console.log(JSON.stringify(result, null, 2))
+    })
   },
 })
 
@@ -29,13 +54,82 @@ const searchCommand = defineCommand({
   meta: { name: "search", description: "Search the stash" },
   args: {
     query: { type: "positional", description: "Search query", required: false, default: "" },
-    type: { type: "string", description: "Asset type filter (tool|skill|command|agent|knowledge|any)" },
+    type: { type: "string", description: "Asset type filter (tool|skill|command|agent|knowledge|script|any)" },
     limit: { type: "string", description: "Maximum number of results" },
+    usage: { type: "string", description: "Usage metadata mode (none|both|item|guide)", default: "both" },
+    source: { type: "string", description: "Search source (local|registry|both)", default: "local" },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      const type = args.type as "tool" | "skill" | "command" | "agent" | "knowledge" | "script" | "any" | undefined
+      const limit = args.limit ? parseInt(args.limit, 10) : undefined
+      const usage = parseSearchUsageMode(args.usage)
+      const source = parseSearchSource(args.source)
+      console.log(JSON.stringify(await agentikitSearch({ query: args.query, type, limit, usage, source }), null, 2))
+    })
+  },
+})
+
+const addCommand = defineCommand({
+  meta: { name: "add", description: "Install a registry package or local git directory into the stash" },
+  args: {
+    ref: {
+      type: "positional",
+      description: "Registry ref (npm package, owner/repo, github URL, or local git directory)",
+      required: true,
+    },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitAdd({ ref: args.ref }), null, 2))
+    })
+  },
+})
+
+const listCommand = defineCommand({
+  meta: { name: "list", description: "List installed registry packages from config" },
+  async run() {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitList(), null, 2))
+    })
+  },
+})
+
+const removeCommand = defineCommand({
+  meta: { name: "remove", description: "Remove an installed registry package by id or ref" },
+  args: {
+    target: { type: "positional", description: "Installed target (id or ref)", required: true },
   },
   async run({ args }) {
-    const type = args.type as "tool" | "skill" | "command" | "agent" | "knowledge" | "any" | undefined
-    const limit = args.limit ? parseInt(args.limit, 10) : undefined
-    console.log(JSON.stringify(await agentikitSearch({ query: args.query, type, limit }), null, 2))
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitRemove({ target: args.target }), null, 2))
+    })
+  },
+})
+
+const updateCommand = defineCommand({
+  meta: { name: "update", description: "Update one or all installed registry packages" },
+  args: {
+    target: { type: "positional", description: "Installed target (id or ref)", required: false },
+    all: { type: "boolean", description: "Update all installed entries", default: false },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitUpdate({ target: args.target, all: args.all }), null, 2))
+    })
+  },
+})
+
+const reinstallCommand = defineCommand({
+  meta: { name: "reinstall", description: "Reinstall one or all installed registry packages" },
+  args: {
+    target: { type: "positional", description: "Installed target (id or ref)", required: false },
+    all: { type: "boolean", description: "Reinstall all installed entries", default: false },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitReinstall({ target: args.target, all: args.all }), null, 2))
+    })
   },
 })
 
@@ -48,129 +142,286 @@ const showCommand = defineCommand({
     start: { type: "string", description: "Start line (for --view lines)" },
     end: { type: "string", description: "End line (for --view lines)" },
   },
-  run({ args }) {
-    let view: KnowledgeView | undefined
-    if (args.view) {
-      switch (args.view) {
-        case "section":
-          view = { mode: "section", heading: args.heading ?? "" }
-          break
-        case "lines":
-          view = {
-            mode: "lines",
-            start: Number(args.start ?? "1"),
-            end: args.end ? parseInt(args.end, 10) : Number.MAX_SAFE_INTEGER,
-          }
-          break
-        case "toc":
-        case "frontmatter":
-        case "full":
-          view = { mode: args.view }
-          break
-        default:
-          console.error(`Unknown view mode: ${args.view}`)
-          process.exit(1)
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      let view: KnowledgeView | undefined
+      if (args.view) {
+        switch (args.view) {
+          case "section":
+            view = { mode: "section", heading: args.heading ?? "" }
+            break
+          case "lines":
+            view = {
+              mode: "lines",
+              start: Number(args.start ?? "1"),
+              end: args.end ? parseInt(args.end, 10) : Number.MAX_SAFE_INTEGER,
+            }
+            break
+          case "toc":
+          case "frontmatter":
+          case "full":
+            view = { mode: args.view }
+            break
+          default:
+            throw new Error(`Unknown view mode: ${args.view}. Expected one of: full|toc|frontmatter|section|lines`)
+        }
       }
-    }
-    console.log(JSON.stringify(agentikitShow({ ref: args.ref, view }), null, 2))
+      console.log(JSON.stringify(await agentikitShow({ ref: args.ref, view }), null, 2))
+    })
   },
 })
 
 const configCommand = defineCommand({
-  meta: { name: "config", description: "Show or update configuration" },
+  meta: { name: "config", description: "Show configuration, get/set keys, and manage embedding/LLM providers" },
   args: {
-    set: { type: "string", description: "Update a config key (key=value format)" },
+    list: { type: "boolean", description: "List current configuration with effective defaults", default: false },
+    get: { type: "string", description: "Get a configuration value by key" },
+    unset: { type: "string", description: "Unset an optional configuration key or whole embedding/llm section" },
+    set: { type: "string", description: "Back-compat alias for updating a key (key=value format)" },
+  },
+  subCommands: {
+    list: defineCommand({
+      meta: { name: "list", description: "List current configuration with effective embedding/LLM settings" },
+      run() {
+        return runWithJsonErrors(() => {
+          console.log(JSON.stringify(listConfig(loadConfig()), null, 2))
+        })
+      },
+    }),
+    get: defineCommand({
+      meta: { name: "get", description: "Get a configuration value by key" },
+      args: {
+        key: { type: "positional", required: true, description: "Config key (for example: embedding.provider)" },
+      },
+      run({ args }) {
+        return runWithJsonErrors(() => {
+          console.log(JSON.stringify(getConfigValue(loadConfig(), args.key), null, 2))
+        })
+      },
+    }),
+    set: defineCommand({
+      meta: { name: "set", description: "Set a configuration value by key" },
+      args: {
+        key: { type: "positional", required: true, description: "Config key (for example: llm.temperature)" },
+        value: { type: "positional", required: true, description: "Config value" },
+      },
+      run({ args }) {
+        return runWithJsonErrors(() => {
+          const updated = setConfigValue(loadConfig(), args.key, args.value)
+          saveConfig(updated)
+          console.log(JSON.stringify(listConfig(updated), null, 2))
+        })
+      },
+    }),
+    unset: defineCommand({
+      meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/llm section" },
+      args: {
+        key: { type: "positional", required: true, description: "Config key to unset" },
+      },
+      run({ args }) {
+        return runWithJsonErrors(() => {
+          const updated = unsetConfigValue(loadConfig(), args.key)
+          saveConfig(updated)
+          console.log(JSON.stringify(listConfig(updated), null, 2))
+        })
+      },
+    }),
+    providers: defineCommand({
+      meta: { name: "providers", description: "List available embedding or LLM providers" },
+      args: {
+        scope: { type: "positional", required: true, description: "Provider scope: embedding or llm" },
+      },
+      run({ args }) {
+        return runWithJsonErrors(() => {
+          const scope = parseProviderScope(args.scope)
+          console.log(JSON.stringify(listProviders(scope, loadConfig()), null, 2))
+        })
+      },
+    }),
+    use: defineCommand({
+      meta: { name: "use", description: "Switch the default embedding or LLM provider" },
+      args: {
+        scope: { type: "positional", required: true, description: "Provider scope: embedding or llm" },
+        provider: { type: "positional", required: true, description: "Provider name" },
+      },
+      run({ args }) {
+        return runWithJsonErrors(() => {
+          const scope = parseProviderScope(args.scope)
+          const updated = useProvider(loadConfig(), scope, args.provider)
+          saveConfig(updated)
+          console.log(JSON.stringify(listConfig(updated), null, 2))
+        })
+      },
+    }),
   },
   run({ args }) {
-    const stashDir = resolveStashDir()
-
-    if (args.set) {
-      const eqIndex = args.set.indexOf("=")
-      if (eqIndex === -1) {
-        console.error("Error: --set expects key=value format")
-        process.exit(1)
+    return runWithJsonErrors(() => {
+      if (hasConfigSubcommand(args)) return
+      if (args.list) {
+        console.log(JSON.stringify(listConfig(loadConfig()), null, 2))
+        return
+      }
+      if (args.get) {
+        console.log(JSON.stringify(getConfigValue(loadConfig(), args.get), null, 2))
+        return
+      }
+      if (args.unset) {
+        const updated = unsetConfigValue(loadConfig(), args.unset)
+        saveConfig(updated)
+        console.log(JSON.stringify(listConfig(updated), null, 2))
+        return
+      }
+      if (args.set) {
+        const eqIndex = args.set.indexOf("=")
+        if (eqIndex === -1) {
+          throw new Error("--set expects key=value format")
+        }
+        const key = args.set.slice(0, eqIndex)
+        const value = args.set.slice(eqIndex + 1)
+        const partial = parseConfigValue(key, value)
+        const config = { ...loadConfig(), ...partial }
+        saveConfig(config)
+        console.log(JSON.stringify(listConfig(config), null, 2))
+      } else {
+        console.log(JSON.stringify(listConfig(loadConfig()), null, 2))
       }
-      const key = args.set.slice(0, eqIndex)
-      const value = args.set.slice(eqIndex + 1)
-      const partial = parseConfigValue(key, value)
-      const config = updateConfig(partial, stashDir)
-      console.log(JSON.stringify(config, null, 2))
-    } else {
-      const config = loadConfig(stashDir)
-      console.log(JSON.stringify(config, null, 2))
-    }
+    })
+  },
+})
+
+const cloneCommand = defineCommand({
+  meta: { name: "clone", description: "Clone an asset from any stash source into the working stash" },
+  args: {
+    ref: { type: "positional", description: "Asset ref (e.g. @installed:pkg/tool:script.sh)", required: true },
+    name: { type: "string", description: "New name for the cloned asset" },
+    force: { type: "boolean", description: "Overwrite if asset already exists in working stash", default: false },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      const result = await agentikitClone({
+        sourceRef: args.ref,
+        newName: args.name,
+        force: args.force,
+      })
+      console.log(JSON.stringify(result, null, 2))
+    })
+  },
+})
+
+
+const sourcesCommand = defineCommand({
+  meta: { name: "sources", description: "List all stash sources with their kind, path, and status" },
+  run() {
+    return runWithJsonErrors(() => {
+      const sources = resolveStashSources()
+      console.log(JSON.stringify({ sources }, null, 2))
+    })
   },
 })
 
 const main = defineCommand({
   meta: {
     name: "akm",
-    description: "CLI tool to search, open, and run extension assets from an agentikit stash directory.",
+    description: "CLI tool to search, open, and manage assets from Agent-i-Kit stash.",
   },
   subCommands: {
     init: initCommand,
     index: indexCommand,
+    add: addCommand,
+    list: listCommand,
+    remove: removeCommand,
+    update: updateCommand,
+    reinstall: reinstallCommand,
     search: searchCommand,
     show: showCommand,
+    clone: cloneCommand,
+    sources: sourcesCommand,
     config: configCommand,
   },
 })
 
+const SEARCH_USAGE_MODES: SearchUsageMode[] = ["none", "both", "item", "guide"]
+const SEARCH_SOURCES: SearchSource[] = ["local", "registry", "both"]
+const CONFIG_SUBCOMMAND_SET = new Set(["list", "get", "set", "unset", "providers", "use"])
+
+// Note: citty reads process.argv directly, so we must normalize it in-place.
+// This is done once at startup before runMain.
+normalizeConfigArgv(process.argv)
 runMain(main)
 
-function parseConnectionValue(
-  key: string,
-  value: string,
-  exampleEndpoint: string,
-  exampleModel: string,
-): { endpoint: string; model: string; apiKey?: string } | undefined {
-  if (value === "null" || value === "") return undefined
-  let parsed: unknown
+function parseSearchUsageMode(value: string): SearchUsageMode {
+  if ((SEARCH_USAGE_MODES as string[]).includes(value)) return value as SearchUsageMode
+  throw new Error(`Invalid value for --usage: ${value}. Expected one of: ${SEARCH_USAGE_MODES.join("|")}`)
+}
+
+function parseSearchSource(value: string): SearchSource {
+  if ((SEARCH_SOURCES as string[]).includes(value)) return value as SearchSource
+  throw new Error(`Invalid value for --source: ${value}. Expected one of: ${SEARCH_SOURCES.join("|")}`)
+}
+
+async function runWithJsonErrors(fn: (() => void) | (() => Promise<void>)): Promise<void> {
   try {
-    parsed = JSON.parse(value)
-  } catch {
-    throw new Error(
-      `Invalid value for ${key}: expected JSON object with endpoint and model`
-      + ` (e.g. '{"endpoint":"${exampleEndpoint}","model":"${exampleModel}"}')`,
-    )
+    await fn()
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    const hint = buildHint(message)
+    console.error(JSON.stringify({ ok: false, error: message, hint }, null, 2))
+    process.exit(1)
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`Invalid value for ${key}: expected a JSON object`)
+}
+
+function buildHint(message: string): string | undefined {
+  if (message.includes("AKM_STASH_DIR")) return "Run `akm init` or set AKM_STASH_DIR to a valid directory."
+  if (message.includes("Either <target> or --all is required")) return "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg`."
+  if (message.includes("Specify either <target> or --all")) return "Use only one: a positional target or `--all`."
+  if (message.includes("No installed registry entry matched target")) return "Run `akm list` to view installed ids/refs, then retry with one of those values."
+  if (message.includes("Invalid value for --source")) return "Pick one of: local, registry, both."
+  if (message.includes("Invalid value for --usage")) return "Pick one of: none, both, item, guide."
+  if (message.includes("expected JSON object with endpoint and model")) {
+    return "Quote JSON values in your shell, for example: akm config set embedding '{\"endpoint\":\"http://localhost:11434/v1/embeddings\",\"model\":\"nomic-embed-text\"}'."
   }
-  const obj = parsed as Record<string, unknown>
-  if (typeof obj.endpoint !== "string" || !obj.endpoint || typeof obj.model !== "string" || !obj.model) {
-    throw new Error(`Invalid value for ${key}: "endpoint" and "model" are required string fields`)
+  return undefined
+}
+
+function parseProviderScope(value: string): "embedding" | "llm" {
+  if (value === "embedding" || value === "llm") return value
+  throw new Error(`Invalid provider scope: ${value}. Expected one of: embedding|llm`)
+}
+
+function hasConfigSubcommand(args: Record<string, unknown>): boolean {
+  const command = Array.isArray(args._) ? args._[0] : undefined
+  return typeof command === "string" && CONFIG_SUBCOMMAND_SET.has(command)
+}
+
+/**
+ * Mutate argv before citty parses it so git-style config forms like
+ * `akm config llm.maxTokens 512` and `akm config --get llm.maxTokens`
+ * are normalized into the existing config subcommands.
+ */
+function normalizeConfigArgv(argv: string[]): void {
+  const [, , command, argAfterCommand, argAfterKey, ...rest] = argv
+  if (command !== "config") return
+  if (!argAfterCommand) return
+  if (argAfterCommand === "--list") {
+    argv.splice(3, argv.length - 3, "list")
+    return
   }
-  const result: { endpoint: string; model: string; apiKey?: string } = {
-    endpoint: obj.endpoint,
-    model: obj.model,
+  if (argAfterCommand === "--get" && argAfterKey) {
+    argv.splice(3, argv.length - 3, "get", argAfterKey, ...rest)
+    return
   }
-  if (typeof obj.apiKey === "string" && obj.apiKey) {
-    result.apiKey = obj.apiKey
+  if (argAfterCommand === "--unset" && argAfterKey) {
+    argv.splice(3, argv.length - 3, "unset", argAfterKey, ...rest)
+    return
   }
-  return result
-}
+  if (argAfterCommand.startsWith("-")) return
+  if (CONFIG_SUBCOMMAND_SET.has(argAfterCommand)) return
 
-function parseConfigValue(key: string, value: string): Partial<AgentikitConfig> {
-  switch (key) {
-    case "semanticSearch":
-      if (value !== "true" && value !== "false") {
-        throw new Error(`Invalid value for semanticSearch: expected "true" or "false"`)
-      }
-      return { semanticSearch: value === "true" }
-    case "additionalStashDirs":
-      try {
-        const parsed = JSON.parse(value)
-        if (!Array.isArray(parsed)) throw new Error("expected JSON array")
-        return { additionalStashDirs: parsed.filter((d: unknown): d is string => typeof d === "string") }
-      } catch {
-        throw new Error(`Invalid value for additionalStashDirs: expected JSON array (e.g. '["/path/a","/path/b"]')`)
-      }
-    case "embedding":
-      return { embedding: parseConnectionValue("embedding", value, "http://localhost:11434/v1/embeddings", "nomic-embed-text") }
-    case "llm":
-      return { llm: parseConnectionValue("llm", value, "http://localhost:11434/v1/chat/completions", "llama3.2") }
-    default:
-      throw new Error(`Unknown config key: ${key}`)
+  // A single arg after `config` behaves like `git config <key>` and reads the value.
+  if (argAfterKey === undefined) {
+    argv.splice(3, argv.length - 3, "get", argAfterCommand)
+    return
   }
+
+  argv.splice(3, argv.length - 3, "set", argAfterCommand, argAfterKey, ...rest)
 }

package/src/common.ts

@@ -4,7 +4,7 @@ import { TYPE_DIRS } from "./asset-spec"
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
-export type AgentikitAssetType = "tool" | "skill" | "command" | "agent" | "knowledge"
+export type AgentikitAssetType = "tool" | "skill" | "command" | "agent" | "knowledge" | "script"
 
 // ── Constants ───────────────────────────────────────────────────────────────
 
@@ -20,19 +20,19 @@ export function isAssetType(type: string): type is AgentikitAssetType {
 // ── Utilities ───────────────────────────────────────────────────────────────
 
 export function resolveStashDir(): string {
-  const raw = process.env.AGENTIKIT_STASH_DIR?.trim()
+  const raw = process.env.AKM_STASH_DIR?.trim()
   if (!raw) {
-    throw new Error("AGENTIKIT_STASH_DIR is not set. Set it to your Agentikit stash path.")
+    throw new Error("AKM_STASH_DIR is not set. Set it to your Agentikit stash path.")
   }
   const stashDir = path.resolve(raw)
   let stat: fs.Stats
   try {
     stat = fs.statSync(stashDir)
   } catch {
-    throw new Error(`Unable to read AGENTIKIT_STASH_DIR at "${stashDir}".`)
+    throw new Error(`Unable to read AKM_STASH_DIR at "${stashDir}".`)
   }
   if (!stat.isDirectory()) {
-    throw new Error(`AGENTIKIT_STASH_DIR must point to a directory: "${stashDir}".`)
+    throw new Error(`AKM_STASH_DIR must point to a directory: "${stashDir}".`)
   }
   return stashDir
 }
@@ -56,3 +56,21 @@ export function isWithin(candidate: string, root: string): boolean {
 function normalizeFsPathForComparison(value: string): string {
   return process.platform === "win32" ? value.toLowerCase() : value
 }
+
+/**
+ * Fetch with an AbortController timeout.
+ * Defaults to 30 seconds if no timeout is specified.
+ */
+export async function fetchWithTimeout(
+  url: string,
+  opts?: RequestInit,
+  timeoutMs = 30_000,
+): Promise<Response> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    return await fetch(url, { ...opts, signal: controller.signal })
+  } finally {
+    clearTimeout(timer)
+  }
+}