agentikit 0.0.9 → 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,83 +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: "Dispatching prompt must include the agent's full prompt content verbatim; summaries are non-compliant. \n\n" 
-        + 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) {
-            return {
-              type: "knowledge",
-              name: parsed.name,
-              path: assetPath,
-              content: `Section "${v.heading}" not found in ${parsed.name}. Try --view toc to discover available headings.`,
-            }
-          }
-          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

@@ -12,6 +12,10 @@ export interface LocalSearchHit {
   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
@@ -41,6 +45,8 @@ export interface RegistrySearchResultHit {
   metadata?: Record<string, string>
   installRef: string
   installCmd: string
+  /** Whether this entry was manually reviewed and approved */
+  curated?: boolean
 }
 
 export type SearchHit = LocalSearchHit | RegistrySearchResultHit
@@ -72,7 +78,7 @@ export interface AddResponse {
     installedAt: string
   }
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -129,7 +135,7 @@ export interface RemoveResponse {
     stashRoot: string
   }
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -154,7 +160,7 @@ export interface ReinstallResponse {
   all: boolean
   processed: ReinstallResultItem[]
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -188,7 +194,7 @@ export interface UpdateResponse {
   all: boolean
   processed: UpdateResultItem[]
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -211,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,11 +3,17 @@ 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,
@@ -29,3 +35,5 @@ export type {
   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;
-}

package/src/similarity.ts

@@ -1,271 +0,0 @@
-import type { StashEntry } from "./metadata"
-
-// ── Adapter Interface ───────────────────────────────────────────────────────
-
-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[]
-}
-
-// ── TF-IDF Implementation ───────────────────────────────────────────────────
-
-interface TfIdfDocument {
-  entry: ScoredEntry
-  termFreqs: Map<string, number>
-  magnitude: number
-}
-
-export interface SerializedTfIdf {
-  idf: Record<string, number>
-  docs: Array<{
-    id: string
-    termFreqs: Record<string, number>
-    magnitude: number
-  }>
-}
-
-export class TfIdfAdapter implements SearchAdapter {
-  private documents: TfIdfDocument[] = []
-  private idf: Map<string, number> = new Map()
-  private entries: ScoredEntry[] = []
-
-  buildIndex(entries: ScoredEntry[]): void {
-    this.entries = entries
-    const docCount = entries.length
-    if (docCount === 0) return
-
-    // Compute term frequencies per document
-    const docFreqs = new Map<string, number>()
-    this.documents = entries.map((entry) => {
-      const tokens = tokenize(entry.text)
-      const termFreqs = new Map<string, number>()
-
-      for (const token of tokens) {
-        termFreqs.set(token, (termFreqs.get(token) || 0) + 1)
-      }
-
-      // Track document frequency for IDF
-      for (const term of termFreqs.keys()) {
-        docFreqs.set(term, (docFreqs.get(term) || 0) + 1)
-      }
-
-      return { entry, termFreqs, magnitude: 0 }
-    })
-
-    // Compute IDF: log(N / df)
-    this.idf = new Map()
-    for (const [term, df] of docFreqs) {
-      this.idf.set(term, Math.log(docCount / df))
-    }
-
-    // Compute document magnitudes for cosine similarity
-    for (const doc of this.documents) {
-      let sumSq = 0
-      for (const [term, tf] of doc.termFreqs) {
-        const idf = this.idf.get(term) || 0
-        const tfidf = tf * idf
-        sumSq += tfidf * tfidf
-      }
-      doc.magnitude = Math.sqrt(sumSq)
-    }
-  }
-
-  search(query: string, limit: number, typeFilter?: string): ScoredResult[] {
-    if (this.documents.length === 0) return []
-
-    const queryTokens = tokenize(query.toLowerCase())
-    if (queryTokens.length === 0) {
-      // Empty query: return all, sorted by type
-      return this.documents
-        .filter((d) => !typeFilter || typeFilter === "any" || d.entry.entry.type === typeFilter)
-        .slice(0, limit)
-        .map((d) => ({
-          entry: d.entry.entry,
-          path: d.entry.path,
-          score: 1,
-        }))
-    }
-
-    // Build query TF-IDF vector
-    const queryTermFreqs = new Map<string, number>()
-    for (const token of queryTokens) {
-      queryTermFreqs.set(token, (queryTermFreqs.get(token) || 0) + 1)
-    }
-
-    let queryMagnitude = 0
-    const queryVector = new Map<string, number>()
-    for (const [term, tf] of queryTermFreqs) {
-      const idf = this.idf.get(term) || 0
-      const tfidf = tf * idf
-      queryVector.set(term, tfidf)
-      queryMagnitude += tfidf * tfidf
-    }
-    queryMagnitude = Math.sqrt(queryMagnitude)
-
-    if (queryMagnitude === 0) {
-      // All query terms are unknown — fallback to substring match
-      return this.substringFallback(query, limit, typeFilter)
-    }
-
-    const results: ScoredResult[] = []
-    const querySet = new Set(queryTokens)
-
-    for (const doc of this.documents) {
-      if (typeFilter && typeFilter !== "any" && doc.entry.entry.type !== typeFilter) continue
-
-      // Cosine similarity
-      let dotProduct = 0
-      for (const [term, queryTfidf] of queryVector) {
-        const docTf = doc.termFreqs.get(term) || 0
-        if (docTf === 0) continue
-        const docIdf = this.idf.get(term) || 0
-        dotProduct += queryTfidf * (docTf * docIdf)
-      }
-
-      let score = doc.magnitude > 0 && queryMagnitude > 0
-        ? dotProduct / (doc.magnitude * queryMagnitude)
-        : 0
-
-      // Boost: tag exact match
-      const tags = doc.entry.entry.tags || []
-      for (const tag of tags) {
-        if (querySet.has(tag.toLowerCase())) {
-          score += 0.15
-        }
-      }
-
-      // Boost: intent phrase contains query token
-      const intents = doc.entry.entry.intents || []
-      for (const intent of intents) {
-        const intentLower = intent.toLowerCase()
-        for (const token of queryTokens) {
-          if (intentLower.includes(token)) {
-            score += 0.12
-            break // one boost per intent phrase
-          }
-        }
-      }
-
-      // Boost: name contains query token
-      const nameLower = doc.entry.entry.name.toLowerCase().replace(/[-_]/g, " ")
-      for (const token of queryTokens) {
-        if (nameLower.includes(token)) {
-          score += 0.1
-          break
-        }
-      }
-
-      if (score > 0) {
-        results.push({
-          entry: doc.entry.entry,
-          path: doc.entry.path,
-          score: Math.round(score * 1000) / 1000,
-        })
-      }
-    }
-
-    results.sort((a, b) => b.score - a.score)
-    return results.slice(0, limit)
-  }
-
-  serialize(): SerializedTfIdf {
-    const idf: Record<string, number> = {}
-    for (const [term, val] of this.idf) {
-      idf[term] = val
-    }
-    const docs = this.documents.map((d) => {
-      const termFreqs: Record<string, number> = {}
-      for (const [term, tf] of d.termFreqs) {
-        termFreqs[term] = tf
-      }
-      return { id: d.entry.id, termFreqs, magnitude: d.magnitude }
-    })
-    return { idf, docs }
-  }
-
-  static deserialize(data: SerializedTfIdf, entries: ScoredEntry[]): TfIdfAdapter {
-    const adapter = new TfIdfAdapter()
-    adapter.entries = entries
-
-    adapter.idf = new Map(Object.entries(data.idf))
-
-    const entryMap = new Map(entries.map((e) => [e.id, e]))
-    adapter.documents = data.docs
-      .map((d) => {
-        const entry = entryMap.get(d.id)
-        if (!entry) return null
-        return {
-          entry,
-          termFreqs: new Map(Object.entries(d.termFreqs)),
-          magnitude: d.magnitude,
-        }
-      })
-      .filter((d): d is TfIdfDocument => d !== null)
-
-    return adapter
-  }
-
-  private substringFallback(query: string, limit: number, typeFilter?: string): ScoredResult[] {
-    const q = query.toLowerCase()
-    const tokens = tokenize(q)
-    return this.documents
-      .map((d) => {
-        if (typeFilter && typeFilter !== "any" && d.entry.entry.type !== typeFilter) return null
-        // Check if any query token matches the document text or name
-        const text = d.entry.text
-        const name = d.entry.entry.name.toLowerCase()
-        let matchCount = 0
-        for (const token of tokens) {
-          if (text.includes(token) || name.includes(token)) matchCount++
-        }
-        // Also check full substring match
-        if (text.includes(q) || name.includes(q)) matchCount = Math.max(matchCount, tokens.length)
-        if (matchCount === 0) return null
-        return {
-          entry: d.entry.entry,
-          path: d.entry.path,
-          score: Math.round((matchCount / Math.max(tokens.length, 1)) * 500) / 1000,
-        }
-      })
-      .filter((d): d is ScoredResult => d !== null)
-      .sort((a, b) => b.score - a.score)
-      .slice(0, limit)
-  }
-}
-
-// ── Tokenization ────────────────────────────────────────────────────────────
-
-const STOP_WORDS = new Set([
-  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
-  "have", "has", "had", "do", "does", "did", "will", "would", "could",
-  "should", "may", "might", "shall", "can", "need", "dare", "ought",
-  "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
-  "into", "through", "during", "before", "after", "above", "below",
-  "and", "but", "or", "nor", "not", "so", "yet", "both", "either",
-  "neither", "each", "every", "all", "any", "few", "more", "most",
-  "other", "some", "such", "no", "only", "own", "same", "than",
-  "too", "very", "just", "because", "if", "when", "where", "how",
-  "what", "which", "who", "whom", "this", "that", "these", "those",
-  "it", "its",
-])
-
-function tokenize(text: string): string[] {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, " ")
-    .split(/\s+/)
-    .filter((t) => t.length > 1 && !STOP_WORDS.has(t))
-}