agentikit 0.0.3

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "agentikit",
+  "description": "Search, open, and run extension assets from an Agentikit stash directory. Provides tools, skills, commands, and agents management for AI coding assistants.",
+  "version": "0.0.1",
+  "author": {
+    "name": "itlackey",
+    "url": "https://github.com/itlackey"
+  },
+  "homepage": "https://github.com/itlackey/agentikit#readme",
+  "repository": "https://github.com/itlackey/agentikit",
+  "license": "CC-BY-4.0",
+  "keywords": [
+    "agentikit",
+    "stash",
+    "tools",
+    "skills",
+    "commands",
+    "agents",
+    "plugin"
+  ]
+}

package/README.md

@@ -0,0 +1,147 @@
+# agentikit
+
+Agentikit is a stash toolkit for AI coding assistants. It exposes three tools so agents can **search**, **open**, and **run** extension assets directly from a stash directory. Works as both an **OpenCode plugin** and a **Claude Code plugin**.
+
+## Installation
+
+### npm / bun
+
+```sh
+npm install @itlackey/agentikit
+# or
+bun add @itlackey/agentikit
+```
+
+### Standalone binary
+
+Use the install scripts for a copy/paste install:
+
+```sh
+# macOS / Linux (recommended: pin a release tag)
+curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash -s -- v1.2.3
+```
+
+```sh
+# PowerShell (Windows)
+irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1 v1.2.3
+```
+
+The shell installer verifies the downloaded binary against release `checksums.txt` before installing it.
+
+### OpenCode plugin
+
+Add agentikit to the `plugin` array in your OpenCode config (`opencode.json`):
+
+```json
+{
+  "plugin": ["@itlackey/agentikit"]
+}
+```
+
+### Claude Code plugin
+
+Install agentikit as a Claude Code plugin by pointing to the repo directory:
+
+```sh
+claude --plugin-dir /path/to/agentikit
+```
+
+Or add it to a plugin marketplace for team distribution. See the [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins) for details.
+
+Once installed, the plugin provides:
+
+- **Skill** (`agentikit:stash`) — Claude automatically uses this when you ask about stash assets
+- **Commands** — `/agentikit:search`, `/agentikit:open`, `/agentikit:run` slash commands
+
+## Stash model
+
+Set a stash path via `AGENTIKIT_STASH_DIR`.
+
+```sh
+export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
+```
+
+Expected stash layout:
+
+```
+$AGENTIKIT_STASH_DIR/
+├── tools/      # recursive files (.sh, .ts, .js, .ps1, .cmd, .bat)
+├── skills/     # skill directories containing SKILL.md
+├── commands/   # markdown files
+└── agents/     # markdown files
+```
+
+## Tools
+
+When loaded as a plugin (OpenCode or Claude Code), Agentikit provides three tools:
+
+- `agentikit_search({ query, type?, limit? })`
+- `agentikit_open({ ref })`
+- `agentikit_run({ ref })`
+
+### `agentikit_search`
+
+Search the stash for extension assets.
+
+- `query`: case-insensitive substring over stable names (relative paths)
+- `type`: `tool | skill | command | agent | any` (default: `any`)
+- `limit`: defaults to `20`
+
+Returns typed hits with `openRef` and, for tools, execution-ready `runCmd`.
+
+Tool command generation:
+
+- `.sh` → `bash "<absolute-file>"`
+- `.ps1` → `powershell -ExecutionPolicy Bypass -File "<absolute-file>"`
+- `.cmd`/`.bat` → `cmd /c "<absolute-file>"`
+- `.ts`/`.js`:
+  - find nearest `package.json` from script dir upward to stash `tools/` root
+  - if found: `cd "<pkgDir>" && bun "<absolute-file>"`
+  - else: `bun "<absolute-file>"`
+  - optional: set `AGENTIKIT_BUN_INSTALL=true` to include `bun install` before running
+
+### `agentikit_open`
+
+Open a hit using `openRef` from search results.
+
+Returns full payload by type:
+
+- `skill` → full `SKILL.md` content
+- `command` → full markdown body as `template` (+ best-effort `description`)
+- `agent` → full markdown body as `prompt` (+ best-effort `description`, `toolPolicy`, `modelHint`)
+- `tool` → `runCmd`/`kind`
+
+### `agentikit_run`
+
+Execute a tool from the stash by its `openRef`. Only `tool:` refs are supported.
+
+- `ref`: open reference of a tool returned by `agentikit_search`
+
+Returns `{ type, name, path, output, exitCode }`.
+
+## Usage example
+
+1. `agentikit_search({ query: "deploy", type: "tool" })`
+2. `agentikit_run({ ref: "<openRef from search>" })`
+
+Or:
+
+1. `agentikit_search({ query: "release", type: "command" })`
+2. `agentikit_open({ ref: "<openRef from search>" })`
+3. Apply returned template in-session
+
+## Package exports
+
+- `plugin` — OpenCode plugin exposing `agentikit_search`, `agentikit_open`, and `agentikit_run`
+- `agentikitSearch` / `agentikitOpen` / `agentikitRun` — direct library APIs
+
+## Notes
+
+- Agentikit does not write to `.opencode/` or `.claude/`.
+- Agentikit does not install or copy kit files.
+- Missing or unreadable stash paths return friendly errors.
+
+## Docs
+
+- **OpenCode**: [Plugins](https://opencode.ai/docs/plugins/) · [Commands](https://opencode.ai/docs/commands/) · [Agents](https://opencode.ai/docs/agents/) · [Agent Skills](https://opencode.ai/docs/skills/) · [Custom tools](https://opencode.ai/docs/custom-tools/) · [Config](https://opencode.ai/docs/config/)
+- **Claude Code**: [Plugins](https://code.claude.com/docs/en/plugins) · [Skills](https://code.claude.com/docs/en/skills) · [Plugins reference](https://code.claude.com/docs/en/plugins-reference)

package/commands/open.md

@@ -0,0 +1,11 @@
+---
+description: Open an Agentikit stash asset by its openRef
+---
+
+Open an Agentikit stash asset using the CLI. Run:
+
+```bash
+agentikit open $ARGUMENTS
+```
+
+Parse the JSON output and present the asset content to the user based on its type (skill content, command template, agent prompt, or tool info).

package/commands/run.md

@@ -0,0 +1,11 @@
+---
+description: Run an Agentikit stash tool by its openRef
+---
+
+Run an Agentikit stash tool using the CLI. Run:
+
+```bash
+agentikit run $ARGUMENTS
+```
+
+Parse the JSON output and present the tool's output and exit code to the user.

package/commands/search.md

@@ -0,0 +1,11 @@
+---
+description: Search the Agentikit stash for tools, skills, commands, and agents using semantic search
+---
+
+Search the Agentikit stash using the CLI. If a search index exists, results are ranked by semantic relevance. Run `agentikit index` first to enable semantic search.
+
+```bash
+agentikit search $ARGUMENTS
+```
+
+Parse the JSON output and present the results to the user in a readable format. Include the `openRef` for each hit so the user can open or run assets. Results may include `description`, `tags`, and `score` fields when semantic search is active.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { plugin } from "./src/plugin";
+export { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./src/stash";
+export type { AgentikitAssetType, AgentikitSearchType, SearchHit, SearchResponse, OpenResponse, RunResponse, InitResponse, } from "./src/stash";
+export { agentikitIndex } from "./src/indexer";
+export type { IndexResponse } from "./src/indexer";
+export type { StashEntry, StashFile, StashIntent } from "./src/metadata";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { plugin } from "./src/plugin";
+export { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./src/stash";
+export { agentikitIndex } from "./src/indexer";

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,62 @@
+#!/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) {
+    const idx = args.indexOf(name);
+    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+function usage() {
+    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");
+        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/dist/src/indexer.d.ts

@@ -0,0 +1,26 @@
+import { type StashEntry } from "./metadata";
+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;
+}
+export declare function getIndexPath(): string;
+export declare function loadSearchIndex(): SearchIndex | null;
+export declare function agentikitIndex(options?: {
+    stashDir?: string;
+}): IndexResponse;
+export declare function buildSearchText(entry: StashEntry): string;

package/dist/src/indexer.js

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadStashFile, writeStashFile, generateMetadata, } from "./metadata";
+import { TfIdfAdapter } from "./similarity";
+// ── Constants ───────────────────────────────────────────────────────────────
+const INDEX_VERSION = 1;
+const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
+const TYPE_DIRS = {
+    tool: "tools",
+    skill: "skills",
+    command: "commands",
+    agent: "agents",
+};
+// ── Index Path ──────────────────────────────────────────────────────────────
+export function getIndexPath() {
+    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() {
+    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;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Indexer ──────────────────────────────────────────────────────────────────
+export function agentikitIndex(options) {
+    const stashDir = options?.stashDir || resolveStashDirForIndex();
+    const allEntries = [];
+    let generatedCount = 0;
+    for (const assetType of Object.keys(TYPE_DIRS)) {
+        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 = 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 = {
+        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, assetType) {
+    const groups = new Map();
+    const walk = (dir) => {
+        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, assetType) {
+    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) {
+    const parts = [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() {
+    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/dist/src/metadata.d.ts

@@ -0,0 +1,33 @@
+import type { AgentikitAssetType } from "./stash";
+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[];
+}
+export declare function stashFilePath(dirPath: string): string;
+export declare function loadStashFile(dirPath: string): StashFile | null;
+export declare function writeStashFile(dirPath: string, stash: StashFile): void;
+export declare function validateStashEntry(entry: unknown): StashEntry | null;
+export declare function generateMetadata(dirPath: string, assetType: AgentikitAssetType, files: string[]): StashFile;
+export declare function extractDescriptionFromComments(filePath: string): string | null;
+export declare function extractFrontmatterDescription(filePath: string): string | null;
+export declare function extractPackageMetadata(dirPath: string): {
+    name?: string;
+    description?: string;
+    keywords?: string[];
+} | null;
+export declare function fileNameToDescription(fileName: string): string;
+export declare function extractTagsFromPath(filePath: string, rootDir: string): string[];