agentikit 0.0.8 → 0.0.9

package/README.md

@@ -54,23 +54,109 @@ $AGENTIKIT_STASH_DIR/
 ```sh
 akm init                 # Initialize stash directory and set AGENTIKIT_STASH_DIR
 akm index [--full]       # Build search index (incremental by default)
-akm search [query]       # Search the stash
+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
 ```
 
+### add
+
+Install a registry reference and make it searchable immediately.
+
+```sh
+akm add @scope/kit
+akm add npm:@scope/kit@latest
+akm add owner/repo
+akm add github:owner/repo#v1.2.3
+```
+
+- 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
+
+### 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
+akm remove npm:@scope/kit
+akm remove github:owner/repo
+akm remove owner/repo
+```
+
+- 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
+
+### reinstall
+
+Reinstall one entry or all entries from stored refs.
+
+```sh
+akm reinstall npm:@scope/kit
+akm reinstall --all
+```
+
+- 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
+
+### update
+
+Update one entry or all entries by doing a fresh resolve/install from each current ref.
+
+```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
 
-Search the stash for extension assets.
+Search local stash assets, registry entries, or both.
 
 ```sh
-akm search "deploy" --type tool --limit 10
+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 | 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`.
+
+When registry results are included (`--source registry|both`), each registry hit includes explicit install guidance:
+
+- `installRef` (normalized ref for install)
+- `installCmd` (ready-to-run command, e.g. `akm add npm:@scope/kit`)
 
-Returns typed hits with `openRef`, score/explainability details (`score`, `whyMatched`), and, for tools, execution-ready `runCmd`.
+- `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.
 
 ### show
 
@@ -96,10 +182,25 @@ Returns full payload by type:
 Agentikit also exports its core functions for use as a library:
 
 ```ts
-import { agentikitSearch, agentikitShow, agentikitInit, agentikitIndex } from "agentikit"
+import {
+  agentikitAdd,
+  agentikitList,
+  agentikitRemove,
+  agentikitReinstall,
+  agentikitUpdate,
+  agentikitSearch,
+  agentikitShow,
+  agentikitInit,
+  agentikitIndex,
+} from "agentikit"
 ```
 
-- `agentikitSearch({ query, type?, limit? })` — search the stash
+- `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
@@ -179,5 +280,7 @@ Both `embedding` and `llm` accept an optional `apiKey` field for authenticated e
 
 ## Notes
 
-- Agentikit does not install or copy kit files.
+- `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,7 +1,7 @@
-export { agentikitSearch, agentikitShow } 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, SearchHit, SearchResponse, ShowResponse, KnowledgeView, } from "./src/stash";
+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";
@@ -12,7 +12,11 @@ export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterO
 export type { TocHeading, KnowledgeToc } from "./src/markdown";
 export { parseFrontmatter } from "./src/frontmatter";
 export { loadConfig, saveConfig, updateConfig } from "./src/config";
-export type { AgentikitConfig, EmbeddingConnectionConfig, LlmConnectionConfig } 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,9 +1,12 @@
-export { agentikitSearch, agentikitShow } 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/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
-import { agentikitSearch, agentikitShow } from "./stash";
+import { agentikitAdd, agentikitList, agentikitReinstall, agentikitRemove, agentikitSearch, agentikitShow, agentikitUpdate, } from "./stash";
 import { agentikitInit } from "./init";
 import { agentikitIndex } from "./indexer";
 import { loadConfig, updateConfig } from "./config";
@@ -8,8 +8,10 @@ import { resolveStashDir } from "./common";
 const initCommand = defineCommand({
     meta: { name: "init", description: "Initialize agentikit stash directory and set AGENTIKIT_STASH_DIR" },
     run() {
-        const result = agentikitInit();
-        console.log(JSON.stringify(result, null, 2));
+        return runWithJsonErrors(() => {
+            const result = agentikitInit();
+            console.log(JSON.stringify(result, null, 2));
+        });
     },
 });
 const indexCommand = defineCommand({
@@ -18,8 +20,10 @@ const indexCommand = defineCommand({
         full: { type: "boolean", description: "Force full reindex", default: false },
     },
     async run({ args }) {
-        const result = await agentikitIndex({ full: args.full });
-        console.log(JSON.stringify(result, null, 2));
+        await runWithJsonErrors(async () => {
+            const result = await agentikitIndex({ full: args.full });
+            console.log(JSON.stringify(result, null, 2));
+        });
     },
 });
 const searchCommand = defineCommand({
@@ -28,11 +32,71 @@ const searchCommand = defineCommand({
         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 }) {
-        const type = args.type;
-        const limit = args.limit ? parseInt(args.limit, 10) : undefined;
-        console.log(JSON.stringify(await agentikitSearch({ query: args.query, type, limit }), null, 2));
+        await runWithJsonErrors(async () => {
+            const type = args.type;
+            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({
@@ -45,30 +109,31 @@ const showCommand = defineCommand({
         end: { type: "string", description: "End line (for --view lines)" },
     },
     run({ args }) {
-        let view;
-        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:
-                    console.error(`Unknown view mode: ${args.view}`);
-                    process.exit(1);
+        return runWithJsonErrors(() => {
+            let view;
+            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));
+            console.log(JSON.stringify(agentikitShow({ ref: args.ref, view }), null, 2));
+        });
     },
 });
 const configCommand = defineCommand({
@@ -77,23 +142,24 @@ const configCommand = defineCommand({
         set: { type: "string", description: "Update a config key (key=value format)" },
     },
     run({ args }) {
-        const stashDir = resolveStashDir();
-        if (args.set) {
-            const eqIndex = args.set.indexOf("=");
-            if (eqIndex === -1) {
-                console.error("Error: --set expects key=value format");
-                process.exit(1);
+        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 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({
@@ -104,12 +170,29 @@ const main = defineCommand({
     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 = ["none", "both", "item", "guide"];
+const SEARCH_SOURCES = ["local", "registry", "both"];
+function parseSearchUsageMode(value) {
+    if (SEARCH_USAGE_MODES.includes(value))
+        return value;
+    throw new Error(`Invalid value for --usage: ${value}. Expected one of: ${SEARCH_USAGE_MODES.join("|")}`);
+}
+function parseSearchSource(value) {
+    if (SEARCH_SOURCES.includes(value))
+        return value;
+    throw new Error(`Invalid value for --source: ${value}. Expected one of: ${SEARCH_SOURCES.join("|")}`);
+}
 function parseConnectionValue(key, value, exampleEndpoint, exampleModel) {
     if (value === "null" || value === "")
         return undefined;
@@ -162,3 +245,29 @@ function parseConfigValue(key, value) {
             throw new Error(`Unknown config key: ${key}`);
     }
 }
+async function runWithJsonErrors(fn) {
+    try {
+        await fn();
+    }
+    catch (error) {
+        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);
+    }
+}
+function buildHint(message) {
+    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;
+}

package/dist/src/config.d.ts

@@ -1,3 +1,4 @@
+import type { RegistryInstalledEntry } from "./registry-types";
 export interface EmbeddingConnectionConfig {
     /** OpenAI-compatible embeddings endpoint (e.g. "http://localhost:11434/v1/embeddings") */
     endpoint: string;
@@ -23,6 +24,11 @@ export interface AgentikitConfig {
     embedding?: EmbeddingConnectionConfig;
     /** OpenAI-compatible LLM endpoint config for metadata generation. If not set, uses heuristic generation */
     llm?: LlmConnectionConfig;
+    /** Installed registry sources and local cache metadata */
+    registry?: RegistryConfig;
+}
+export interface RegistryConfig {
+    installed: RegistryInstalledEntry[];
 }
 export declare const DEFAULT_CONFIG: AgentikitConfig;
 export declare function getConfigPath(stashDir: string): string;

package/dist/src/config.js

@@ -53,6 +53,9 @@ function pickKnownKeys(raw) {
     const llm = parseConnectionConfig(raw.llm);
     if (llm)
         config.llm = llm;
+    const registry = parseRegistryConfig(raw.registry);
+    if (registry)
+        config.registry = registry;
     return config;
 }
 function parseConnectionConfig(value) {
@@ -72,3 +75,50 @@ function parseConnectionConfig(value) {
     }
     return result;
 }
+function parseRegistryConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    if (!Array.isArray(obj.installed))
+        return undefined;
+    const installed = obj.installed
+        .map((entry) => parseRegistryInstalledEntry(entry))
+        .filter((entry) => entry !== undefined);
+    return { installed };
+}
+function parseRegistryInstalledEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    const id = asNonEmptyString(obj.id);
+    const source = asRegistrySource(obj.source);
+    const ref = asNonEmptyString(obj.ref);
+    const artifactUrl = asNonEmptyString(obj.artifactUrl);
+    const stashRoot = asNonEmptyString(obj.stashRoot);
+    const cacheDir = asNonEmptyString(obj.cacheDir);
+    const installedAt = asNonEmptyString(obj.installedAt);
+    if (!id || !source || !ref || !artifactUrl || !stashRoot || !cacheDir || !installedAt)
+        return undefined;
+    const entry = {
+        id,
+        source,
+        ref,
+        artifactUrl,
+        stashRoot,
+        cacheDir,
+        installedAt,
+    };
+    const resolvedVersion = asNonEmptyString(obj.resolvedVersion);
+    if (resolvedVersion)
+        entry.resolvedVersion = resolvedVersion;
+    const resolvedRevision = asNonEmptyString(obj.resolvedRevision);
+    if (resolvedRevision)
+        entry.resolvedRevision = resolvedRevision;
+    return entry;
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function asRegistrySource(value) {
+    return value === "npm" || value === "github" ? value : undefined;
+}

package/dist/src/metadata.d.ts

@@ -20,6 +20,7 @@ export interface StashEntry {
     source?: "package" | "frontmatter" | "comments" | "filename" | "manual" | "llm";
     aliases?: string[];
     toc?: TocHeading[];
+    usage?: string[];
 }
 export interface StashFile {
     entries: StashEntry[];

package/dist/src/metadata.js

@@ -94,8 +94,24 @@ export function validateStashEntry(entry) {
         if (validated.length > 0)
             result.toc = validated;
     }
+    const usage = normalizeNonEmptyStringList(e.usage);
+    if (usage)
+        result.usage = usage;
     return result;
 }
+function normalizeNonEmptyStringList(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : undefined;
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    const filtered = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    return filtered.length > 0 ? filtered : undefined;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];

package/dist/src/registry-install.d.ts

@@ -0,0 +1,11 @@
+import { type AgentikitConfig } from "./config";
+import type { RegistryInstallResult, RegistryInstalledEntry } from "./registry-types";
+export interface InstallRegistryRefOptions {
+    cacheRootDir?: string;
+    now?: Date;
+}
+export declare function installRegistryRef(ref: string, options?: InstallRegistryRefOptions): Promise<RegistryInstallResult>;
+export declare function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry, stashDir?: string): AgentikitConfig;
+export declare function removeInstalledRegistryEntry(id: string, stashDir?: string): AgentikitConfig;
+export declare function getRegistryCacheRootDir(): string;
+export declare function detectStashRoot(extractedDir: string): string;