agentikit 0.0.8 → 0.0.12

package/src/registry-types.ts

@@ -0,0 +1,72 @@
+export type RegistrySource = "npm" | "github" | "git"
+
+export interface RegistryRefBase {
+  source: RegistrySource
+  ref: string
+  id: string
+}
+
+export interface ParsedNpmRef extends RegistryRefBase {
+  source: "npm"
+  packageName: string
+  requestedVersionOrTag?: string
+}
+
+export interface ParsedGithubRef extends RegistryRefBase {
+  source: "github"
+  owner: string
+  repo: string
+  requestedRef?: string
+}
+
+export interface ParsedGitRef extends RegistryRefBase {
+  source: "git"
+  repoRoot: string
+  sourcePath: string
+}
+
+export type ParsedRegistryRef = ParsedNpmRef | ParsedGithubRef | ParsedGitRef
+
+export interface ResolvedRegistryArtifact {
+  id: string
+  source: RegistrySource
+  ref: string
+  artifactUrl: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+}
+
+export interface RegistryInstalledEntry {
+  id: string
+  source: RegistrySource
+  ref: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+  artifactUrl: string
+  stashRoot: string
+  cacheDir: string
+  installedAt: string
+}
+
+export interface RegistryInstallResult extends RegistryInstalledEntry {
+  extractedDir: string
+}
+
+export interface RegistrySearchHit {
+  source: RegistrySource
+  id: string
+  title: string
+  description?: string
+  ref: string
+  homepage?: string
+  score?: number
+  metadata?: Record<string, string>
+  /** Whether this entry was manually reviewed and approved */
+  curated?: boolean
+}
+
+export interface RegistrySearchResponse {
+  query: string
+  hits: RegistrySearchHit[]
+  warnings: string[]
+}

package/src/stash-add.ts

@@ -0,0 +1,63 @@
+import { agentikitIndex } from "./indexer"
+import fs from "node:fs"
+import { resolveStashDir } from "./common"
+import { loadConfig } from "./config"
+import { upsertInstalledRegistryEntry, installRegistryRef } from "./registry-install"
+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("Install ref or local git directory is required.")
+
+  const stashDir = resolveStashDir()
+  const installed = await installRegistryRef(ref)
+  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 {
+      fs.rmSync(replaced.cacheDir, { recursive: true, force: true })
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+
+  const index = await agentikitIndex({ stashDir })
+
+  return {
+    stashDir,
+    ref,
+    installed: {
+      id: installed.id,
+      source: installed.source,
+      ref: installed.ref,
+      artifactUrl: installed.artifactUrl,
+      resolvedVersion: installed.resolvedVersion,
+      resolvedRevision: installed.resolvedRevision,
+      stashRoot: installed.stashRoot,
+      cacheDir: installed.cacheDir,
+      extractedDir: installed.extractedDir,
+      installedAt: installed.installedAt,
+    },
+    config: {
+      mountedStashDirs: config.mountedStashDirs,
+      installedRegistryCount: config.registry?.installed.length ?? 0,
+    },
+    index: {
+      mode: index.mode,
+      totalEntries: index.totalEntries,
+      directoriesScanned: index.directoriesScanned,
+      directoriesSkipped: index.directoriesSkipped,
+    },
+  }
+}

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,
+  }
+}

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

@@ -0,0 +1,259 @@
+import fs from "node:fs"
+import { resolveStashDir } from "./common"
+import { loadConfig } from "./config"
+import { agentikitIndex } from "./indexer"
+import {
+  installRegistryRef,
+  removeInstalledRegistryEntry,
+  upsertInstalledRegistryEntry,
+} from "./registry-install"
+import { parseRegistryRef } from "./registry-resolve"
+import type { RegistryInstalledEntry } from "./registry-types"
+import type {
+  ListResponse,
+  RegistryInstallStatus,
+  RemoveResponse,
+  ReinstallResponse,
+  UpdateResponse,
+} from "./stash-types"
+
+export async function agentikitList(input?: { stashDir?: string }): Promise<ListResponse> {
+  const stashDir = input?.stashDir ?? resolveStashDir()
+  const config = loadConfig()
+  const installed = config.registry?.installed ?? []
+
+  return {
+    stashDir,
+    installed: installed.map((entry) => ({
+      ...entry,
+      status: {
+        cacheDirExists: directoryExists(entry.cacheDir),
+        stashRootExists: directoryExists(entry.stashRoot),
+      },
+    })),
+    totalInstalled: installed.length,
+  }
+}
+
+export async function agentikitRemove(input: { target: string; stashDir?: string }): Promise<RemoveResponse> {
+  const target = input.target.trim()
+  if (!target) throw new Error("Target is required.")
+
+  const stashDir = input.stashDir ?? resolveStashDir()
+  const config = loadConfig()
+  const installed = config.registry?.installed ?? []
+  const entry = resolveInstalledTarget(installed, target)
+
+  const updatedConfig = removeInstalledRegistryEntry(entry.id)
+  cleanupDirectoryBestEffort(entry.cacheDir)
+  const index = await agentikitIndex({ stashDir })
+
+  return {
+    stashDir,
+    target,
+    removed: {
+      id: entry.id,
+      source: entry.source,
+      ref: entry.ref,
+      cacheDir: entry.cacheDir,
+      stashRoot: entry.stashRoot,
+    },
+    config: {
+      mountedStashDirs: updatedConfig.mountedStashDirs,
+      installedRegistryCount: updatedConfig.registry?.installed.length ?? 0,
+    },
+    index: {
+      mode: index.mode,
+      totalEntries: index.totalEntries,
+      directoriesScanned: index.directoriesScanned,
+      directoriesSkipped: index.directoriesSkipped,
+    },
+  }
+}
+
+export async function agentikitReinstall(input?: {
+  target?: string
+  all?: boolean
+  stashDir?: string
+}): Promise<ReinstallResponse> {
+  const stashDir = input?.stashDir ?? resolveStashDir()
+  const target = input?.target?.trim()
+  const all = input?.all === true
+  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))
+    if (entry.cacheDir !== installed.cacheDir) {
+      cleanupDirectoryBestEffort(entry.cacheDir)
+    }
+
+    processed.push({
+      id: entry.id,
+      source: entry.source,
+      ref: entry.ref,
+      previousCacheDir: entry.cacheDir,
+      installed: toInstallStatus(installed),
+    })
+  }
+
+  const index = await agentikitIndex({ stashDir })
+  const config = loadConfig()
+
+  return {
+    stashDir,
+    target,
+    all,
+    processed,
+    config: {
+      mountedStashDirs: config.mountedStashDirs,
+      installedRegistryCount: config.registry?.installed.length ?? 0,
+    },
+    index: {
+      mode: index.mode,
+      totalEntries: index.totalEntries,
+      directoriesScanned: index.directoriesScanned,
+      directoriesSkipped: index.directoriesSkipped,
+    },
+  }
+}
+
+export async function agentikitUpdate(input?: {
+  target?: string
+  all?: boolean
+  stashDir?: string
+}): Promise<UpdateResponse> {
+  const stashDir = input?.stashDir ?? resolveStashDir()
+  const target = input?.target?.trim()
+  const all = input?.all === true
+  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))
+    if (entry.cacheDir !== installed.cacheDir) {
+      cleanupDirectoryBestEffort(entry.cacheDir)
+    }
+
+    const versionChanged = (entry.resolvedVersion ?? "") !== (installed.resolvedVersion ?? "")
+    const revisionChanged = (entry.resolvedRevision ?? "") !== (installed.resolvedRevision ?? "")
+
+    processed.push({
+      id: entry.id,
+      source: entry.source,
+      ref: entry.ref,
+      previous: {
+        resolvedVersion: entry.resolvedVersion,
+        resolvedRevision: entry.resolvedRevision,
+        cacheDir: entry.cacheDir,
+      },
+      installed: toInstallStatus(installed),
+      changed: {
+        version: versionChanged,
+        revision: revisionChanged,
+        any: versionChanged || revisionChanged,
+      },
+    })
+  }
+
+  const index = await agentikitIndex({ stashDir })
+  const config = loadConfig()
+
+  return {
+    stashDir,
+    target,
+    all,
+    processed,
+    config: {
+      mountedStashDirs: config.mountedStashDirs,
+      installedRegistryCount: config.registry?.installed.length ?? 0,
+    },
+    index: {
+      mode: index.mode,
+      totalEntries: index.totalEntries,
+      directoriesScanned: index.directoriesScanned,
+      directoriesSkipped: index.directoriesSkipped,
+    },
+  }
+}
+
+function selectTargets(installed: RegistryInstalledEntry[], target: string | undefined, all: boolean): RegistryInstalledEntry[] {
+  if (all && target) {
+    throw new Error("Specify either <target> or --all, not both.")
+  }
+  if (all) return installed
+  if (!target) {
+    throw new Error("Either <target> or --all is required.")
+  }
+  return [resolveInstalledTarget(installed, target)]
+}
+
+function resolveInstalledTarget(installed: RegistryInstalledEntry[], target: string): RegistryInstalledEntry {
+  const byId = installed.find((entry) => entry.id === target)
+  if (byId) return byId
+
+  const byRef = installed.find((entry) => entry.ref === target)
+  if (byRef) return byRef
+
+  let parsedId: string | undefined
+  try {
+    parsedId = parseRegistryRef(target).id
+  } catch {
+    parsedId = undefined
+  }
+  if (parsedId) {
+    const byParsedId = installed.find((entry) => entry.id === parsedId)
+    if (byParsedId) return byParsedId
+  }
+
+  throw new Error(`No installed registry entry matched target: ${target}`)
+}
+
+function toInstalledEntry(status: RegistryInstallStatus): RegistryInstalledEntry {
+  return {
+    id: status.id,
+    source: status.source,
+    ref: status.ref,
+    artifactUrl: status.artifactUrl,
+    resolvedVersion: status.resolvedVersion,
+    resolvedRevision: status.resolvedRevision,
+    stashRoot: status.stashRoot,
+    cacheDir: status.cacheDir,
+    installedAt: status.installedAt,
+  }
+}
+
+function toInstallStatus(status: RegistryInstallStatus): RegistryInstallStatus {
+  return {
+    id: status.id,
+    source: status.source,
+    ref: status.ref,
+    artifactUrl: status.artifactUrl,
+    resolvedVersion: status.resolvedVersion,
+    resolvedRevision: status.resolvedRevision,
+    stashRoot: status.stashRoot,
+    cacheDir: status.cacheDir,
+    extractedDir: status.extractedDir,
+    installedAt: status.installedAt,
+  }
+}
+
+function cleanupDirectoryBestEffort(target: string): void {
+  try {
+    fs.rmSync(target, { recursive: true, force: true })
+  } catch {
+    // Best-effort cleanup only.
+  }
+}
+
+function directoryExists(target: string): boolean {
+  try {
+    return fs.statSync(target).isDirectory()
+  } catch {
+    return false
+  }
+}

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