agentikit 0.0.9 → 0.0.13

package/src/stash-ref.ts

@@ -1,41 +1,99 @@
 import path from "node:path"
 import { type AgentikitAssetType, isAssetType } from "./common"
 
-export interface OpenRef {
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface AssetRef {
   type: AgentikitAssetType
   name: string
+  /**
+   * Where to find this asset.
+   *   - undefined: search all sources (working → mounted → installed)
+   *   - "local": working stash only
+   *   - registry ref: e.g. "npm:@scope/pkg", "owner/repo", "github:owner/repo#v1"
+   *   - filesystem path: e.g. "/mnt/shared-stash"
+   */
+  origin?: string
 }
 
-export function parseOpenRef(ref: string): OpenRef {
-  const separator = ref.indexOf(":")
-  if (separator <= 0) {
-    throw new Error("Invalid open ref. Expected format '<type>:<name>'.")
+// ── Construction ────────────────────────────────────────────────────────────
+
+/**
+ * Build a ref string from components.
+ *
+ * Examples:
+ *   makeAssetRef("tool", "deploy.sh")
+ *     → "tool:deploy.sh"
+ *   makeAssetRef("tool", "deploy.sh", "npm:@scope/pkg")
+ *     → "npm:@scope/pkg//tool:deploy.sh"
+ *   makeAssetRef("skill", "code-review", "local")
+ *     → "local//skill:code-review"
+ *   makeAssetRef("tool", "db/migrate/run.sh", "owner/repo")
+ *     → "owner/repo//tool:db/migrate/run.sh"
+ */
+export function makeAssetRef(
+  type: AgentikitAssetType,
+  name: string,
+  origin?: string,
+): string {
+  validateName(name)
+  const normalized = normalizeName(name)
+  const asset = `${type}:${normalized}`
+  if (!origin) return asset
+  return `${origin}//${asset}`
+}
+
+// ── Parsing ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a ref string in the format `[origin//]type:name`.
+ */
+export function parseAssetRef(ref: string): AssetRef {
+  const trimmed = ref.trim()
+  if (!trimmed) throw new Error("Empty ref.")
+
+  let origin: string | undefined
+  let body = trimmed
+
+  const boundary = trimmed.indexOf("//")
+  if (boundary >= 0) {
+    origin = trimmed.slice(0, boundary)
+    body = trimmed.slice(boundary + 2)
+    if (!origin) throw new Error("Empty origin in ref.")
   }
-  const rawType = ref.slice(0, separator)
-  const rawName = ref.slice(separator + 1)
-  if (!isAssetType(rawType)) {
-    throw new Error(`Invalid open ref type: "${rawType}".`)
+
+  const colon = body.indexOf(":")
+  if (colon <= 0) {
+    throw new Error(`Invalid ref "${trimmed}". Expected [origin//]type:name`)
   }
-  let name: string
-  try {
-    name = decodeURIComponent(rawName)
-  } catch {
-    throw new Error("Invalid open ref encoding.")
+
+  const rawType = body.slice(0, colon)
+  const rawName = body.slice(colon + 1)
+
+  if (!isAssetType(rawType)) {
+    throw new Error(`Invalid asset type: "${rawType}".`)
   }
+
+  validateName(rawName)
+  const name = normalizeName(rawName)
+
+  return { type: rawType, name, origin: origin || undefined }
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+function validateName(name: string): void {
+  if (!name) throw new Error("Empty asset name.")
+  if (name.includes("\0")) throw new Error("Null byte in asset name.")
+  if (/^[A-Za-z]:/.test(name)) throw new Error("Windows drive path in asset name.")
+
   const normalized = path.posix.normalize(name.replace(/\\/g, "/"))
-  if (
-    !name
-    || name.includes("\0")
-    || /^[A-Za-z]:/.test(name)
-    || path.posix.isAbsolute(normalized)
-    || normalized === ".."
-    || normalized.startsWith("../")
-  ) {
-    throw new Error("Invalid open ref name.")
+  if (path.posix.isAbsolute(normalized)) throw new Error("Absolute path in asset name.")
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new Error("Path traversal in asset name.")
   }
-  return { type: rawType, name: normalized }
 }
 
-export function makeOpenRef(type: AgentikitAssetType, name: string): string {
-  return `${type}:${encodeURIComponent(name)}`
+function normalizeName(name: string): string {
+  return path.posix.normalize(name.replace(/\\/g, "/"))
 }

package/src/stash-registry.ts

@@ -19,7 +19,7 @@ import type {
 
 export async function agentikitList(input?: { stashDir?: string }): Promise<ListResponse> {
   const stashDir = input?.stashDir ?? resolveStashDir()
-  const config = loadConfig(stashDir)
+  const config = loadConfig()
   const installed = config.registry?.installed ?? []
 
   return {
@@ -40,11 +40,11 @@ export async function agentikitRemove(input: { target: string; stashDir?: string
   if (!target) throw new Error("Target is required.")
 
   const stashDir = input.stashDir ?? resolveStashDir()
-  const config = loadConfig(stashDir)
+  const config = loadConfig()
   const installed = config.registry?.installed ?? []
   const entry = resolveInstalledTarget(installed, target)
 
-  const updatedConfig = removeInstalledRegistryEntry(entry.id, stashDir)
+  const updatedConfig = removeInstalledRegistryEntry(entry.id)
   cleanupDirectoryBestEffort(entry.cacheDir)
   const index = await agentikitIndex({ stashDir })
 
@@ -59,7 +59,7 @@ export async function agentikitRemove(input: { target: string; stashDir?: string
       stashRoot: entry.stashRoot,
     },
     config: {
-      additionalStashDirs: updatedConfig.additionalStashDirs,
+      mountedStashDirs: updatedConfig.mountedStashDirs,
       installedRegistryCount: updatedConfig.registry?.installed.length ?? 0,
     },
     index: {
@@ -79,13 +79,13 @@ export async function agentikitReinstall(input?: {
   const stashDir = input?.stashDir ?? resolveStashDir()
   const target = input?.target?.trim()
   const all = input?.all === true
-  const installedEntries = loadConfig(stashDir).registry?.installed ?? []
+  const installedEntries = loadConfig().registry?.installed ?? []
   const selectedEntries = selectTargets(installedEntries, target, all)
 
   const processed: ReinstallResponse["processed"] = []
   for (const entry of selectedEntries) {
     const installed = await installRegistryRef(entry.ref)
-    upsertInstalledRegistryEntry(toInstalledEntry(installed), stashDir)
+    upsertInstalledRegistryEntry(toInstalledEntry(installed))
     if (entry.cacheDir !== installed.cacheDir) {
       cleanupDirectoryBestEffort(entry.cacheDir)
     }
@@ -100,7 +100,7 @@ export async function agentikitReinstall(input?: {
   }
 
   const index = await agentikitIndex({ stashDir })
-  const config = loadConfig(stashDir)
+  const config = loadConfig()
 
   return {
     stashDir,
@@ -108,7 +108,7 @@ export async function agentikitReinstall(input?: {
     all,
     processed,
     config: {
-      additionalStashDirs: config.additionalStashDirs,
+      mountedStashDirs: config.mountedStashDirs,
       installedRegistryCount: config.registry?.installed.length ?? 0,
     },
     index: {
@@ -128,13 +128,13 @@ export async function agentikitUpdate(input?: {
   const stashDir = input?.stashDir ?? resolveStashDir()
   const target = input?.target?.trim()
   const all = input?.all === true
-  const installedEntries = loadConfig(stashDir).registry?.installed ?? []
+  const installedEntries = loadConfig().registry?.installed ?? []
   const selectedEntries = selectTargets(installedEntries, target, all)
 
   const processed: UpdateResponse["processed"] = []
   for (const entry of selectedEntries) {
     const installed = await installRegistryRef(entry.ref)
-    upsertInstalledRegistryEntry(toInstalledEntry(installed), stashDir)
+    upsertInstalledRegistryEntry(toInstalledEntry(installed))
     if (entry.cacheDir !== installed.cacheDir) {
       cleanupDirectoryBestEffort(entry.cacheDir)
     }
@@ -161,7 +161,7 @@ export async function agentikitUpdate(input?: {
   }
 
   const index = await agentikitIndex({ stashDir })
-  const config = loadConfig(stashDir)
+  const config = loadConfig()
 
   return {
     stashDir,
@@ -169,7 +169,7 @@ export async function agentikitUpdate(input?: {
     all,
     processed,
     config: {
-      additionalStashDirs: config.additionalStashDirs,
+      mountedStashDirs: config.mountedStashDirs,
       installedRegistryCount: config.registry?.installed.length ?? 0,
     },
     index: {

package/src/stash-resolve.ts

@@ -22,6 +22,9 @@ export function resolveAssetPath(stashDir: string, type: AgentikitAssetType, nam
     if (type === "tool") {
       throw new Error("Tool ref must resolve to a .sh, .ts, .js, .ps1, .cmd, or .bat file.")
     }
+    if (type === "script") {
+      throw new Error("Script ref must resolve to a file with a supported script extension. Refer to the Agentikit documentation for the complete list of supported script extensions.");
+    }
     throw new Error(`Stash asset not found for ref: ${type}:${name}`)
   }
   return realTarget