agentikit 0.0.13 → 0.0.14

package/dist/renderers.js

@@ -0,0 +1,276 @@
+/**
+ * Built-in asset renderers.
+ *
+ * Each renderer mirrors the show/search/metadata behavior of its corresponding
+ * legacy AssetTypeHandler, re-expressed against the AssetRenderer interface
+ * from ./file-context. Renderers are registered at module-load time so that
+ * importing this module is sufficient to make them available.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { registerRenderer } from "./file-context";
+import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
+import { SCRIPT_EXTENSIONS } from "./asset-spec";
+import { buildToolInfo } from "./tool-runner";
+import { hasErrnoCode } from "./common";
+import { extractDescriptionFromComments } from "./metadata";
+import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc, } from "./markdown";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Derive a display name from the RenderContext.
+ *
+ * Prefers `matchResult.meta.name` when present; otherwise falls back to the
+ * POSIX-style relative path stripped of its extension.
+ */
+function deriveName(ctx) {
+    const metaName = ctx.matchResult.meta?.name;
+    if (typeof metaName === "string" && metaName)
+        return metaName;
+    // Strip the extension from the relPath for a reasonable fallback.
+    const ext = path.extname(ctx.relPath);
+    return ext ? ctx.relPath.slice(0, -ext.length) : ctx.relPath;
+}
+/**
+ * Find the stashDir that contains `filePath`, falling back to the first
+ * entry in the array when no prefix match is found.
+ */
+function findContainingStashDir(stashDirs, filePath) {
+    return (stashDirs.find((d) => path.resolve(filePath).startsWith(path.resolve(d) + path.sep)) ?? stashDirs[0]);
+}
+// ── 1. tool-script ───────────────────────────────────────────────────────────
+const toolScriptRenderer = {
+    name: "tool-script",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const stashDirs = ctx.stashDirs;
+        const assetStashDir = findContainingStashDir(stashDirs, ctx.absPath);
+        if (!assetStashDir) {
+            return { type: "tool", name, path: ctx.absPath, content: ctx.content() };
+        }
+        const toolInfo = buildToolInfo(assetStashDir, ctx.absPath);
+        return {
+            type: "tool",
+            name,
+            path: ctx.absPath,
+            runCmd: toolInfo.runCmd,
+            kind: toolInfo.kind,
+        };
+    },
+    enrichSearchHit(hit, stashDir) {
+        try {
+            const toolInfo = buildToolInfo(stashDir, hit.path);
+            hit.runCmd = toolInfo.runCmd;
+            hit.kind = toolInfo.kind;
+        }
+        catch (error) {
+            if (!hasErrnoCode(error, "ENOENT"))
+                throw error;
+        }
+    },
+    extractMetadata(entry, ctx) {
+        if (SCRIPT_EXTENSIONS.has(ctx.ext) && ctx.ext !== ".md") {
+            const commentDesc = extractDescriptionFromComments(ctx.absPath);
+            if (commentDesc && !entry.description) {
+                entry.description = commentDesc;
+                entry.source = "comments";
+                entry.confidence = 0.7;
+            }
+        }
+    },
+    usageGuide: [
+        "Use the hit's runCmd for execution so runtime and working directory stay correct.",
+        "Use `akm show <openRef>` to inspect the tool before running it.",
+    ],
+};
+// ── 2. skill-md ──────────────────────────────────────────────────────────────
+const skillMdRenderer = {
+    name: "skill-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        return {
+            type: "skill",
+            name,
+            path: ctx.absPath,
+            content: ctx.content(),
+        };
+    },
+    usageGuide: [
+        "Read and apply the skill instructions as written, then adapt examples to your current repo state and task.",
+        "Use `akm show <openRef>` to read the full SKILL.md for required steps and constraints.",
+    ],
+};
+// ── 3. command-md ────────────────────────────────────────────────────────────
+const commandMdRenderer = {
+    name: "command-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsedMd = parseFrontmatter(ctx.content());
+        return {
+            type: "command",
+            name,
+            path: ctx.absPath,
+            description: toStringOrUndefined(parsedMd.data.description),
+            template: parsedMd.content,
+            modelHint: parsedMd.data.model,
+            agent: toStringOrUndefined(parsedMd.data.agent),
+        };
+    },
+    usageGuide: [
+        "Read the .md file, fill $ARGUMENTS placeholders, and run it in the current repo context.",
+        "Use `akm show <openRef>` to retrieve the command template body.",
+        "When `agent` is specified, dispatch the command to that agent.",
+    ],
+};
+// ── 4. agent-md ──────────────────────────────────────────────────────────────
+const agentMdRenderer = {
+    name: "agent-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsedMd = parseFrontmatter(ctx.content());
+        return {
+            type: "agent",
+            name,
+            path: ctx.absPath,
+            description: toStringOrUndefined(parsedMd.data.description),
+            prompt: "Dispatching prompt must include the agent's full prompt content verbatim; summaries are non-compliant. \n\n" +
+                parsedMd.content,
+            toolPolicy: parsedMd.data.tools,
+            modelHint: parsedMd.data.model,
+        };
+    },
+    usageGuide: [
+        "Read the .md file and dispatch an agent using the content of the file. Use modelHint/toolPolicy when present to run the agent with compatible settings.",
+        "Use with `akm show <openRef>` to get the full prompt payload.",
+    ],
+};
+// ── 5. knowledge-md ──────────────────────────────────────────────────────────
+const knowledgeMdRenderer = {
+    name: "knowledge-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const v = ctx.matchResult.meta?.view ?? { mode: "full" };
+        const content = ctx.content();
+        switch (v.mode) {
+            case "toc": {
+                const toc = parseMarkdownToc(content);
+                return { type: "knowledge", name, path: ctx.absPath, content: formatToc(toc) };
+            }
+            case "frontmatter": {
+                const fm = extractFrontmatterOnly(content);
+                return { type: "knowledge", name, path: ctx.absPath, content: fm ?? "(no frontmatter)" };
+            }
+            case "section": {
+                const section = extractSection(content, v.heading);
+                if (!section) {
+                    return {
+                        type: "knowledge",
+                        name,
+                        path: ctx.absPath,
+                        content: `Section "${v.heading}" not found in ${name}. Try --view toc to discover available headings.`,
+                    };
+                }
+                return { type: "knowledge", name, path: ctx.absPath, content: section.content };
+            }
+            case "lines": {
+                return {
+                    type: "knowledge",
+                    name,
+                    path: ctx.absPath,
+                    content: extractLineRange(content, v.start, v.end),
+                };
+            }
+            default: {
+                return { type: "knowledge", name, path: ctx.absPath, content };
+            }
+        }
+    },
+    extractMetadata(entry, ctx) {
+        try {
+            const mdContent = fs.readFileSync(ctx.absPath, "utf8");
+            const toc = parseMarkdownToc(mdContent);
+            if (toc.headings.length > 0)
+                entry.toc = toc.headings;
+        }
+        catch {
+            // Non-fatal: skip TOC if file can't be read
+        }
+    },
+    usageGuide: [
+        "Use `akm show <openRef>` to read the document; start with `--view toc` for large files.",
+        "Use `--view section` or `--view lines` to load only the part you need.",
+    ],
+};
+// ── 6. script-source ─────────────────────────────────────────────────────────
+/** Extensions that buildToolInfo can handle (tool-runner supported) */
+const RUNNABLE_EXTENSIONS = SCRIPT_EXTENSIONS;
+const scriptSourceRenderer = {
+    name: "script-source",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const ext = path.extname(ctx.absPath).toLowerCase();
+        // For extensions supported by tool-runner, show runCmd
+        if (RUNNABLE_EXTENSIONS.has(ext)) {
+            const stashDirs = ctx.stashDirs;
+            const assetStashDir = findContainingStashDir(stashDirs, ctx.absPath);
+            if (assetStashDir) {
+                try {
+                    const toolInfo = buildToolInfo(assetStashDir, ctx.absPath);
+                    return {
+                        type: "script",
+                        name,
+                        path: ctx.absPath,
+                        runCmd: toolInfo.runCmd,
+                        kind: toolInfo.kind,
+                    };
+                }
+                catch {
+                    // Fall through to content display
+                }
+            }
+        }
+        // For other extensions or when buildToolInfo fails, show file content
+        return {
+            type: "script",
+            name,
+            path: ctx.absPath,
+            content: ctx.content(),
+        };
+    },
+    enrichSearchHit(hit, stashDir) {
+        const ext = path.extname(hit.path).toLowerCase();
+        if (!RUNNABLE_EXTENSIONS.has(ext))
+            return;
+        try {
+            const toolInfo = buildToolInfo(stashDir, hit.path);
+            hit.runCmd = toolInfo.runCmd;
+            hit.kind = toolInfo.kind;
+        }
+        catch (error) {
+            if (!hasErrnoCode(error, "ENOENT"))
+                throw error;
+        }
+    },
+    extractMetadata(entry, ctx) {
+        if (ctx.ext !== ".md") {
+            const commentDesc = extractDescriptionFromComments(ctx.absPath);
+            if (commentDesc && !entry.description) {
+                entry.description = commentDesc;
+                entry.source = "comments";
+                entry.confidence = 0.7;
+            }
+        }
+    },
+    usageGuide: [
+        "Use the hit's runCmd for execution when available, or run the script directly with the appropriate interpreter.",
+        "Use `akm show <openRef>` to inspect the script before running it.",
+    ],
+};
+// ── Registration ─────────────────────────────────────────────────────────────
+registerRenderer(toolScriptRenderer);
+registerRenderer(skillMdRenderer);
+registerRenderer(commandMdRenderer);
+registerRenderer(agentMdRenderer);
+registerRenderer(knowledgeMdRenderer);
+registerRenderer(scriptSourceRenderer);
+// ── Named exports for testing ────────────────────────────────────────────────
+export { toolScriptRenderer, skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, scriptSourceRenderer, };

package/dist/{src/ripgrep-install.js → ripgrep-install.js}

@@ -28,14 +28,15 @@ function getRgPlatformTarget() {
 }
 const RG_VERSION = "14.1.1";
 /**
- * Ensure ripgrep is available. If not found on PATH or in stash/bin,
- * download and install it to stash/bin.
+ * Ensure ripgrep is available. If not found on PATH or in the given binDir,
+ * download and install it to binDir.
  *
+ * @param binDir - Directory to install ripgrep into (e.g. cache/bin from paths.ts)
  * Returns the path to the ripgrep binary and whether it was newly installed.
  */
-export function ensureRg(stashDir) {
+export function ensureRg(binDir) {
     // Already available?
-    const existing = resolveRg(stashDir);
+    const existing = resolveRg(binDir);
     if (existing) {
         return { rgPath: existing, installed: false, version: getRgVersion(existing) };
     }
@@ -45,7 +46,6 @@ export function ensureRg(stashDir) {
         throw new Error(`Unsupported platform for ripgrep auto-install: ${process.platform}/${process.arch}. ` +
             `Install ripgrep manually: https://github.com/BurntSushi/ripgrep#installation`);
     }
-    const binDir = path.join(stashDir, "bin");
     if (!fs.existsSync(binDir)) {
         fs.mkdirSync(binDir, { recursive: true });
     }

package/dist/{src/ripgrep-resolve.js → ripgrep-resolve.js}

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { IS_WINDOWS } from "./common";
+import { getBinDir } from "./paths";
 export const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
 function canExecute(filePath) {
     if (!fs.existsSync(filePath))
@@ -47,22 +48,31 @@ function resolveFromPath() {
 /**
  * Resolve the path to a usable ripgrep binary.
  * Checks in order:
- *   1. stashDir/bin/rg
- *   2. system PATH (rg)
+ *   1. Provided binDir (or default cache bin dir) for rg
+ *   2. System PATH (rg)
  * Returns null if ripgrep is not available.
  */
-export function resolveRg(stashDir) {
-    // Check stash bin directory first
-    if (stashDir) {
-        const stashRg = path.join(stashDir, "bin", RG_BINARY);
-        if (canExecute(stashRg))
-            return stashRg;
+export function resolveRg(binDir) {
+    if (binDir) {
+        const directRg = path.join(binDir, RG_BINARY);
+        if (canExecute(directRg))
+            return directRg;
+    }
+    // Check default cache bin dir
+    try {
+        const defaultBinDir = getBinDir();
+        const cachedRg = path.join(defaultBinDir, RG_BINARY);
+        if (canExecute(cachedRg))
+            return cachedRg;
+    }
+    catch {
+        // getBinDir may fail if HOME is not set — fall through
     }
     return resolveFromPath();
 }
 /**
- * Check if ripgrep is available (either in stash/bin or system PATH).
+ * Check if ripgrep is available (in cache/bin or system PATH).
  */
-export function isRgAvailable(stashDir) {
-    return resolveRg(stashDir) !== null;
+export function isRgAvailable(binDir) {
+    return resolveRg(binDir) !== null;
 }

package/dist/self-update.js

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { IS_WINDOWS, fetchWithRetry } from "./common";
+import { githubHeaders } from "./github";
+const REPO = "itlackey/agentikit";
+export function detectInstallMethod() {
+    // Bun-compiled binaries: Bun.main equals process.execPath
+    if (typeof Bun !== "undefined" && Bun.main === process.execPath) {
+        return "binary";
+    }
+    // npm/bun global install: import.meta.dir contains node_modules
+    if (import.meta.dir?.includes("node_modules")) {
+        return "npm";
+    }
+    return "unknown";
+}
+export function getAkmBinaryName() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "linux" && arch === "x64")
+        return "akm-linux-x64";
+    if (platform === "linux" && arch === "arm64")
+        return "akm-linux-arm64";
+    if (platform === "darwin" && arch === "x64")
+        return "akm-darwin-x64";
+    if (platform === "darwin" && arch === "arm64")
+        return "akm-darwin-arm64";
+    if (platform === "win32" && arch === "x64")
+        return "akm-windows-x64.exe";
+    throw new Error(`Unsupported platform for binary upgrade: ${platform}/${arch}`);
+}
+export async function checkForUpdate(currentVersion) {
+    const installMethod = detectInstallMethod();
+    const url = `https://api.github.com/repos/${REPO}/releases/latest`;
+    const response = await fetchWithRetry(url, { headers: githubHeaders() });
+    if (!response.ok) {
+        throw new Error(`Failed to check for updates: ${response.status} ${response.statusText}`);
+    }
+    const release = (await response.json());
+    const latestTag = release.tag_name ?? "";
+    const latestVersion = latestTag.replace(/^v/, "");
+    return {
+        currentVersion,
+        latestVersion,
+        updateAvailable: latestVersion !== "" && latestVersion !== currentVersion,
+        installMethod,
+    };
+}
+export async function performUpgrade(check, opts) {
+    const { currentVersion, latestVersion, installMethod } = check;
+    const force = opts?.force === true;
+    if (installMethod === "npm") {
+        return {
+            currentVersion,
+            newVersion: latestVersion,
+            upgraded: false,
+            installMethod,
+            message: `akm installed via npm. Run: bun install -g agentikit@latest`,
+        };
+    }
+    if (installMethod === "unknown") {
+        return {
+            currentVersion,
+            newVersion: latestVersion,
+            upgraded: false,
+            installMethod,
+            message: `Unable to detect install method. Upgrade manually from https://github.com/${REPO}/releases`,
+        };
+    }
+    // Binary install
+    if (!check.updateAvailable && !force) {
+        return {
+            currentVersion,
+            newVersion: latestVersion,
+            upgraded: false,
+            installMethod,
+            message: `akm v${currentVersion} is already the latest version`,
+        };
+    }
+    if (!latestVersion) {
+        throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/agentikit/releases");
+    }
+    const tag = `v${latestVersion}`;
+    const binaryName = getAkmBinaryName();
+    const binaryUrl = `https://github.com/${REPO}/releases/download/${tag}/${binaryName}`;
+    const checksumsUrl = `https://github.com/${REPO}/releases/download/${tag}/checksums.txt`;
+    // Download binary
+    const binaryResponse = await fetchWithRetry(binaryUrl);
+    if (!binaryResponse.ok) {
+        throw new Error(`Failed to download binary: ${binaryResponse.status} ${binaryResponse.statusText}`);
+    }
+    const binaryData = new Uint8Array(await binaryResponse.arrayBuffer());
+    // Download and verify checksum
+    let checksumVerified = false;
+    try {
+        const checksumsResponse = await fetchWithRetry(checksumsUrl);
+        if (checksumsResponse.ok) {
+            const checksumsText = await checksumsResponse.text();
+            const expectedHash = parseChecksumForFile(checksumsText, binaryName);
+            if (expectedHash) {
+                const actualHash = createHash("sha256").update(binaryData).digest("hex");
+                if (actualHash !== expectedHash) {
+                    throw new Error(`Checksum mismatch for ${binaryName}.\n` +
+                        `Expected: ${expectedHash}\n` +
+                        `Got:      ${actualHash}`);
+                }
+                checksumVerified = true;
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes("Checksum mismatch")) {
+            throw err;
+        }
+        // Non-fatal: checksum file missing or unparseable
+    }
+    const execPath = process.execPath;
+    const execDir = path.dirname(execPath);
+    const execName = path.basename(execPath);
+    if (IS_WINDOWS) {
+        // Windows: rename running exe, write new one, clean up old on success
+        const oldPath = execPath + ".old";
+        try {
+            fs.renameSync(execPath, oldPath);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "EPERM" || code === "EACCES") {
+                throw new Error(`Permission denied. Cannot rename ${execPath}.\n` +
+                    `Try running as Administrator, or re-download from https://github.com/${REPO}/releases`);
+            }
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to rename ${execPath}: ${detail}`);
+        }
+        try {
+            fs.writeFileSync(execPath, binaryData);
+        }
+        catch (err) {
+            // Restore from old
+            fs.renameSync(oldPath, execPath);
+            throw err;
+        }
+        // Best-effort cleanup of .old
+        try {
+            fs.unlinkSync(oldPath);
+        }
+        catch {
+            // Windows may lock the old exe — it will be cleaned up on next startup or manually
+        }
+    }
+    else {
+        // Unix: write to temp file, chmod +x, atomic rename
+        const tmpPath = path.join(execDir, `.${execName}.tmp.${process.pid}`);
+        const bakPath = execPath + ".bak";
+        try {
+            fs.writeFileSync(tmpPath, binaryData);
+            fs.chmodSync(tmpPath, 0o755);
+        }
+        catch (err) {
+            // Clean up temp file on failure
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            const code = err.code;
+            if (code === "EACCES" || code === "EPERM") {
+                throw new Error(`Permission denied writing to ${execDir}.\n` +
+                    `Run: sudo akm upgrade\n` +
+                    `Or re-run the install script: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash`);
+            }
+            throw err;
+        }
+        // Backup current, then atomic rename
+        try {
+            fs.copyFileSync(execPath, bakPath);
+            fs.renameSync(tmpPath, execPath);
+        }
+        catch (err) {
+            // Restore from backup if rename failed
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            try {
+                if (fs.existsSync(bakPath) && !fs.existsSync(execPath)) {
+                    fs.renameSync(bakPath, execPath);
+                }
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+        // Cleanup backup
+        try {
+            fs.unlinkSync(bakPath);
+        }
+        catch { /* ignore */ }
+    }
+    return {
+        currentVersion,
+        newVersion: latestVersion,
+        upgraded: true,
+        installMethod,
+        binaryPath: execPath,
+        checksumVerified,
+    };
+}
+function parseChecksumForFile(checksumsText, filename) {
+    for (const line of checksumsText.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Format: <hash>  <filename>
+        const match = trimmed.match(/^([0-9a-f]{64})\s+(.+)$/);
+        if (match && match[2] === filename) {
+            return match[1];
+        }
+    }
+    return undefined;
+}

package/dist/{src/stash-add.js → stash-add.js}

@@ -2,11 +2,12 @@ import { agentikitIndex } from "./indexer";
 import fs from "node:fs";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
+import { upsertLockEntry } from "./lockfile";
 import { upsertInstalledRegistryEntry, installRegistryRef } from "./registry-install";
 export async function agentikitAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
-        throw new Error("Install ref or local git directory is required.");
+        throw new Error("Install ref or local directory is required.");
     const stashDir = resolveStashDir();
     const installed = await installRegistryRef(ref);
     const replaced = loadConfig().registry?.installed.find((entry) => entry.id === installed.id);
@@ -21,6 +22,14 @@ export async function agentikitAdd(input) {
         cacheDir: installed.cacheDir,
         installedAt: installed.installedAt,
     });
+    upsertLockEntry({
+        id: installed.id,
+        source: installed.source,
+        ref: installed.ref,
+        resolvedVersion: installed.resolvedVersion,
+        resolvedRevision: installed.resolvedRevision,
+        integrity: installed.integrity ?? (installed.source === "local" ? "local" : undefined),
+    });
     if (replaced && replaced.cacheDir !== installed.cacheDir) {
         try {
             fs.rmSync(replaced.cacheDir, { recursive: true, force: true });
@@ -46,7 +55,7 @@ export async function agentikitAdd(input) {
             installedAt: installed.installedAt,
         },
         config: {
-            mountedStashDirs: config.mountedStashDirs,
+            searchPaths: config.searchPaths,
             installedRegistryCount: config.registry?.installed.length ?? 0,
         },
         index: {