agentikit 0.0.8 → 0.0.12

package/src/stash-show.ts

@@ -1,24 +1,17 @@
 import fs from "node:fs"
-import path from "node:path"
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter"
-import { resolveStashDir } from "./common"
-import { parseOpenRef } from "./stash-ref"
+import { parseAssetRef } from "./stash-ref"
+import { resolveSourcesForOrigin } from "./origin-resolve"
 import { resolveAssetPath } from "./stash-resolve"
 import type { KnowledgeView, ShowResponse } from "./stash-types"
-import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./markdown"
-import { buildToolInfo } from "./tool-runner"
-import { loadConfig } from "./config"
+import { getHandler } from "./asset-type-handler"
+import { resolveStashSources, findSourceForPath } from "./stash-source"
 
-export function agentikitShow(input: { ref: string; view?: KnowledgeView }): ShowResponse {
-  const parsed = parseOpenRef(input.ref)
-  const stashDir = resolveStashDir()
-  const config = loadConfig(stashDir)
-  const allStashDirs = [
-    stashDir,
-    ...config.additionalStashDirs.filter((d) => {
-      try { return fs.statSync(d).isDirectory() } catch { return false }
-    }),
-  ]
+export async function agentikitShow(input: { ref: string; view?: KnowledgeView }): Promise<ShowResponse> {
+  const parsed = parseAssetRef(input.ref)
+  const allSources = resolveStashSources()
+  const searchSources = resolveSourcesForOrigin(parsed.origin, allSources)
+
+  const allStashDirs = searchSources.map((s) => s.path)
 
   let assetPath: string | undefined
   let lastError: Error | undefined
@@ -30,75 +23,33 @@ export function agentikitShow(input: { ref: string; view?: KnowledgeView }): Sho
       lastError = err instanceof Error ? err : new Error(String(err))
     }
   }
+
+  if (!assetPath && parsed.origin && searchSources.length === 0) {
+    const installCmd = `akm add ${parsed.origin}`
+    throw new Error(
+      `Stash asset not found for ref: ${parsed.type}:${parsed.name}. ` +
+      `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`
+    )
+  }
+
   if (!assetPath) {
     throw lastError ?? new Error(`Stash asset not found for ref: ${parsed.type}:${parsed.name}`)
   }
   const content = fs.readFileSync(assetPath, "utf8")
 
-  switch (parsed.type) {
-    case "skill":
-      return {
-        type: "skill",
-        name: parsed.name,
-        path: assetPath,
-        content,
-      }
-    case "command": {
-      const parsedMd = parseFrontmatter(content)
-      return {
-        type: "command",
-        name: parsed.name,
-        path: assetPath,
-        description: toStringOrUndefined(parsedMd.data.description),
-        template: parsedMd.content,
-      }
-    }
-    case "agent": {
-      const parsedMd = parseFrontmatter(content)
-      return {
-        type: "agent",
-        name: parsed.name,
-        path: assetPath,
-        description: toStringOrUndefined(parsedMd.data.description),
-        prompt: parsedMd.content,
-        toolPolicy: parsedMd.data.tools,
-        modelHint: parsedMd.data.model,
-      }
-    }
-    case "tool": {
-      const assetStashDir = allStashDirs.find((d) => path.resolve(assetPath!).startsWith(path.resolve(d) + path.sep)) ?? stashDir
-      const toolInfo = buildToolInfo(assetStashDir, assetPath)
-      return {
-        type: "tool",
-        name: parsed.name,
-        path: assetPath,
-        runCmd: toolInfo.runCmd,
-        kind: toolInfo.kind,
-      }
-    }
-    case "knowledge": {
-      const v = input.view ?? { mode: "full" }
-      switch (v.mode) {
-        case "toc": {
-          const toc = parseMarkdownToc(content)
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: formatToc(toc) }
-        }
-        case "frontmatter": {
-          const fm = extractFrontmatterOnly(content)
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: fm ?? "(no frontmatter)" }
-        }
-        case "section": {
-          const section = extractSection(content, v.heading)
-          if (!section) throw new Error(`Section "${v.heading}" not found in ${parsed.name}`)
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: section.content }
-        }
-        case "lines": {
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: extractLineRange(content, v.start, v.end) }
-        }
-        default: {
-          return { type: "knowledge", name: parsed.name, path: assetPath, content }
-        }
-      }
-    }
+  const source = findSourceForPath(assetPath, allSources)
+  const handler = getHandler(parsed.type)
+  const response = handler.buildShowResponse({
+    name: parsed.name,
+    path: assetPath,
+    content,
+    view: input.view,
+    stashDirs: allStashDirs,
+  })
+
+  return {
+    ...response,
+    registryId: source?.registryId,
+    editable: source?.writable ?? false,
   }
 }

package/src/stash-source.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs"
+import path from "node:path"
+import { resolveStashDir } from "./common"
+import { loadConfig } from "./config"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type StashSourceKind = "working" | "mounted" | "installed"
+
+export interface StashSource {
+  kind: StashSourceKind
+  path: string
+  /** For installed sources, the registry entry id */
+  registryId?: string
+  /** Whether this source is writable (only working stash) */
+  writable: boolean
+}
+
+// ── Resolution ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the ordered list of stash sources:
+ *   1. Working stash (writable)
+ *   2. Mounted stash dirs (read-only, user-configured)
+ *   3. Installed stash dirs (read-only, derived from registry.installed)
+ */
+export function resolveStashSources(overrideStashDir?: string): StashSource[] {
+  const stashDir = overrideStashDir ?? resolveStashDir()
+  const config = loadConfig()
+
+  const sources: StashSource[] = [
+    { kind: "working", path: stashDir, writable: true },
+  ]
+
+  for (const dir of config.mountedStashDirs) {
+    if (isSuspiciousStashRoot(dir)) {
+      console.warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`)
+    }
+    if (isValidDirectory(dir)) {
+      sources.push({ kind: "mounted", path: dir, writable: false })
+    }
+  }
+
+  for (const entry of config.registry?.installed ?? []) {
+    if (isSuspiciousStashRoot(entry.stashRoot)) {
+      console.warn(`Warning: stash root "${entry.stashRoot}" appears to be a system directory. This may be unintentional.`)
+    }
+    if (isValidDirectory(entry.stashRoot)) {
+      sources.push({
+        kind: "installed",
+        path: entry.stashRoot,
+        registryId: entry.id,
+        writable: false,
+      })
+    }
+  }
+
+  return sources
+}
+
+/**
+ * Convenience: returns just the directory paths, preserving priority order.
+ */
+export function resolveAllStashDirs(overrideStashDir?: string): string[] {
+  return resolveStashSources(overrideStashDir).map((s) => s.path)
+}
+
+/**
+ * Find which source a file path belongs to.
+ */
+export function findSourceForPath(filePath: string, sources: StashSource[]): StashSource | undefined {
+  const resolved = path.resolve(filePath)
+  for (const source of sources) {
+    if (resolved.startsWith(path.resolve(source.path) + path.sep)) return source
+  }
+  return undefined
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+const SUSPICIOUS_ROOTS = new Set(['/', '/etc', '/bin', '/sbin', '/usr', '/var', '/tmp', '/dev', '/proc', '/sys'])
+
+function isSuspiciousStashRoot(dir: string): boolean {
+  const resolved = path.resolve(dir)
+  const normalized = process.platform === 'win32' ? resolved.toLowerCase() : resolved
+  if (SUSPICIOUS_ROOTS.has(normalized)) return true
+  if (process.platform === 'win32') {
+    // Check for Windows system directories
+    const winDir = (process.env.SystemRoot || 'C:\\Windows').toLowerCase()
+    if (normalized === winDir || normalized.startsWith(winDir + path.sep)) return true
+  }
+  return false
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function isValidDirectory(dir: string): boolean {
+  try {
+    return fs.statSync(dir).isDirectory()
+  } catch {
+    return false
+  }
+}

package/src/stash-types.ts

@@ -1,29 +1,210 @@
 import type { AgentikitAssetType } from "./common"
+import type { RegistrySource } from "./registry-types"
 import type { ToolKind } from "./tool-runner"
 
 export type AgentikitSearchType = AgentikitAssetType | "any"
+export type SearchUsageMode = "none" | "both" | "item" | "guide"
+export type SearchSource = "local" | "registry" | "both"
 
-export interface SearchHit {
+export interface LocalSearchHit {
+  hitSource: "local"
   type: AgentikitAssetType
   name: string
   path: string
   openRef: string
+  /** For installed sources, the registry id */
+  registryId?: string
+  /** Whether this asset is editable (only true for working stash) */
+  editable?: boolean
   description?: string
   tags?: string[]
   score?: number
   whyMatched?: string[]
   runCmd?: string
   kind?: ToolKind
+  usage?: string[]
 }
 
+export interface RegistrySearchResultHit {
+  hitSource: "registry"
+  type: "registry"
+  name: string
+  path?: string
+  openRef?: string
+  id: string
+  registrySource: RegistrySource
+  ref: string
+  description?: string
+  tags?: string[]
+  homepage?: string
+  score?: number
+  whyMatched?: string[]
+  runCmd?: string
+  kind?: ToolKind
+  usage?: string[]
+  metadata?: Record<string, string>
+  installRef: string
+  installCmd: string
+  /** Whether this entry was manually reviewed and approved */
+  curated?: boolean
+}
+
+export type SearchHit = LocalSearchHit | RegistrySearchResultHit
+
 export interface SearchResponse {
   stashDir: string
+  source: SearchSource
   hits: SearchHit[]
+  usageGuide?: Partial<Record<AgentikitAssetType, string[]>>
   tip?: string
+  warnings?: string[]
   /** Timing counters in milliseconds */
   timing?: { totalMs: number; rankMs?: number; embedMs?: number }
 }
 
+export interface AddResponse {
+  stashDir: string
+  ref: string
+  installed: {
+    id: string
+    source: RegistrySource
+    ref: string
+    artifactUrl: string
+    resolvedVersion?: string
+    resolvedRevision?: string
+    stashRoot: string
+    cacheDir: string
+    extractedDir: string
+    installedAt: string
+  }
+  config: {
+    mountedStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
+export interface RegistryInstallStatus {
+  id: string
+  source: RegistrySource
+  ref: string
+  artifactUrl: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+  stashRoot: string
+  cacheDir: string
+  extractedDir: string
+  installedAt: string
+}
+
+export interface RegistryListEntry {
+  id: string
+  source: RegistrySource
+  ref: string
+  artifactUrl: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+  stashRoot: string
+  cacheDir: string
+  installedAt: string
+  status: {
+    cacheDirExists: boolean
+    stashRootExists: boolean
+  }
+}
+
+export interface ListResponse {
+  stashDir: string
+  installed: RegistryListEntry[]
+  totalInstalled: number
+}
+
+export interface RemoveResponse {
+  stashDir: string
+  target: string
+  removed: {
+    id: string
+    source: RegistrySource
+    ref: string
+    cacheDir: string
+    stashRoot: string
+  }
+  config: {
+    mountedStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
+export interface ReinstallResultItem {
+  id: string
+  source: RegistrySource
+  ref: string
+  previousCacheDir: string
+  installed: RegistryInstallStatus
+}
+
+export interface ReinstallResponse {
+  stashDir: string
+  target?: string
+  all: boolean
+  processed: ReinstallResultItem[]
+  config: {
+    mountedStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
+export interface UpdateResultItem {
+  id: string
+  source: RegistrySource
+  ref: string
+  previous: {
+    resolvedVersion?: string
+    resolvedRevision?: string
+    cacheDir: string
+  }
+  installed: RegistryInstallStatus
+  changed: {
+    version: boolean
+    revision: boolean
+    any: boolean
+  }
+}
+
+export interface UpdateResponse {
+  stashDir: string
+  target?: string
+  all: boolean
+  processed: UpdateResultItem[]
+  config: {
+    mountedStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
 export interface ShowResponse {
   type: AgentikitAssetType
   name: string
@@ -36,6 +217,10 @@ export interface ShowResponse {
   modelHint?: unknown
   runCmd?: string
   kind?: ToolKind
+  /** For installed sources, the registry id */
+  registryId?: string
+  /** Whether this asset is editable (only true for working stash) */
+  editable?: boolean
 }
 
 export type KnowledgeView =

package/src/stash.ts

@@ -3,14 +3,37 @@ export { resolveStashDir } from "./common"
 export { agentikitInit } from "./init"
 export type { InitResponse } from "./init"
 export type { ToolKind } from "./tool-runner"
+export type { AssetTypeHandler, ShowInput } from "./asset-type-handler"
+export { registerAssetType, getHandler, getAllHandlers, getRegisteredTypeNames } from "./asset-type-handler"
 
 export { agentikitSearch } from "./stash-search"
 export { agentikitShow } from "./stash-show"
+export { agentikitAdd } from "./stash-add"
+export { agentikitClone } from "./stash-clone"
+
+export { agentikitList, agentikitRemove, agentikitReinstall, agentikitUpdate } from "./stash-registry"
+export { resolveStashSources, resolveAllStashDirs, findSourceForPath } from "./stash-source"
+export type { StashSource, StashSourceKind } from "./stash-source"
 
 export type {
+  AddResponse,
   AgentikitSearchType,
+  LocalSearchHit,
+  RegistrySearchResultHit,
+  SearchSource,
+  SearchUsageMode,
   SearchHit,
   SearchResponse,
   ShowResponse,
   KnowledgeView,
+  ListResponse,
+  RemoveResponse,
+  ReinstallResponse,
+  UpdateResponse,
+  RegistryListEntry,
+  RegistryInstallStatus,
+  ReinstallResultItem,
+  UpdateResultItem,
 } from "./stash-types"
+
+export type { CloneOptions, CloneResponse } from "./stash-clone"

package/src/tool-runner.ts

@@ -34,7 +34,7 @@ export interface ToolInfo {
  *
  * For `.ts` / `.js` files, looks up the nearest `package.json` so that
  * `bun install` can be run in the correct working directory when the
- * `AGENTIKIT_BUN_INSTALL` env flag is set.
+ * `AKM_BUN_INSTALL` env flag is set.
  */
 export function buildToolInfo(stashDir: string, filePath: string): ToolInfo {
   const ext = path.extname(filePath).toLowerCase()
@@ -67,8 +67,17 @@ export function buildToolInfo(stashDir: string, filePath: string): ToolInfo {
     throw new Error(`Unsupported tool extension: ${ext}`)
   }
 
-  const toolsRoot = path.resolve(path.join(stashDir, "tools"))
-  const pkgDir = findNearestPackageDir(path.dirname(filePath), toolsRoot)
+  // Determine the type root by checking which subdirectory contains the file
+  const resolvedFile = path.resolve(filePath)
+  let typeRoot = path.resolve(path.join(stashDir, "tools"))
+  for (const subdir of ["tools", "scripts"]) {
+    const candidate = path.resolve(path.join(stashDir, subdir))
+    if (resolvedFile.startsWith(candidate + path.sep)) {
+      typeRoot = candidate
+      break
+    }
+  }
+  const pkgDir = findNearestPackageDir(path.dirname(filePath), typeRoot)
   if (!pkgDir) {
     return {
       runCmd: `bun ${shellQuote(filePath)}`,
@@ -76,7 +85,7 @@ export function buildToolInfo(stashDir: string, filePath: string): ToolInfo {
       execute: { command: "bun", args: [filePath] },
     }
   }
-  const installFlag = process.env.AGENTIKIT_BUN_INSTALL
+  const installFlag = process.env.AKM_BUN_INSTALL
   const shouldInstall = installFlag === "1" || installFlag === "true" || installFlag === "yes"
 
   const quotedPkgDir = shellQuote(pkgDir)
@@ -101,7 +110,11 @@ export function shellQuote(input: string): string {
     throw new Error("Unsupported control characters in stash path.")
   }
   if (IS_WINDOWS) {
-    return `"${input.replace(/"/g, '""')}"`
+    const escaped = input
+      .replace(/%/g, "%%")
+      .replace(/([\\^|&<>])/g, "^$1")
+      .replace(/"/g, '""')
+    return `"${escaped}"`
   }
   const escaped = input
     .replace(/\\/g, "\\\\")

package/dist/src/similarity.d.ts

@@ -1,34 +0,0 @@
-import type { StashEntry } from "./metadata";
-export interface ScoredEntry {
-    id: string;
-    text: string;
-    entry: StashEntry;
-    path: string;
-}
-export interface ScoredResult {
-    entry: StashEntry;
-    path: string;
-    score: number;
-}
-export interface SearchAdapter {
-    buildIndex(entries: ScoredEntry[]): void;
-    search(query: string, limit: number, typeFilter?: string): ScoredResult[];
-}
-export interface SerializedTfIdf {
-    idf: Record<string, number>;
-    docs: Array<{
-        id: string;
-        termFreqs: Record<string, number>;
-        magnitude: number;
-    }>;
-}
-export declare class TfIdfAdapter implements SearchAdapter {
-    private documents;
-    private idf;
-    private entries;
-    buildIndex(entries: ScoredEntry[]): void;
-    search(query: string, limit: number, typeFilter?: string): ScoredResult[];
-    serialize(): SerializedTfIdf;
-    static deserialize(data: SerializedTfIdf, entries: ScoredEntry[]): TfIdfAdapter;
-    private substringFallback;
-}