agentikit 0.0.7 → 0.0.9

package/README.md

@@ -1,15 +1,17 @@
 # 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**.
+Agentikit is a CLI tool and library for managing a stash of extension assets for AI coding assistants. It lets you **search** and **show** tools, skills, commands, and agents from a stash directory.
+
+The CLI is called **akm** (Agentikit Manager).
 
 ## Installation
 
 ### npm / bun
 
 ```sh
-npm install @itlackey/agentikit
+npm install -g agentikit
 # or
-bun add @itlackey/agentikit
+bun add -g agentikit
 ```
 
 ### Standalone binary
@@ -17,131 +19,268 @@ bun add @itlackey/agentikit
 Use the install scripts for a copy/paste install:
 
 ```sh
-# macOS / Linux (recommended: pin a release tag)
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
+# 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
+irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
 ```
 
 The shell installer verifies the downloaded binary against release `checksums.txt` before installing it.
 
-### OpenCode plugin
+## Stash model
 
-Add agentikit to the `plugin` array in your OpenCode config (`opencode.json`):
+Set a stash path via `AGENTIKIT_STASH_DIR`, or run `akm init` to create one automatically.
 
-```json
-{
-  "plugin": ["@itlackey/agentikit"]
-}
+```sh
+export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
 ```
 
-### Claude Code plugin
+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
+└── knowledge/  # markdown files
+```
 
-Install agentikit as a Claude Code plugin by pointing to the repo directory:
+## CLI usage
 
 ```sh
-claude --plugin-dir /path/to/agentikit
+akm init                 # Initialize stash directory and set AGENTIKIT_STASH_DIR
+akm index [--full]       # Build search index (incremental by default)
+akm add <ref>            # Install a registry kit by npm/GitHub ref
+akm list                 # List installed registry kits from config.registry.installed
+akm remove <target>      # Remove installed kit by id/ref (or parsed ref id)
+akm update [target] [--all]     # Fresh install from current ref(s), report changed revision/version
+akm reinstall [target] [--all]  # Reinstall from stored refs
+akm search [query]       # Search local stash and/or registry
+akm show <type:name>     # Read a stash asset by ref
 ```
 
-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.
+### add
 
-Once installed, the plugin provides:
+Install a registry reference and make it searchable immediately.
 
-- **Skill** (`agentikit:stash`) — Claude automatically uses this when you ask about stash assets
-- **Commands** — `/agentikit:search`, `/agentikit:open`, `/agentikit:run` slash commands
+```sh
+akm add @scope/kit
+akm add npm:@scope/kit@latest
+akm add owner/repo
+akm add github:owner/repo#v1.2.3
+```
 
-## Stash model
+- Uses registry resolution + install helpers (`npm` and `github` refs)
+- Updates `config.json` registry install records and syncs `additionalStashDirs`
+- If an existing install with the same id is replaced, old cache directories are cleaned up (best effort)
+- Triggers an incremental index build
+- Returns JSON with install details and index stats
 
-Set a stash path via `AGENTIKIT_STASH_DIR`.
+### list
+
+Show installed entries from `config.registry.installed`.
+
+- Source of truth is config, not cache directory discovery
+- Each entry includes status flags:
+  - `status.cacheDirExists`
+  - `status.stashRootExists`
+
+### remove
+
+Remove a single installed entry and reindex incrementally.
 
 ```sh
-export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
+akm remove npm:@scope/kit
+akm remove github:owner/repo
+akm remove owner/repo
 ```
 
-Expected stash layout:
+- Target resolution order: exact `id`, exact stored `ref`, then parsed ref `id`
+- Removes entry via config helper (also syncs `additionalStashDirs`)
+- Deletes prior `cacheDir` best effort
+- Runs one incremental reindex
 
-```
-$AGENTIKIT_STASH_DIR/
-├── tools/      # recursive files (.sh, .ts, .js, .ps1, .cmd, .bat)
-├── skills/     # skill directories containing SKILL.md
-├── commands/   # markdown files
-└── agents/     # markdown files
+### reinstall
+
+Reinstall one entry or all entries from stored refs.
+
+```sh
+akm reinstall npm:@scope/kit
+akm reinstall --all
 ```
 
-## Tools
+- Uses the same registry install flow as `akm add`
+- Upserts config entries + `additionalStashDirs`
+- Cleans up replaced cache directories best effort
+- Runs one incremental reindex after all installs
 
-When loaded as a plugin (OpenCode or Claude Code), Agentikit provides three tools:
+### update
 
-- `agentikit_search({ query, type?, limit? })`
-- `agentikit_open({ ref })`
-- `agentikit_run({ ref })`
+Update one entry or all entries by doing a fresh resolve/install from each current ref.
 
-### `agentikit_search`
+```sh
+akm update npm:@scope/kit
+akm update --all
+```
+
+- Same target selection rules as `reinstall`
+- Floating refs (for example `@latest` or default branch) resolve to newest available artifact
+- Reports per-entry change flags for version/revision (`changed.version`, `changed.revision`, `changed.any`)
+- Runs one incremental reindex after all installs
 
-Search the stash for extension assets.
+### search
+
+Search local stash assets, registry entries, or both.
+
+```sh
+akm search "deploy" --type tool --limit 10 --usage both
+akm search "lint" --source registry
+akm search "docker" --source both
+```
 
 - `query`: case-insensitive substring over stable names (relative paths)
-- `type`: `tool | skill | command | agent | any` (default: `any`)
-- `limit`: defaults to `20`
+- `--type`: `tool | skill | command | agent | knowledge | any` (default: `any`)
+- `--limit`: defaults to `20`
+- `--usage`: `none | both | item | guide` (default: `both`)
+- `--source`: `local | registry | both` (default: `local`)
+
+By default (`--source local`), results are the existing stash hits with `openRef`, score/explainability details (`score`, `whyMatched`), and, for tools, execution-ready `runCmd`.
 
-Returns typed hits with `openRef` and, for tools, execution-ready `runCmd`.
+When registry results are included (`--source registry|both`), each registry hit includes explicit install guidance:
 
-Tool command generation:
+- `installRef` (normalized ref for install)
+- `installCmd` (ready-to-run command, e.g. `akm add npm:@scope/kit`)
 
-- `.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
+- `usageGuide` is included by default (`--usage both`) and explains how to use each hit type.
+- Per-hit `usage` is optional metadata from `.stash.json` and is included when present.
 
-### `agentikit_open`
+### show
 
-Open a hit using `openRef` from search results.
+Show a hit using `openRef` from search results.
+
+```sh
+akm show skill:code-review
+akm show knowledge:guide.md --view toc
+akm show knowledge:guide.md --view section --heading "Getting Started"
+akm show knowledge:guide.md --view lines --start 10 --end 30
+```
 
 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`
+- `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` (the agent uses the host's shell to execute `runCmd`)
+- `knowledge` — content with optional view modes (`full`, `toc`, `frontmatter`, `section`, `lines`)
+
+## Library API
+
+Agentikit also exports its core functions for use as a library:
+
+```ts
+import {
+  agentikitAdd,
+  agentikitList,
+  agentikitRemove,
+  agentikitReinstall,
+  agentikitUpdate,
+  agentikitSearch,
+  agentikitShow,
+  agentikitInit,
+  agentikitIndex,
+} from "agentikit"
+```
 
-### `agentikit_run`
+- `agentikitAdd({ ref })` — install a registry reference and index it
+- `agentikitList()` — list installed registry entries and filesystem status flags
+- `agentikitRemove({ target })` — remove one installed entry and reindex incrementally
+- `agentikitReinstall({ target? , all? })` — reinstall one/all installed entries
+- `agentikitUpdate({ target? , all? })` — fresh resolve/install one/all installed entries with change reporting
+- `agentikitSearch({ query, type?, limit?, usage?, source? })` — search local stash and/or registry
+- `agentikitShow({ ref, view? })` — show a stash asset
+- `agentikitInit()` — initialize stash directory
+- `agentikitIndex()` — build/rebuild search index
 
-Execute a tool from the stash by its `openRef`. Only `tool:` refs are supported.
+## Configuration
 
-- `ref`: open reference of a tool returned by `agentikit_search`
+Agentikit stores configuration in `config.json` inside the stash directory.
 
-Returns `{ type, name, path, output, exitCode }`.
+```sh
+akm config                    # Show current config
+akm config --set key=value    # Update a config key
+```
 
-## Usage example
+### Embedding connection
 
-1. `agentikit_search({ query: "deploy", type: "tool" })`
-2. `agentikit_run({ ref: "<openRef from search>" })`
+By default, agentikit uses the local `@xenova/transformers` library for embeddings. You can configure an OpenAI-compatible embedding endpoint instead:
 
-Or:
+```sh
+akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
+```
 
-1. `agentikit_search({ query: "release", type: "command" })`
-2. `agentikit_open({ ref: "<openRef from search>" })`
-3. Apply returned template in-session
+To clear the custom embedding config and revert to local embeddings:
 
-## Package exports
+```sh
+akm config --set 'embedding=null'
+```
 
-- `plugin` — OpenCode plugin exposing `agentikit_search`, `agentikit_open`, and `agentikit_run`
-- `agentikitSearch` / `agentikitOpen` / `agentikitRun` — direct library APIs
+### LLM connection
 
-## Notes
+When configured, agentikit uses an OpenAI-compatible LLM to generate richer metadata (descriptions, intents, tags) during indexing:
 
-- Agentikit does not write to `.opencode/` or `.claude/`.
-- Agentikit does not install or copy kit files.
-- Missing or unreadable stash paths return friendly errors.
+```sh
+akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
+```
+
+To clear:
+
+```sh
+akm config --set 'llm=null'
+```
+
+### Using a local Ollama instance
+
+[Ollama](https://ollama.com) provides local models with an OpenAI-compatible API. After installing Ollama and pulling your models:
+
+```sh
+# Pull models
+ollama pull nomic-embed-text
+ollama pull llama3.2
+
+# Configure agentikit to use Ollama for both embeddings and metadata generation
+akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
+akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
 
-## Docs
+# Rebuild the index — embeddings use Ollama, metadata is LLM-enhanced
+akm index --full
+```
 
-- **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)
+Both `embedding` and `llm` accept an optional `apiKey` field for authenticated endpoints:
+
+```json
+{
+  "endpoint": "https://api.openai.com/v1/embeddings",
+  "model": "text-embedding-3-small",
+  "apiKey": "sk-..."
+}
+```
+
+### Config reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `semanticSearch` | `boolean` | `true` | Enable semantic search ranking |
+| `additionalStashDirs` | `string[]` | `[]` | Extra stash directories to search |
+| `embedding` | `object` | not set | OpenAI-compatible embedding endpoint (`endpoint`, `model`, `apiKey?`) |
+| `llm` | `object` | not set | OpenAI-compatible LLM endpoint (`endpoint`, `model`, `apiKey?`) |
+
+## Notes
+
+- `akm add` installs registry kits into the local cache and adds discovered stash roots to `additionalStashDirs`.
+- Registry lifecycle commands (`list`, `remove`, `reinstall`, `update`) use `config.registry.installed` as the source of truth.
+- When commands fail, CLI errors are returned as structured JSON with `error` and `hint` fields.
+- Missing or unreadable stash paths return friendly errors.

package/dist/index.d.ts

@@ -1,8 +1,22 @@
-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 { agentikitAdd, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, } from "./src/stash";
+export { agentikitInit } from "./src/init";
+export type { InitResponse } from "./src/init";
+export type { AgentikitAssetType, AgentikitSearchType, AddResponse, LocalSearchHit, RegistrySearchResultHit, SearchSource, SearchHit, SearchResponse, ShowResponse, KnowledgeView, ListResponse, RemoveResponse, ReinstallResponse, UpdateResponse, RegistryListEntry, RegistryInstallStatus, ReinstallResultItem, UpdateResultItem, } from "./src/stash";
+export type { ToolKind } from "./src/tool-runner";
 export { agentikitIndex } from "./src/indexer";
 export type { IndexResponse } from "./src/indexer";
 export type { StashEntry, StashFile, StashIntent } from "./src/metadata";
 export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
 export type { EnsureRgResult } from "./src/ripgrep";
+export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./src/markdown";
+export type { TocHeading, KnowledgeToc } from "./src/markdown";
+export { parseFrontmatter } from "./src/frontmatter";
+export { loadConfig, saveConfig, updateConfig } from "./src/config";
+export type { AgentikitConfig, EmbeddingConnectionConfig, LlmConnectionConfig, RegistryConfig } from "./src/config";
+export { parseRegistryRef, resolveRegistryArtifact } from "./src/registry-resolve";
+export { searchRegistry } from "./src/registry-search";
+export { installRegistryRef, upsertInstalledRegistryEntry, removeInstalledRegistryEntry, getRegistryCacheRootDir, detectStashRoot, } from "./src/registry-install";
+export type { RegistrySource, ParsedRegistryRef, ParsedNpmRef, ParsedGithubRef, ResolvedRegistryArtifact, RegistryInstalledEntry, RegistryInstallResult, RegistrySearchHit, RegistrySearchResponse, } from "./src/registry-types";
+export { enhanceMetadata, isLlmAvailable } from "./src/llm";
+export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";
+export type { EmbeddingVector } from "./src/embedder";

package/dist/index.js

@@ -1,4 +1,12 @@
-export { plugin } from "./src/plugin";
-export { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./src/stash";
+export { agentikitAdd, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, } from "./src/stash";
+export { agentikitInit } from "./src/init";
 export { agentikitIndex } from "./src/indexer";
 export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
+export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./src/markdown";
+export { parseFrontmatter } from "./src/frontmatter";
+export { loadConfig, saveConfig, updateConfig } from "./src/config";
+export { parseRegistryRef, resolveRegistryArtifact } from "./src/registry-resolve";
+export { searchRegistry } from "./src/registry-search";
+export { installRegistryRef, upsertInstalledRegistryEntry, removeInstalledRegistryEntry, getRegistryCacheRootDir, detectStashRoot, } from "./src/registry-install";
+export { enhanceMetadata, isLlmAvailable } from "./src/llm";
+export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";

package/dist/src/asset-spec.d.ts

@@ -0,0 +1,14 @@
+import type { AgentikitAssetType } from "./common";
+export declare const SCRIPT_EXTENSIONS: Set<string>;
+export interface AssetSpec {
+    stashDir: string;
+    isRelevantFile: (fileName: string) => boolean;
+    toCanonicalName: (typeRoot: string, filePath: string) => string | undefined;
+    toAssetPath: (typeRoot: string, name: string) => string;
+}
+export declare const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec>;
+export declare const ASSET_TYPES: AgentikitAssetType[];
+export declare const TYPE_DIRS: Record<AgentikitAssetType, string>;
+export declare function isRelevantAssetFile(assetType: AgentikitAssetType, fileName: string): boolean;
+export declare function deriveCanonicalAssetName(assetType: AgentikitAssetType, typeRoot: string, filePath: string): string | undefined;
+export declare function resolveAssetPathFromName(assetType: AgentikitAssetType, typeRoot: string, name: string): string;

package/dist/src/asset-spec.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
+const markdownSpec = {
+    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 = {
+    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);
+export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
+    acc[type] = ASSET_SPECS[type].stashDir;
+    return acc;
+}, {});
+export function isRelevantAssetFile(assetType, fileName) {
+    return ASSET_SPECS[assetType].isRelevantFile(fileName);
+}
+export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
+    return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath);
+}
+export function resolveAssetPathFromName(assetType, typeRoot, name) {
+    return ASSET_SPECS[assetType].toAssetPath(typeRoot, name);
+}
+function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}