agentikit 0.0.7 → 0.0.9

package/dist/src/tool-runner.js

@@ -0,0 +1,100 @@
+/**
+ * Tool execution utilities.
+ *
+ * Handles building run commands and executing tool scripts for all supported
+ * kinds (bash, bun, powershell, cmd).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { IS_WINDOWS, isWithin } from "./common";
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Build execution metadata for a tool file based on its extension.
+ *
+ * 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.
+ */
+export function buildToolInfo(stashDir, filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".sh") {
+        return {
+            runCmd: `bash ${shellQuote(filePath)}`,
+            kind: "bash",
+            execute: { command: "bash", args: [filePath] },
+        };
+    }
+    if (ext === ".ps1") {
+        return {
+            runCmd: `powershell -ExecutionPolicy Bypass -File ${shellQuote(filePath)}`,
+            kind: "powershell",
+            execute: { command: "powershell", args: ["-ExecutionPolicy", "Bypass", "-File", filePath] },
+        };
+    }
+    if (ext === ".cmd" || ext === ".bat") {
+        return {
+            runCmd: `cmd /c ${shellQuote(filePath)}`,
+            kind: "cmd",
+            execute: { command: "cmd", args: ["/c", filePath] },
+        };
+    }
+    if (ext !== ".ts" && ext !== ".js") {
+        throw new Error(`Unsupported tool extension: ${ext}`);
+    }
+    const toolsRoot = path.resolve(path.join(stashDir, "tools"));
+    const pkgDir = findNearestPackageDir(path.dirname(filePath), toolsRoot);
+    if (!pkgDir) {
+        return {
+            runCmd: `bun ${shellQuote(filePath)}`,
+            kind: "bun",
+            execute: { command: "bun", args: [filePath] },
+        };
+    }
+    const installFlag = process.env.AGENTIKIT_BUN_INSTALL;
+    const shouldInstall = installFlag === "1" || installFlag === "true" || installFlag === "yes";
+    const quotedPkgDir = shellQuote(pkgDir);
+    const quotedFilePath = shellQuote(filePath);
+    const cdCmd = IS_WINDOWS ? `cd /d ${quotedPkgDir}` : `cd ${quotedPkgDir}`;
+    const chain = IS_WINDOWS ? " & " : " && ";
+    return {
+        runCmd: shouldInstall
+            ? `${cdCmd}${chain}bun install${chain}bun ${quotedFilePath}`
+            : `${cdCmd}${chain}bun ${quotedFilePath}`,
+        kind: "bun",
+        install: shouldInstall ? { command: "bun", args: ["install"], cwd: pkgDir } : undefined,
+        execute: { command: "bun", args: [filePath], cwd: pkgDir },
+    };
+}
+/**
+ * Shell-quote a path for inclusion in a human-readable `runCmd` string.
+ */
+export function shellQuote(input) {
+    if (/[\r\n\t\0]/.test(input)) {
+        throw new Error("Unsupported control characters in stash path.");
+    }
+    if (IS_WINDOWS) {
+        return `"${input.replace(/"/g, '""')}"`;
+    }
+    const escaped = input
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\$/g, "\\$")
+        .replace(/`/g, "\\`");
+    return `"${escaped}"`;
+}
+/**
+ * Walk up from `startDir` toward `toolsRoot` looking for the nearest `package.json`.
+ */
+export function findNearestPackageDir(startDir, toolsRoot) {
+    let current = path.resolve(startDir);
+    const root = path.resolve(toolsRoot);
+    while (isWithin(current, root)) {
+        if (fs.existsSync(path.join(current, "package.json"))) {
+            return current;
+        }
+        if (current === root)
+            return undefined;
+        current = path.dirname(current);
+    }
+    return undefined;
+}

package/dist/src/walker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared filesystem walker for agentikit stash directories.
+ *
+ * Provides a single implementation used by both the search fallback
+ * (stash.ts) and the indexer (indexer.ts) to walk type-specific asset
+ * directories and group files by parent directory.
+ */
+import { type AgentikitAssetType } from "./common";
+export interface DirectoryGroup {
+    dirPath: string;
+    files: string[];
+}
+/**
+ * Walk a type root directory and return files grouped by their parent directory.
+ *
+ * Only files relevant to the given `assetType` are included (e.g. `.md` for
+ * commands, script extensions for tools, `SKILL.md` for skills).
+ */
+export declare function walkStash(typeRoot: string, assetType: AgentikitAssetType): DirectoryGroup[];

package/dist/src/walker.js

@@ -0,0 +1,47 @@
+/**
+ * Shared filesystem walker for agentikit stash directories.
+ *
+ * Provides a single implementation used by both the search fallback
+ * (stash.ts) and the indexer (indexer.ts) to walk type-specific asset
+ * directories and group files by parent directory.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isRelevantAssetFile } from "./asset-spec";
+/**
+ * Walk a type root directory and return files grouped by their parent directory.
+ *
+ * Only files relevant to the given `assetType` are included (e.g. `.md` for
+ * commands, script extensions for tools, `SKILL.md` for skills).
+ */
+export function walkStash(typeRoot, assetType) {
+    if (!fs.existsSync(typeRoot))
+        return [];
+    const groups = new Map();
+    const stack = [typeRoot];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = fs.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === ".stash.json")
+                continue;
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(fullPath);
+            }
+            else if (entry.isFile() && isRelevantAssetFile(assetType, entry.name)) {
+                const parentDir = path.dirname(fullPath);
+                const existing = groups.get(parentDir);
+                if (existing) {
+                    existing.push(fullPath);
+                }
+                else {
+                    groups.set(parentDir, [fullPath]);
+                }
+            }
+        }
+    }
+    return Array.from(groups, ([dirPath, files]) => ({ dirPath, files }));
+}

package/package.json

@@ -1,20 +1,14 @@
 {
   "name": "agentikit",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
-  "description": "Search, open, and run extension assets from a stash directory. Works as both an OpenCode plugin and a Claude Code plugin.",
+  "description": "CLI tool to search, open, and run extension assets from an agentikit stash directory.",
   "keywords": [
-    "opencode",
-    "opencode-ai",
-    "opencode-plugin",
-    "opencode-extensions",
-    "claude-code",
-    "claude-code-plugin",
     "agentikit",
     "ai-agent",
     "agent-framework",
     "developer-tools",
-    "plugin",
+    "cli",
     "tools",
     "skills",
     "commands"
@@ -31,13 +25,10 @@
   "files": [
     "dist",
     "src",
-    ".claude-plugin",
-    "skills",
-    "commands",
     "README.md"
   ],
   "bin": {
-    "agentikit": "dist/src/cli.js"
+    "akm": "dist/src/cli.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -60,7 +51,10 @@
     "@types/node": "^24.0.0",
     "typescript": "^5.9.3"
   },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.0"
+  },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.2.20"
+    "citty": "^0.2.1"
   }
 }

package/src/asset-spec.ts

@@ -0,0 +1,69 @@
+import path from "node:path"
+import type { AgentikitAssetType } from "./common"
+
+export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"])
+
+export interface AssetSpec {
+  stashDir: string
+  isRelevantFile: (fileName: string) => boolean
+  toCanonicalName: (typeRoot: string, filePath: string) => string | undefined
+  toAssetPath: (typeRoot: string, name: string) => string
+}
+
+const markdownSpec: Omit<AssetSpec, "stashDir"> = {
+  isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
+  toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+  toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+}
+
+export const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec> = {
+  tool: {
+    stashDir: "tools",
+    isRelevantFile: (fileName) => SCRIPT_EXTENSIONS.has(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+    toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+  },
+  skill: {
+    stashDir: "skills",
+    isRelevantFile: (fileName) => fileName === "SKILL.md",
+    toCanonicalName: (typeRoot, filePath) => {
+      const relDir = toPosix(path.dirname(path.relative(typeRoot, filePath)))
+      if (!relDir || relDir === ".") return undefined
+      return relDir
+    },
+    toAssetPath: (typeRoot, name) => path.join(typeRoot, name, "SKILL.md"),
+  },
+  command: { stashDir: "commands", ...markdownSpec },
+  agent: { stashDir: "agents", ...markdownSpec },
+  knowledge: { stashDir: "knowledge", ...markdownSpec },
+}
+
+export const ASSET_TYPES = Object.keys(ASSET_SPECS) as AgentikitAssetType[]
+
+export const TYPE_DIRS: Record<AgentikitAssetType, string> = ASSET_TYPES.reduce(
+  (acc, type) => {
+    acc[type] = ASSET_SPECS[type].stashDir
+    return acc
+  },
+  {} as Record<AgentikitAssetType, string>,
+)
+
+export function isRelevantAssetFile(assetType: AgentikitAssetType, fileName: string): boolean {
+  return ASSET_SPECS[assetType].isRelevantFile(fileName)
+}
+
+export function deriveCanonicalAssetName(
+  assetType: AgentikitAssetType,
+  typeRoot: string,
+  filePath: string,
+): string | undefined {
+  return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath)
+}
+
+export function resolveAssetPathFromName(assetType: AgentikitAssetType, typeRoot: string, name: string): string {
+  return ASSET_SPECS[assetType].toAssetPath(typeRoot, name)
+}
+
+function toPosix(input: string): string {
+  return input.replace(/\\/g, "/")
+}

package/src/cli.ts

@@ -1,60 +1,296 @@
 #!/usr/bin/env node
-import { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./stash"
+import { defineCommand, runMain } from "citty"
+import {
+  agentikitAdd,
+  agentikitList,
+  agentikitReinstall,
+  agentikitRemove,
+  agentikitSearch,
+  agentikitShow,
+  agentikitUpdate,
+  type KnowledgeView,
+} from "./stash"
+import type { SearchSource, SearchUsageMode } from "./stash-types"
+import { agentikitInit } from "./init"
 import { agentikitIndex } from "./indexer"
+import { loadConfig, updateConfig, type AgentikitConfig } from "./config"
+import { resolveStashDir } from "./common"
 
-const args = process.argv.slice(2)
-const command = args[0]
+const initCommand = defineCommand({
+  meta: { name: "init", description: "Initialize agentikit stash directory and set AGENTIKIT_STASH_DIR" },
+  run() {
+    return runWithJsonErrors(() => {
+      const result = agentikitInit()
+      console.log(JSON.stringify(result, null, 2))
+    })
+  },
+})
 
-function flag(name: string): string | undefined {
-  const idx = args.indexOf(name)
-  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined
+const indexCommand = defineCommand({
+  meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
+  args: {
+    full: { type: "boolean", description: "Force full reindex", default: false },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      const result = await agentikitIndex({ full: args.full })
+      console.log(JSON.stringify(result, null, 2))
+    })
+  },
+})
+
+const searchCommand = defineCommand({
+  meta: { name: "search", description: "Search the stash" },
+  args: {
+    query: { type: "positional", description: "Search query", required: false, default: "" },
+    type: { type: "string", description: "Asset type filter (tool|skill|command|agent|knowledge|any)" },
+    limit: { type: "string", description: "Maximum number of results" },
+    usage: { type: "string", description: "Usage metadata mode (none|both|item|guide)", default: "both" },
+    source: { type: "string", description: "Search source (local|registry|both)", default: "local" },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      const type = args.type as "tool" | "skill" | "command" | "agent" | "knowledge" | "any" | undefined
+      const limit = args.limit ? parseInt(args.limit, 10) : undefined
+      const usage = parseSearchUsageMode(args.usage)
+      const source = parseSearchSource(args.source)
+      console.log(JSON.stringify(await agentikitSearch({ query: args.query, type, limit, usage, source }), null, 2))
+    })
+  },
+})
+
+const addCommand = defineCommand({
+  meta: { name: "add", description: "Install a registry package into the stash" },
+  args: {
+    ref: { type: "positional", description: "Registry ref (npm package, owner/repo, or github URL)", required: true },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitAdd({ ref: args.ref }), null, 2))
+    })
+  },
+})
+
+const listCommand = defineCommand({
+  meta: { name: "list", description: "List installed registry packages from config" },
+  async run() {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitList(), null, 2))
+    })
+  },
+})
+
+const removeCommand = defineCommand({
+  meta: { name: "remove", description: "Remove an installed registry package by id or ref" },
+  args: {
+    target: { type: "positional", description: "Installed target (id or ref)", required: true },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitRemove({ target: args.target }), null, 2))
+    })
+  },
+})
+
+const updateCommand = defineCommand({
+  meta: { name: "update", description: "Update one or all installed registry packages" },
+  args: {
+    target: { type: "positional", description: "Installed target (id or ref)", required: false },
+    all: { type: "boolean", description: "Update all installed entries", default: false },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitUpdate({ target: args.target, all: args.all }), null, 2))
+    })
+  },
+})
+
+const reinstallCommand = defineCommand({
+  meta: { name: "reinstall", description: "Reinstall one or all installed registry packages" },
+  args: {
+    target: { type: "positional", description: "Installed target (id or ref)", required: false },
+    all: { type: "boolean", description: "Reinstall all installed entries", default: false },
+  },
+  async run({ args }) {
+    await runWithJsonErrors(async () => {
+      console.log(JSON.stringify(await agentikitReinstall({ target: args.target, all: args.all }), null, 2))
+    })
+  },
+})
+
+const showCommand = defineCommand({
+  meta: { name: "show", description: "Show a stash asset by ref (e.g. agent:bunjs-typescript-coder.md)" },
+  args: {
+    ref: { type: "positional", description: "Asset ref (type:name)", required: true },
+    view: { type: "string", description: "Knowledge view mode (full|toc|frontmatter|section|lines)" },
+    heading: { type: "string", description: "Section heading (for --view section)" },
+    start: { type: "string", description: "Start line (for --view lines)" },
+    end: { type: "string", description: "End line (for --view lines)" },
+  },
+  run({ args }) {
+    return runWithJsonErrors(() => {
+      let view: KnowledgeView | undefined
+      if (args.view) {
+        switch (args.view) {
+          case "section":
+            view = { mode: "section", heading: args.heading ?? "" }
+            break
+          case "lines":
+            view = {
+              mode: "lines",
+              start: Number(args.start ?? "1"),
+              end: args.end ? parseInt(args.end, 10) : Number.MAX_SAFE_INTEGER,
+            }
+            break
+          case "toc":
+          case "frontmatter":
+          case "full":
+            view = { mode: args.view }
+            break
+          default:
+            throw new Error(`Unknown view mode: ${args.view}. Expected one of: full|toc|frontmatter|section|lines`)
+        }
+      }
+      console.log(JSON.stringify(agentikitShow({ ref: args.ref, view }), null, 2))
+    })
+  },
+})
+
+const configCommand = defineCommand({
+  meta: { name: "config", description: "Show or update configuration" },
+  args: {
+    set: { type: "string", description: "Update a config key (key=value format)" },
+  },
+  run({ args }) {
+    return runWithJsonErrors(() => {
+      const stashDir = resolveStashDir()
+
+      if (args.set) {
+        const eqIndex = args.set.indexOf("=")
+        if (eqIndex === -1) {
+          throw new Error("--set expects key=value format")
+        }
+        const key = args.set.slice(0, eqIndex)
+        const value = args.set.slice(eqIndex + 1)
+        const partial = parseConfigValue(key, value)
+        const config = updateConfig(partial, stashDir)
+        console.log(JSON.stringify(config, null, 2))
+      } else {
+        const config = loadConfig(stashDir)
+        console.log(JSON.stringify(config, null, 2))
+      }
+    })
+  },
+})
+
+const main = defineCommand({
+  meta: {
+    name: "akm",
+    description: "CLI tool to search, open, and run extension assets from an agentikit stash directory.",
+  },
+  subCommands: {
+    init: initCommand,
+    index: indexCommand,
+    add: addCommand,
+    list: listCommand,
+    remove: removeCommand,
+    update: updateCommand,
+    reinstall: reinstallCommand,
+    search: searchCommand,
+    show: showCommand,
+    config: configCommand,
+  },
+})
+
+runMain(main)
+
+const SEARCH_USAGE_MODES: SearchUsageMode[] = ["none", "both", "item", "guide"]
+const SEARCH_SOURCES: SearchSource[] = ["local", "registry", "both"]
+
+function parseSearchUsageMode(value: string): SearchUsageMode {
+  if ((SEARCH_USAGE_MODES as string[]).includes(value)) return value as SearchUsageMode
+  throw new Error(`Invalid value for --usage: ${value}. Expected one of: ${SEARCH_USAGE_MODES.join("|")}`)
 }
 
-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)
+function parseSearchSource(value: string): SearchSource {
+  if ((SEARCH_SOURCES as string[]).includes(value)) return value as SearchSource
+  throw new Error(`Invalid value for --source: ${value}. Expected one of: ${SEARCH_SOURCES.join("|")}`)
 }
 
-switch (command) {
-  case "init": {
-    const result = agentikitInit()
-    console.log(JSON.stringify(result, null, 2))
-    break
+function parseConnectionValue(
+  key: string,
+  value: string,
+  exampleEndpoint: string,
+  exampleModel: string,
+): { endpoint: string; model: string; apiKey?: string } | undefined {
+  if (value === "null" || value === "") return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(value)
+  } catch {
+    throw new Error(
+      `Invalid value for ${key}: expected JSON object with endpoint and model`
+      + ` (e.g. '{"endpoint":"${exampleEndpoint}","model":"${exampleModel}"}')`,
+    )
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Invalid value for ${key}: expected a JSON object`)
   }
-  case "index": {
-    const result = agentikitIndex()
-    console.log(JSON.stringify(result, null, 2))
-    break
+  const obj = parsed as Record<string, unknown>
+  if (typeof obj.endpoint !== "string" || !obj.endpoint || typeof obj.model !== "string" || !obj.model) {
+    throw new Error(`Invalid value for ${key}: "endpoint" and "model" are required string fields`)
   }
-  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
+  const result: { endpoint: string; model: string; apiKey?: string } = {
+    endpoint: obj.endpoint,
+    model: obj.model,
   }
-  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
+  if (typeof obj.apiKey === "string" && obj.apiKey) {
+    result.apiKey = obj.apiKey
+  }
+  return result
+}
+
+function parseConfigValue(key: string, value: string): Partial<AgentikitConfig> {
+  switch (key) {
+    case "semanticSearch":
+      if (value !== "true" && value !== "false") {
+        throw new Error(`Invalid value for semanticSearch: expected "true" or "false"`)
+      }
+      return { semanticSearch: value === "true" }
+    case "additionalStashDirs":
+      try {
+        const parsed = JSON.parse(value)
+        if (!Array.isArray(parsed)) throw new Error("expected JSON array")
+        return { additionalStashDirs: parsed.filter((d: unknown): d is string => typeof d === "string") }
+      } catch {
+        throw new Error(`Invalid value for additionalStashDirs: expected JSON array (e.g. '["/path/a","/path/b"]')`)
+      }
+    case "embedding":
+      return { embedding: parseConnectionValue("embedding", value, "http://localhost:11434/v1/embeddings", "nomic-embed-text") }
+    case "llm":
+      return { llm: parseConnectionValue("llm", value, "http://localhost:11434/v1/chat/completions", "llama3.2") }
+    default:
+      throw new Error(`Unknown config key: ${key}`)
   }
-  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
+}
+
+async function runWithJsonErrors(fn: (() => void) | (() => Promise<void>)): Promise<void> {
+  try {
+    await fn()
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    const hint = buildHint(message)
+    console.error(JSON.stringify({ ok: false, error: message, hint }, null, 2))
+    process.exit(1)
   }
-  default:
-    usage()
+}
+
+function buildHint(message: string): string | undefined {
+  if (message.includes("AGENTIKIT_STASH_DIR")) return "Run `akm init` or set AGENTIKIT_STASH_DIR to a valid directory."
+  if (message.includes("Either <target> or --all is required")) return "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg`."
+  if (message.includes("Specify either <target> or --all")) return "Use only one: a positional target or `--all`."
+  if (message.includes("No installed registry entry matched target")) return "Run `akm list` to view installed ids/refs, then retry with one of those values."
+  if (message.includes("Invalid value for --source")) return "Pick one of: local, registry, both."
+  if (message.includes("Invalid value for --usage")) return "Pick one of: none, both, item, guide."
+  return undefined
 }