agentikit 0.0.3

package/skills/stash/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: stash
+description: Search, open, and run extension assets from an Agentikit stash directory. Use when the user wants to find tools, skills, commands, or agents in their stash, view asset contents, or execute stash tools.
+---
+
+# Agentikit Stash
+
+You have access to the `agentikit` CLI to manage extension assets from a stash directory.
+
+The stash directory is configured via the `AGENTIKIT_STASH_DIR` environment variable and contains:
+
+- **tools/** — executable scripts (.sh, .ts, .js, .ps1, .cmd, .bat)
+- **skills/** — skill directories containing SKILL.md
+- **commands/** — markdown template files
+- **agents/** — markdown agent definition files
+
+## Commands
+
+### Build the search index
+
+Scan stash directories, auto-generate missing `.stash.json` metadata, and build a semantic search index.
+
+```bash
+agentikit index
+```
+
+Run this after adding new extensions to enable semantic search ranking.
+
+### Search the stash
+
+Find assets by semantic similarity (if indexed) or name substring. Returns JSON with matching hits including `openRef` identifiers.
+
+```bash
+agentikit search [query] [--type tool|skill|command|agent|any] [--limit N]
+```
+
+### Open an asset
+
+Retrieve the full content/payload of an asset using its `openRef` from search results.
+
+```bash
+agentikit open <openRef>
+```
+
+Returns type-specific payloads:
+- **skill** → full SKILL.md content
+- **command** → markdown template + description
+- **agent** → prompt + description, toolPolicy, modelHint
+- **tool** → execution command and kind
+
+### Run a tool
+
+Execute a tool asset by its `openRef`. Only tool refs are supported.
+
+```bash
+agentikit run <openRef>
+```
+
+Returns the tool's stdout/stderr output and exit code.
+
+## Workflow
+
+1. Build the index: `agentikit index`
+2. Search for assets: `agentikit search "deploy" --type tool`
+3. Inspect a result: `agentikit open <openRef>`
+4. Run a tool: `agentikit run <openRef>`
+
+All output is JSON for easy parsing.

package/src/cli.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./stash"
+import { agentikitIndex } from "./indexer"
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+function flag(name: string): string | undefined {
+  const idx = args.indexOf(name)
+  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined
+}
+
+function usage(): never {
+  console.error("Usage: agentikit <init|search|open|run> [options]")
+  console.error("")
+  console.error("Commands:")
+  console.error("  init                 Initialize agentikit stash directory and set AGENTIKIT_STASH_DIR")
+  console.error("  index                Build search index with metadata generation")
+  console.error("  search [query]       Search the stash (--type tool|skill|command|agent|any) (--limit N)")
+  console.error("  open <type:name>     Open a stash asset by ref")
+  console.error("  run <type:name>      Run a tool by ref")
+  process.exit(1)
+}
+
+switch (command) {
+  case "init": {
+    const result = agentikitInit()
+    console.log(JSON.stringify(result, null, 2))
+    break
+  }
+  case "index": {
+    const result = agentikitIndex()
+    console.log(JSON.stringify(result, null, 2))
+    break
+  }
+  case "search": {
+    const query = args.find((a, i) => i > 0 && !a.startsWith("--") && args[i - 1] !== "--type" && args[i - 1] !== "--limit") ?? ""
+    const type = flag("--type") as "tool" | "skill" | "command" | "agent" | "any" | undefined
+    const limitStr = flag("--limit")
+    const limit = limitStr ? parseInt(limitStr, 10) : undefined
+    console.log(JSON.stringify(agentikitSearch({ query, type, limit }), null, 2))
+    break
+  }
+  case "open": {
+    const ref = args[1]
+    if (!ref) { console.error("Error: missing ref argument\n"); usage() }
+    console.log(JSON.stringify(agentikitOpen({ ref }), null, 2))
+    break
+  }
+  case "run": {
+    const ref = args[1]
+    if (!ref) { console.error("Error: missing ref argument\n"); usage() }
+    const result = agentikitRun({ ref })
+    console.log(JSON.stringify(result, null, 2))
+    process.exit(result.exitCode)
+    break
+  }
+  default:
+    usage()
+}

package/src/indexer.ts

@@ -0,0 +1,211 @@
+import fs from "node:fs"
+import path from "node:path"
+import type { AgentikitAssetType } from "./stash"
+import {
+  type StashFile,
+  type StashEntry,
+  loadStashFile,
+  writeStashFile,
+  generateMetadata,
+} from "./metadata"
+import { TfIdfAdapter, type ScoredEntry } from "./similarity"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface IndexedEntry {
+  entry: StashEntry
+  path: string
+  dirPath: string
+}
+
+export interface SearchIndex {
+  version: number
+  builtAt: string
+  stashDir: string
+  entries: IndexedEntry[]
+  /** Serialized TF-IDF state (term frequencies, idf values) */
+  tfidf?: unknown
+}
+
+export interface IndexResponse {
+  stashDir: string
+  totalEntries: number
+  generatedMetadata: number
+  indexPath: string
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+const INDEX_VERSION = 1
+const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"])
+
+const TYPE_DIRS: Record<AgentikitAssetType, string> = {
+  tool: "tools",
+  skill: "skills",
+  command: "commands",
+  agent: "agents",
+}
+
+// ── Index Path ──────────────────────────────────────────────────────────────
+
+export function getIndexPath(): string {
+  const cacheDir = process.env.XDG_CACHE_HOME
+    || path.join(process.env.HOME || process.env.USERPROFILE || "", ".cache")
+  return path.join(cacheDir, "agentikit", "index.json")
+}
+
+export function loadSearchIndex(): SearchIndex | null {
+  const indexPath = getIndexPath()
+  if (!fs.existsSync(indexPath)) return null
+  try {
+    const raw = JSON.parse(fs.readFileSync(indexPath, "utf8"))
+    if (raw?.version !== INDEX_VERSION) return null
+    return raw as SearchIndex
+  } catch {
+    return null
+  }
+}
+
+// ── Indexer ──────────────────────────────────────────────────────────────────
+
+export function agentikitIndex(options?: { stashDir?: string }): IndexResponse {
+  const stashDir = options?.stashDir || resolveStashDirForIndex()
+  const allEntries: IndexedEntry[] = []
+  let generatedCount = 0
+
+  for (const assetType of Object.keys(TYPE_DIRS) as AgentikitAssetType[]) {
+    const typeRoot = path.join(stashDir, TYPE_DIRS[assetType])
+    if (!fs.existsSync(typeRoot) || !fs.statSync(typeRoot).isDirectory()) continue
+
+    // Group files by their immediate parent directory
+    const dirGroups = collectDirectoryGroups(typeRoot, assetType)
+
+    for (const [dirPath, files] of dirGroups) {
+      // Try loading existing .stash.json
+      let stash = loadStashFile(dirPath)
+
+      if (!stash) {
+        // Generate metadata
+        stash = generateMetadata(dirPath, assetType, files)
+        if (stash.entries.length > 0) {
+          writeStashFile(dirPath, stash)
+          generatedCount += stash.entries.length
+        }
+      }
+
+      if (stash) {
+        for (const entry of stash.entries) {
+          const entryPath = entry.entry
+            ? path.join(dirPath, entry.entry)
+            : files[0] || dirPath
+          allEntries.push({ entry, path: entryPath, dirPath })
+        }
+      }
+    }
+  }
+
+  // Build TF-IDF index
+  const adapter = new TfIdfAdapter()
+  const scoredEntries: ScoredEntry[] = allEntries.map((ie) => ({
+    id: `${ie.entry.type}:${ie.entry.name}`,
+    text: buildSearchText(ie.entry),
+    entry: ie.entry,
+    path: ie.path,
+  }))
+  adapter.buildIndex(scoredEntries)
+
+  // Persist index
+  const indexPath = getIndexPath()
+  const indexDir = path.dirname(indexPath)
+  if (!fs.existsSync(indexDir)) {
+    fs.mkdirSync(indexDir, { recursive: true })
+  }
+
+  const index: SearchIndex = {
+    version: INDEX_VERSION,
+    builtAt: new Date().toISOString(),
+    stashDir,
+    entries: allEntries,
+    tfidf: adapter.serialize(),
+  }
+  fs.writeFileSync(indexPath, JSON.stringify(index) + "\n", "utf8")
+
+  return {
+    stashDir,
+    totalEntries: allEntries.length,
+    generatedMetadata: generatedCount,
+    indexPath,
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function collectDirectoryGroups(
+  typeRoot: string,
+  assetType: AgentikitAssetType,
+): Map<string, string[]> {
+  const groups = new Map<string, string[]>()
+
+  const walk = (dir: string): void => {
+    if (!fs.existsSync(dir)) return
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name === ".stash.json") continue
+      const fullPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walk(fullPath)
+      } else if (entry.isFile() && isRelevantFile(entry.name, assetType)) {
+        const parentDir = path.dirname(fullPath)
+        const existing = groups.get(parentDir)
+        if (existing) {
+          existing.push(fullPath)
+        } else {
+          groups.set(parentDir, [fullPath])
+        }
+      }
+    }
+  }
+
+  walk(typeRoot)
+  return groups
+}
+
+function isRelevantFile(fileName: string, assetType: AgentikitAssetType): boolean {
+  const ext = path.extname(fileName).toLowerCase()
+  switch (assetType) {
+    case "tool":
+      return SCRIPT_EXTENSIONS.has(ext)
+    case "skill":
+      return fileName === "SKILL.md"
+    case "command":
+    case "agent":
+      return ext === ".md"
+    default:
+      return false
+  }
+}
+
+export function buildSearchText(entry: StashEntry): string {
+  const parts: string[] = [entry.name.replace(/[-_]/g, " ")]
+  if (entry.description) parts.push(entry.description)
+  if (entry.tags) parts.push(entry.tags.join(" "))
+  if (entry.examples) parts.push(entry.examples.join(" "))
+  if (entry.intent) {
+    if (entry.intent.when) parts.push(entry.intent.when)
+    if (entry.intent.input) parts.push(entry.intent.input)
+    if (entry.intent.output) parts.push(entry.intent.output)
+  }
+  return parts.join(" ").toLowerCase()
+}
+
+function resolveStashDirForIndex(): string {
+  const raw = process.env.AGENTIKIT_STASH_DIR?.trim()
+  if (!raw) {
+    throw new Error("AGENTIKIT_STASH_DIR is not set. Run 'agentikit init' first.")
+  }
+  const stashDir = path.resolve(raw)
+  if (!fs.existsSync(stashDir) || !fs.statSync(stashDir).isDirectory()) {
+    throw new Error(`AGENTIKIT_STASH_DIR does not exist or is not a directory: "${stashDir}"`)
+  }
+  return stashDir
+}

package/src/metadata.ts

@@ -0,0 +1,249 @@
+import fs from "node:fs"
+import path from "node:path"
+import type { AgentikitAssetType } from "./stash"
+
+// ── Schema ──────────────────────────────────────────────────────────────────
+
+export interface StashIntent {
+  when?: string
+  input?: string
+  output?: string
+}
+
+export interface StashEntry {
+  name: string
+  type: AgentikitAssetType
+  description?: string
+  tags?: string[]
+  examples?: string[]
+  intent?: StashIntent
+  entry?: string
+  generated?: boolean
+}
+
+export interface StashFile {
+  entries: StashEntry[]
+}
+
+// ── Load / Write ────────────────────────────────────────────────────────────
+
+const STASH_FILENAME = ".stash.json"
+
+export function stashFilePath(dirPath: string): string {
+  return path.join(dirPath, STASH_FILENAME)
+}
+
+export function loadStashFile(dirPath: string): StashFile | null {
+  const filePath = stashFilePath(dirPath)
+  if (!fs.existsSync(filePath)) return null
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf8"))
+    if (!raw || !Array.isArray(raw.entries)) return null
+    const entries: StashEntry[] = []
+    for (const e of raw.entries) {
+      const validated = validateStashEntry(e)
+      if (validated) entries.push(validated)
+    }
+    return entries.length > 0 ? { entries } : null
+  } catch {
+    return null
+  }
+}
+
+export function writeStashFile(dirPath: string, stash: StashFile): void {
+  const filePath = stashFilePath(dirPath)
+  fs.writeFileSync(filePath, JSON.stringify(stash, null, 2) + "\n", "utf8")
+}
+
+export function validateStashEntry(entry: unknown): StashEntry | null {
+  if (typeof entry !== "object" || entry === null) return null
+  const e = entry as Record<string, unknown>
+  if (typeof e.name !== "string" || !e.name) return null
+  if (typeof e.type !== "string" || !isValidType(e.type)) return null
+
+  const result: StashEntry = {
+    name: e.name,
+    type: e.type as AgentikitAssetType,
+  }
+  if (typeof e.description === "string" && e.description) result.description = e.description
+  if (Array.isArray(e.tags)) result.tags = e.tags.filter((t): t is string => typeof t === "string")
+  if (Array.isArray(e.examples)) result.examples = e.examples.filter((x): x is string => typeof x === "string")
+  if (typeof e.intent === "object" && e.intent !== null) {
+    const intent = e.intent as Record<string, unknown>
+    result.intent = {}
+    if (typeof intent.when === "string") result.intent.when = intent.when
+    if (typeof intent.input === "string") result.intent.input = intent.input
+    if (typeof intent.output === "string") result.intent.output = intent.output
+  }
+  if (typeof e.entry === "string" && e.entry) result.entry = e.entry
+  if (e.generated === true) result.generated = true
+
+  return result
+}
+
+function isValidType(type: string): boolean {
+  return type === "tool" || type === "skill" || type === "command" || type === "agent"
+}
+
+// ── Metadata Generation ─────────────────────────────────────────────────────
+
+const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"])
+
+export function generateMetadata(
+  dirPath: string,
+  assetType: AgentikitAssetType,
+  files: string[],
+): StashFile {
+  const entries: StashEntry[] = []
+
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase()
+    const baseName = path.basename(file, ext)
+
+    // Skip non-relevant files
+    if (assetType === "tool" && !SCRIPT_EXTENSIONS.has(ext)) continue
+    if ((assetType === "command" || assetType === "agent") && ext !== ".md") continue
+    if (assetType === "skill" && path.basename(file) !== "SKILL.md") continue
+
+    const entry: StashEntry = {
+      name: baseName,
+      type: assetType,
+      generated: true,
+    }
+
+    // Priority 3: package.json metadata
+    const pkgMeta = extractPackageMetadata(dirPath)
+    if (pkgMeta) {
+      if (pkgMeta.description && !entry.description) entry.description = pkgMeta.description
+      if (pkgMeta.keywords && pkgMeta.keywords.length > 0) entry.tags = pkgMeta.keywords
+    }
+
+    // Priority 2: Frontmatter (for .md files)
+    if (ext === ".md") {
+      const fm = extractFrontmatterDescription(file)
+      if (fm) entry.description = fm
+    }
+
+    // Priority 4: Code comments (for script files)
+    if (SCRIPT_EXTENSIONS.has(ext) && ext !== ".md") {
+      const commentDesc = extractDescriptionFromComments(file)
+      if (commentDesc && !entry.description) entry.description = commentDesc
+    }
+
+    // Priority 5: Filename heuristics (fallback)
+    if (!entry.description) {
+      entry.description = fileNameToDescription(baseName)
+    }
+    if (!entry.tags || entry.tags.length === 0) {
+      entry.tags = extractTagsFromPath(file, dirPath)
+    }
+
+    entry.entry = path.basename(file)
+    entries.push(entry)
+  }
+
+  return { entries }
+}
+
+export function extractDescriptionFromComments(filePath: string): string | null {
+  let content: string
+  try {
+    content = fs.readFileSync(filePath, "utf8")
+  } catch {
+    return null
+  }
+
+  const lines = content.split(/\r?\n/).slice(0, 50)
+
+  // Try JSDoc-style block comment: /** ... */
+  const blockStart = lines.findIndex((l) => /^\s*\/\*\*/.test(l))
+  if (blockStart >= 0) {
+    const desc: string[] = []
+    for (let i = blockStart; i < lines.length; i++) {
+      const line = lines[i]
+      if (i > blockStart && /\*\//.test(line)) break
+      const cleaned = line.replace(/^\s*\/?\*\*?\s?/, "").replace(/\*\/\s*$/, "").trim()
+      if (cleaned) desc.push(cleaned)
+    }
+    if (desc.length > 0) return desc.join(" ")
+  }
+
+  // Try hash comments at start of file (skip shebang)
+  let start = 0
+  if (lines[0]?.startsWith("#!")) start = 1
+  const hashLines: string[] = []
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i].trim()
+    if (line.startsWith("#") && !line.startsWith("#!")) {
+      hashLines.push(line.replace(/^#+\s*/, "").trim())
+    } else if (line === "") {
+      continue
+    } else {
+      break
+    }
+  }
+  if (hashLines.length > 0) return hashLines.join(" ")
+
+  return null
+}
+
+export function extractFrontmatterDescription(filePath: string): string | null {
+  let content: string
+  try {
+    content = fs.readFileSync(filePath, "utf8")
+  } catch {
+    return null
+  }
+
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return null
+
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^description:\s*"?(.+?)"?\s*$/)
+    if (m) return m[1]
+  }
+  return null
+}
+
+export function extractPackageMetadata(
+  dirPath: string,
+): { name?: string; description?: string; keywords?: string[] } | null {
+  const pkgPath = path.join(dirPath, "package.json")
+  if (!fs.existsSync(pkgPath)) return null
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+    const result: { name?: string; description?: string; keywords?: string[] } = {}
+    if (typeof pkg.name === "string") result.name = pkg.name
+    if (typeof pkg.description === "string") result.description = pkg.description
+    if (Array.isArray(pkg.keywords)) {
+      result.keywords = pkg.keywords.filter((k: unknown): k is string => typeof k === "string")
+    }
+    return Object.keys(result).length > 0 ? result : null
+  } catch {
+    return null
+  }
+}
+
+export function fileNameToDescription(fileName: string): string {
+  return fileName
+    .replace(/[-_]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .trim()
+}
+
+export function extractTagsFromPath(filePath: string, rootDir: string): string[] {
+  const rel = path.relative(rootDir, filePath)
+  const parts = rel.split(path.sep)
+  const tags = new Set<string>()
+
+  for (const part of parts) {
+    const name = part.replace(path.extname(part), "")
+    for (const token of name.split(/[-_./\\]+/)) {
+      const clean = token.toLowerCase().trim()
+      if (clean && clean.length > 1) tags.add(clean)
+    }
+  }
+
+  return Array.from(tags)
+}

package/src/plugin.ts

@@ -0,0 +1,56 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+import { agentikitOpen, agentikitRun, agentikitSearch } from "./stash"
+import { agentikitIndex } from "./indexer"
+
+function tryJson(fn: () => unknown, action: string): string {
+  try {
+    return JSON.stringify(fn())
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    return JSON.stringify({ ok: false, error: `Failed to ${action}: ${message}` })
+  }
+}
+
+export const plugin: Plugin = async () => ({
+  tool: {
+    agentikit_search: tool({
+      description: "Search the Agentikit stash for tools, skills, commands, and agents.",
+      args: {
+        query: tool.schema.string().describe("Case-insensitive substring search."),
+        type: tool.schema
+          .enum(["tool", "skill", "command", "agent", "any"])
+          .optional()
+          .describe("Optional type filter. Defaults to 'any'."),
+        limit: tool.schema.number().optional().describe("Maximum number of hits to return. Defaults to 20."),
+      },
+      async execute({ query, type, limit }) {
+        return tryJson(() => agentikitSearch({ query, type, limit }), "search Agentikit stash")
+      },
+    }),
+    agentikit_open: tool({
+      description: "Open a stash asset from an openRef returned by agentikit_search.",
+      args: {
+        ref: tool.schema.string().describe("Open reference returned by agentikit_search."),
+      },
+      async execute({ ref }) {
+        return tryJson(() => agentikitOpen({ ref }), "open stash asset")
+      },
+    }),
+    agentikit_run: tool({
+      description: "Run a tool from the Agentikit stash by its openRef. Only tool refs are supported.",
+      args: {
+        ref: tool.schema.string().describe("Open reference of a tool returned by agentikit_search."),
+      },
+      async execute({ ref }) {
+        return tryJson(() => agentikitRun({ ref }), "run stash tool")
+      },
+    }),
+    agentikit_index: tool({
+      description: "Build or rebuild the Agentikit search index. Scans stash directories, generates missing .stash.json metadata, and builds a semantic search index.",
+      args: {},
+      async execute() {
+        return tryJson(() => agentikitIndex(), "build Agentikit index")
+      },
+    }),
+  },
+})