agentikit 0.0.8 → 0.0.12

package/dist/src/stash-show.js

@@ -1,27 +1,14 @@
 import fs from "node:fs";
-import path from "node:path";
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { resolveStashDir } from "./common";
-import { parseOpenRef } from "./stash-ref";
+import { parseAssetRef } from "./stash-ref";
+import { resolveSourcesForOrigin } from "./origin-resolve";
 import { resolveAssetPath } from "./stash-resolve";
-import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./markdown";
-import { buildToolInfo } from "./tool-runner";
-import { loadConfig } from "./config";
-export function agentikitShow(input) {
-    const parsed = parseOpenRef(input.ref);
-    const stashDir = resolveStashDir();
-    const config = loadConfig(stashDir);
-    const allStashDirs = [
-        stashDir,
-        ...config.additionalStashDirs.filter((d) => {
-            try {
-                return fs.statSync(d).isDirectory();
-            }
-            catch {
-                return false;
-            }
-        }),
-    ];
+import { getHandler } from "./asset-type-handler";
+import { resolveStashSources, findSourceForPath } from "./stash-source";
+export async function agentikitShow(input) {
+    const parsed = parseAssetRef(input.ref);
+    const allSources = resolveStashSources();
+    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    const allStashDirs = searchSources.map((s) => s.path);
     let assetPath;
     let lastError;
     for (const dir of allStashDirs) {
@@ -33,75 +20,27 @@ export function agentikitShow(input) {
             lastError = err instanceof Error ? err : new Error(String(err));
         }
     }
+    if (!assetPath && parsed.origin && searchSources.length === 0) {
+        const installCmd = `akm add ${parsed.origin}`;
+        throw new Error(`Stash asset not found for ref: ${parsed.type}:${parsed.name}. ` +
+            `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`);
+    }
     if (!assetPath) {
         throw lastError ?? new Error(`Stash asset not found for ref: ${parsed.type}:${parsed.name}`);
     }
     const content = fs.readFileSync(assetPath, "utf8");
-    switch (parsed.type) {
-        case "skill":
-            return {
-                type: "skill",
-                name: parsed.name,
-                path: assetPath,
-                content,
-            };
-        case "command": {
-            const parsedMd = parseFrontmatter(content);
-            return {
-                type: "command",
-                name: parsed.name,
-                path: assetPath,
-                description: toStringOrUndefined(parsedMd.data.description),
-                template: parsedMd.content,
-            };
-        }
-        case "agent": {
-            const parsedMd = parseFrontmatter(content);
-            return {
-                type: "agent",
-                name: parsed.name,
-                path: assetPath,
-                description: toStringOrUndefined(parsedMd.data.description),
-                prompt: parsedMd.content,
-                toolPolicy: parsedMd.data.tools,
-                modelHint: parsedMd.data.model,
-            };
-        }
-        case "tool": {
-            const assetStashDir = allStashDirs.find((d) => path.resolve(assetPath).startsWith(path.resolve(d) + path.sep)) ?? stashDir;
-            const toolInfo = buildToolInfo(assetStashDir, assetPath);
-            return {
-                type: "tool",
-                name: parsed.name,
-                path: assetPath,
-                runCmd: toolInfo.runCmd,
-                kind: toolInfo.kind,
-            };
-        }
-        case "knowledge": {
-            const v = input.view ?? { mode: "full" };
-            switch (v.mode) {
-                case "toc": {
-                    const toc = parseMarkdownToc(content);
-                    return { type: "knowledge", name: parsed.name, path: assetPath, content: formatToc(toc) };
-                }
-                case "frontmatter": {
-                    const fm = extractFrontmatterOnly(content);
-                    return { type: "knowledge", name: parsed.name, path: assetPath, content: fm ?? "(no frontmatter)" };
-                }
-                case "section": {
-                    const section = extractSection(content, v.heading);
-                    if (!section)
-                        throw new Error(`Section "${v.heading}" not found in ${parsed.name}`);
-                    return { type: "knowledge", name: parsed.name, path: assetPath, content: section.content };
-                }
-                case "lines": {
-                    return { type: "knowledge", name: parsed.name, path: assetPath, content: extractLineRange(content, v.start, v.end) };
-                }
-                default: {
-                    return { type: "knowledge", name: parsed.name, path: assetPath, content };
-                }
-            }
-        }
-    }
+    const source = findSourceForPath(assetPath, allSources);
+    const handler = getHandler(parsed.type);
+    const response = handler.buildShowResponse({
+        name: parsed.name,
+        path: assetPath,
+        content,
+        view: input.view,
+        stashDirs: allStashDirs,
+    });
+    return {
+        ...response,
+        registryId: source?.registryId,
+        editable: source?.writable ?? false,
+    };
 }

package/dist/src/stash-source.d.ts

@@ -0,0 +1,24 @@
+export type StashSourceKind = "working" | "mounted" | "installed";
+export interface StashSource {
+    kind: StashSourceKind;
+    path: string;
+    /** For installed sources, the registry entry id */
+    registryId?: string;
+    /** Whether this source is writable (only working stash) */
+    writable: boolean;
+}
+/**
+ * Build the ordered list of stash sources:
+ *   1. Working stash (writable)
+ *   2. Mounted stash dirs (read-only, user-configured)
+ *   3. Installed stash dirs (read-only, derived from registry.installed)
+ */
+export declare function resolveStashSources(overrideStashDir?: string): StashSource[];
+/**
+ * Convenience: returns just the directory paths, preserving priority order.
+ */
+export declare function resolveAllStashDirs(overrideStashDir?: string): string[];
+/**
+ * Find which source a file path belongs to.
+ */
+export declare function findSourceForPath(filePath: string, sources: StashSource[]): StashSource | undefined;

package/dist/src/stash-source.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "./common";
+import { loadConfig } from "./config";
+// ── Resolution ──────────────────────────────────────────────────────────────
+/**
+ * Build the ordered list of stash sources:
+ *   1. Working stash (writable)
+ *   2. Mounted stash dirs (read-only, user-configured)
+ *   3. Installed stash dirs (read-only, derived from registry.installed)
+ */
+export function resolveStashSources(overrideStashDir) {
+    const stashDir = overrideStashDir ?? resolveStashDir();
+    const config = loadConfig();
+    const sources = [
+        { kind: "working", path: stashDir, writable: true },
+    ];
+    for (const dir of config.mountedStashDirs) {
+        if (isSuspiciousStashRoot(dir)) {
+            console.warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
+        }
+        if (isValidDirectory(dir)) {
+            sources.push({ kind: "mounted", path: dir, writable: false });
+        }
+    }
+    for (const entry of config.registry?.installed ?? []) {
+        if (isSuspiciousStashRoot(entry.stashRoot)) {
+            console.warn(`Warning: stash root "${entry.stashRoot}" appears to be a system directory. This may be unintentional.`);
+        }
+        if (isValidDirectory(entry.stashRoot)) {
+            sources.push({
+                kind: "installed",
+                path: entry.stashRoot,
+                registryId: entry.id,
+                writable: false,
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Convenience: returns just the directory paths, preserving priority order.
+ */
+export function resolveAllStashDirs(overrideStashDir) {
+    return resolveStashSources(overrideStashDir).map((s) => s.path);
+}
+/**
+ * Find which source a file path belongs to.
+ */
+export function findSourceForPath(filePath, sources) {
+    const resolved = path.resolve(filePath);
+    for (const source of sources) {
+        if (resolved.startsWith(path.resolve(source.path) + path.sep))
+            return source;
+    }
+    return undefined;
+}
+// ── Validation ──────────────────────────────────────────────────────────────
+const SUSPICIOUS_ROOTS = new Set(['/', '/etc', '/bin', '/sbin', '/usr', '/var', '/tmp', '/dev', '/proc', '/sys']);
+function isSuspiciousStashRoot(dir) {
+    const resolved = path.resolve(dir);
+    const normalized = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    if (SUSPICIOUS_ROOTS.has(normalized))
+        return true;
+    if (process.platform === 'win32') {
+        // Check for Windows system directories
+        const winDir = (process.env.SystemRoot || 'C:\\Windows').toLowerCase();
+        if (normalized === winDir || normalized.startsWith(winDir + path.sep))
+            return true;
+    }
+    return false;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function isValidDirectory(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/stash-types.d.ts

@@ -1,22 +1,58 @@
 import type { AgentikitAssetType } from "./common";
+import type { RegistrySource } from "./registry-types";
 import type { ToolKind } from "./tool-runner";
 export type AgentikitSearchType = AgentikitAssetType | "any";
-export interface SearchHit {
+export type SearchUsageMode = "none" | "both" | "item" | "guide";
+export type SearchSource = "local" | "registry" | "both";
+export interface LocalSearchHit {
+    hitSource: "local";
     type: AgentikitAssetType;
     name: string;
     path: string;
     openRef: string;
+    /** For installed sources, the registry id */
+    registryId?: string;
+    /** Whether this asset is editable (only true for working stash) */
+    editable?: boolean;
     description?: string;
     tags?: string[];
     score?: number;
     whyMatched?: string[];
     runCmd?: string;
     kind?: ToolKind;
+    usage?: string[];
 }
+export interface RegistrySearchResultHit {
+    hitSource: "registry";
+    type: "registry";
+    name: string;
+    path?: string;
+    openRef?: string;
+    id: string;
+    registrySource: RegistrySource;
+    ref: string;
+    description?: string;
+    tags?: string[];
+    homepage?: string;
+    score?: number;
+    whyMatched?: string[];
+    runCmd?: string;
+    kind?: ToolKind;
+    usage?: string[];
+    metadata?: Record<string, string>;
+    installRef: string;
+    installCmd: string;
+    /** Whether this entry was manually reviewed and approved */
+    curated?: boolean;
+}
+export type SearchHit = LocalSearchHit | RegistrySearchResultHit;
 export interface SearchResponse {
     stashDir: string;
+    source: SearchSource;
     hits: SearchHit[];
+    usageGuide?: Partial<Record<AgentikitAssetType, string[]>>;
     tip?: string;
+    warnings?: string[];
     /** Timing counters in milliseconds */
     timing?: {
         totalMs: number;
@@ -24,6 +60,140 @@ export interface SearchResponse {
         embedMs?: number;
     };
 }
+export interface AddResponse {
+    stashDir: string;
+    ref: string;
+    installed: {
+        id: string;
+        source: RegistrySource;
+        ref: string;
+        artifactUrl: string;
+        resolvedVersion?: string;
+        resolvedRevision?: string;
+        stashRoot: string;
+        cacheDir: string;
+        extractedDir: string;
+        installedAt: string;
+    };
+    config: {
+        mountedStashDirs: string[];
+        installedRegistryCount: number;
+    };
+    index: {
+        mode: "full" | "incremental";
+        totalEntries: number;
+        directoriesScanned: number;
+        directoriesSkipped: number;
+    };
+}
+export interface RegistryInstallStatus {
+    id: string;
+    source: RegistrySource;
+    ref: string;
+    artifactUrl: string;
+    resolvedVersion?: string;
+    resolvedRevision?: string;
+    stashRoot: string;
+    cacheDir: string;
+    extractedDir: string;
+    installedAt: string;
+}
+export interface RegistryListEntry {
+    id: string;
+    source: RegistrySource;
+    ref: string;
+    artifactUrl: string;
+    resolvedVersion?: string;
+    resolvedRevision?: string;
+    stashRoot: string;
+    cacheDir: string;
+    installedAt: string;
+    status: {
+        cacheDirExists: boolean;
+        stashRootExists: boolean;
+    };
+}
+export interface ListResponse {
+    stashDir: string;
+    installed: RegistryListEntry[];
+    totalInstalled: number;
+}
+export interface RemoveResponse {
+    stashDir: string;
+    target: string;
+    removed: {
+        id: string;
+        source: RegistrySource;
+        ref: string;
+        cacheDir: string;
+        stashRoot: string;
+    };
+    config: {
+        mountedStashDirs: string[];
+        installedRegistryCount: number;
+    };
+    index: {
+        mode: "full" | "incremental";
+        totalEntries: number;
+        directoriesScanned: number;
+        directoriesSkipped: number;
+    };
+}
+export interface ReinstallResultItem {
+    id: string;
+    source: RegistrySource;
+    ref: string;
+    previousCacheDir: string;
+    installed: RegistryInstallStatus;
+}
+export interface ReinstallResponse {
+    stashDir: string;
+    target?: string;
+    all: boolean;
+    processed: ReinstallResultItem[];
+    config: {
+        mountedStashDirs: string[];
+        installedRegistryCount: number;
+    };
+    index: {
+        mode: "full" | "incremental";
+        totalEntries: number;
+        directoriesScanned: number;
+        directoriesSkipped: number;
+    };
+}
+export interface UpdateResultItem {
+    id: string;
+    source: RegistrySource;
+    ref: string;
+    previous: {
+        resolvedVersion?: string;
+        resolvedRevision?: string;
+        cacheDir: string;
+    };
+    installed: RegistryInstallStatus;
+    changed: {
+        version: boolean;
+        revision: boolean;
+        any: boolean;
+    };
+}
+export interface UpdateResponse {
+    stashDir: string;
+    target?: string;
+    all: boolean;
+    processed: UpdateResultItem[];
+    config: {
+        mountedStashDirs: string[];
+        installedRegistryCount: number;
+    };
+    index: {
+        mode: "full" | "incremental";
+        totalEntries: number;
+        directoriesScanned: number;
+        directoriesSkipped: number;
+    };
+}
 export interface ShowResponse {
     type: AgentikitAssetType;
     name: string;
@@ -36,6 +206,10 @@ export interface ShowResponse {
     modelHint?: unknown;
     runCmd?: string;
     kind?: ToolKind;
+    /** For installed sources, the registry id */
+    registryId?: string;
+    /** Whether this asset is editable (only true for working stash) */
+    editable?: boolean;
 }
 export type KnowledgeView = {
     mode: "full";

package/dist/src/stash.d.ts

@@ -3,6 +3,14 @@ export { resolveStashDir } from "./common";
 export { agentikitInit } from "./init";
 export type { InitResponse } from "./init";
 export type { ToolKind } from "./tool-runner";
+export type { AssetTypeHandler, ShowInput } from "./asset-type-handler";
+export { registerAssetType, getHandler, getAllHandlers, getRegisteredTypeNames } from "./asset-type-handler";
 export { agentikitSearch } from "./stash-search";
 export { agentikitShow } from "./stash-show";
-export type { AgentikitSearchType, SearchHit, SearchResponse, ShowResponse, KnowledgeView, } from "./stash-types";
+export { agentikitAdd } from "./stash-add";
+export { agentikitClone } from "./stash-clone";
+export { agentikitList, agentikitRemove, agentikitReinstall, agentikitUpdate } from "./stash-registry";
+export { resolveStashSources, resolveAllStashDirs, findSourceForPath } from "./stash-source";
+export type { StashSource, StashSourceKind } from "./stash-source";
+export type { AddResponse, AgentikitSearchType, LocalSearchHit, RegistrySearchResultHit, SearchSource, SearchUsageMode, SearchHit, SearchResponse, ShowResponse, KnowledgeView, ListResponse, RemoveResponse, ReinstallResponse, UpdateResponse, RegistryListEntry, RegistryInstallStatus, ReinstallResultItem, UpdateResultItem, } from "./stash-types";
+export type { CloneOptions, CloneResponse } from "./stash-clone";

package/dist/src/stash.js

@@ -1,4 +1,9 @@
 export { resolveStashDir } from "./common";
 export { agentikitInit } from "./init";
+export { registerAssetType, getHandler, getAllHandlers, getRegisteredTypeNames } from "./asset-type-handler";
 export { agentikitSearch } from "./stash-search";
 export { agentikitShow } from "./stash-show";
+export { agentikitAdd } from "./stash-add";
+export { agentikitClone } from "./stash-clone";
+export { agentikitList, agentikitRemove, agentikitReinstall, agentikitUpdate } from "./stash-registry";
+export { resolveStashSources, resolveAllStashDirs, findSourceForPath } from "./stash-source";

package/dist/src/tool-runner.d.ts

@@ -22,7 +22,7 @@ export interface ToolInfo {
  *
  * 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.
+ * `AKM_BUN_INSTALL` env flag is set.
  */
 export declare function buildToolInfo(stashDir: string, filePath: string): ToolInfo;
 /**

package/dist/src/tool-runner.js

@@ -13,7 +13,7 @@ import { IS_WINDOWS, isWithin } from "./common";
  *
  * 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.
+ * `AKM_BUN_INSTALL` env flag is set.
  */
 export function buildToolInfo(stashDir, filePath) {
     const ext = path.extname(filePath).toLowerCase();
@@ -41,8 +41,17 @@ export function buildToolInfo(stashDir, 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);
+    // Determine the type root by checking which subdirectory contains the file
+    const resolvedFile = path.resolve(filePath);
+    let typeRoot = path.resolve(path.join(stashDir, "tools"));
+    for (const subdir of ["tools", "scripts"]) {
+        const candidate = path.resolve(path.join(stashDir, subdir));
+        if (resolvedFile.startsWith(candidate + path.sep)) {
+            typeRoot = candidate;
+            break;
+        }
+    }
+    const pkgDir = findNearestPackageDir(path.dirname(filePath), typeRoot);
     if (!pkgDir) {
         return {
             runCmd: `bun ${shellQuote(filePath)}`,
@@ -50,7 +59,7 @@ export function buildToolInfo(stashDir, filePath) {
             execute: { command: "bun", args: [filePath] },
         };
     }
-    const installFlag = process.env.AGENTIKIT_BUN_INSTALL;
+    const installFlag = process.env.AKM_BUN_INSTALL;
     const shouldInstall = installFlag === "1" || installFlag === "true" || installFlag === "yes";
     const quotedPkgDir = shellQuote(pkgDir);
     const quotedFilePath = shellQuote(filePath);
@@ -73,7 +82,11 @@ export function shellQuote(input) {
         throw new Error("Unsupported control characters in stash path.");
     }
     if (IS_WINDOWS) {
-        return `"${input.replace(/"/g, '""')}"`;
+        const escaped = input
+            .replace(/%/g, "%%")
+            .replace(/([\\^|&<>])/g, "^$1")
+            .replace(/"/g, '""');
+        return `"${escaped}"`;
     }
     const escaped = input
         .replace(/\\/g, "\\\\")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentikit",
-  "version": "0.0.8",
+  "version": "0.0.12",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an agentikit stash directory.",
   "keywords": [
@@ -49,10 +49,15 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "bun-types": "^1.3.10",
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@xenova/transformers": "^2.17.0"
+    "@xenova/transformers": "^2.17.0",
+    "sqlite-vec": "^0.1.7-alpha.2"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
   },
   "dependencies": {
     "citty": "^0.2.1"

package/src/asset-spec.ts

@@ -1,5 +1,7 @@
 import path from "node:path"
 import type { AgentikitAssetType } from "./common"
+import { toPosix } from "./common"
+import { tryGetHandler } from "./asset-type-handler"
 
 export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"])
 
@@ -16,6 +18,12 @@ const markdownSpec: Omit<AssetSpec, "stashDir"> = {
   toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
 }
 
+/** Extended set of script extensions for the script asset type */
+export const SCRIPT_EXTENSIONS_BROAD = new Set([
+  ...SCRIPT_EXTENSIONS,
+  ".py", ".rb", ".go", ".pl", ".php", ".lua", ".r", ".swift", ".kt", ".kts",
+])
+
 export const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec> = {
   tool: {
     stashDir: "tools",
@@ -36,6 +44,12 @@ export const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec> = {
   command: { stashDir: "commands", ...markdownSpec },
   agent: { stashDir: "agents", ...markdownSpec },
   knowledge: { stashDir: "knowledge", ...markdownSpec },
+  script: {
+    stashDir: "scripts",
+    isRelevantFile: (fileName) => SCRIPT_EXTENSIONS_BROAD.has(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+    toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+  },
 }
 
 export const ASSET_TYPES = Object.keys(ASSET_SPECS) as AgentikitAssetType[]
@@ -49,6 +63,8 @@ export const TYPE_DIRS: Record<AgentikitAssetType, string> = ASSET_TYPES.reduce(
 )
 
 export function isRelevantAssetFile(assetType: AgentikitAssetType, fileName: string): boolean {
+  const handler = tryGetHandler(assetType)
+  if (handler) return handler.isRelevantFile(fileName)
   return ASSET_SPECS[assetType].isRelevantFile(fileName)
 }
 
@@ -57,13 +73,13 @@ export function deriveCanonicalAssetName(
   typeRoot: string,
   filePath: string,
 ): string | undefined {
+  const handler = tryGetHandler(assetType)
+  if (handler) return handler.toCanonicalName(typeRoot, filePath)
   return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath)
 }
 
 export function resolveAssetPathFromName(assetType: AgentikitAssetType, typeRoot: string, name: string): string {
+  const handler = tryGetHandler(assetType)
+  if (handler) return handler.toAssetPath(typeRoot, name)
   return ASSET_SPECS[assetType].toAssetPath(typeRoot, name)
 }
-
-function toPosix(input: string): string {
-  return input.replace(/\\/g, "/")
-}