akm-cli 0.0.21 → 0.0.23

package/dist/registry-resolve.js

@@ -2,9 +2,37 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { fetchWithRetry } from "./common";
+import { UsageError } from "./errors";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
+/**
+ * Validate that a URL is safe to pass to git.
+ * Allowlists https:, http:, ssh:, git: schemes and git@ SSH shorthand.
+ * Rejects git protocol helpers (ext::, fd::) that can execute arbitrary commands.
+ */
+export function validateGitUrl(url) {
+    // git@ SSH shorthand: git@host:path
+    if (/^git@[^:]+:.+$/.test(url))
+        return;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new UsageError(`Invalid git URL: ${url}`);
+    }
+    const allowed = ["https:", "http:", "ssh:", "git:"];
+    if (!allowed.includes(parsed.protocol)) {
+        throw new UsageError(`Unsafe git URL scheme "${parsed.protocol}" in "${url}". Allowed: https, http, ssh, git, git@host:path`);
+    }
+}
+/** Validate that a git ref (branch/tag/commit) contains only safe characters. */
+export function validateGitRef(ref) {
+    if (!/^[a-zA-Z0-9._\-/]+$/.test(ref)) {
+        throw new UsageError(`Unsafe git ref "${ref}": only alphanumerics, '.', '_', '-', '/' are allowed`);
+    }
+}
 export function parseRegistryRef(rawRef) {
     const ref = rawRef.trim();
     if (!ref)
@@ -285,7 +313,10 @@ async function resolveGithubArtifact(parsed) {
     };
 }
 async function resolveGitArtifact(parsed) {
+    validateGitUrl(parsed.url);
     const ref = parsed.requestedRef ?? "HEAD";
+    if (parsed.requestedRef)
+        validateGitRef(parsed.requestedRef);
     const result = spawnSync("git", ["ls-remote", parsed.url, ref], { encoding: "utf8", timeout: 30_000 });
     let resolvedRevision;
     if (result.status === 0) {
@@ -370,19 +401,23 @@ function stripGitTransport(ref) {
 }
 /**
  * Convert a `file:` URI to a local filesystem path.
- * Supports `file:./relative`, `file:../relative`, and `file:///absolute`.
+ *
+ * Standard `file:///absolute` forms are handled by Node's `fileURLToPath`.
+ * Non-standard `file:./relative` and `file:../relative` shorthand forms
+ * (not a valid RFC 8089 URL) are handled with a custom fallback.
  */
 function fileUriToPath(ref) {
     const after = ref.slice(5); // strip "file:"
-    // file:///absolute/path or file:///C:/path
-    if (after.startsWith("///")) {
-        return after.slice(2); // keep one leading /
-    }
-    // file://hostname/path (rare, treat hostname/path as absolute)
+    // Standard file:///absolute/path — delegate to Node's implementation
     if (after.startsWith("//")) {
-        return after.slice(1);
+        try {
+            return fileURLToPath(ref);
+        }
+        catch {
+            // Fall through to custom handling
+        }
     }
-    // file:./relative or file:../relative or file:/absolute
+    // Non-standard file:./relative or file:../relative or file:/absolute
     return after;
 }
 /**

package/dist/registry-search.js

@@ -1,5 +1,6 @@
+import { toErrorMessage } from "./common";
 import { DEFAULT_CONFIG, loadConfig } from "./config";
-import { resolveProviderFactory } from "./provider-registry";
+import { resolveProviderFactory } from "./registry-factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
 import "./providers/static-index";
 import "./providers/skills-sh";
@@ -63,11 +64,18 @@ export function resolveRegistries(configRegistries) {
     // Allow env var override (comma-separated URLs) — CI escape hatch
     const envUrls = process.env.AKM_REGISTRY_URL?.trim();
     if (envUrls) {
-        return envUrls
-            .split(",")
-            .map((u) => u.trim())
-            .filter(Boolean)
-            .map((url) => ({ url }));
+        const entries = [];
+        for (const raw of envUrls.split(",")) {
+            const url = raw.trim();
+            if (!url)
+                continue;
+            if (!url.startsWith("http://") && !url.startsWith("https://")) {
+                console.warn(`[agentikit] Ignoring AKM_REGISTRY_URL entry: must start with http:// or https://, got "${url}"`);
+                continue;
+            }
+            entries.push({ url });
+        }
+        return entries;
     }
     const registries = configRegistries ?? loadConfig().registries ?? DEFAULT_CONFIG.registries ?? [];
     return registries.filter((r) => r.enabled !== false);
@@ -89,6 +97,3 @@ function clampLimit(limit) {
         return 20;
     return Math.min(100, Math.max(1, Math.trunc(limit)));
 }
-function toErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/renderers.js

@@ -54,7 +54,7 @@ export function extractCommentTags(filePath) {
     catch {
         return {};
     }
-    const lines = content.split(/\r?\n/).slice(0, 50);
+    const lines = content.split(/\r?\n/, 50);
     const hints = {};
     for (const line of lines) {
         const trimmed = line.trim();
@@ -89,10 +89,11 @@ export function extractCommentTags(filePath) {
 export function detectExecHints(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     const hints = {};
-    // Interpreter from extension
+    // Interpreter from extension — use basename so the run command is portable
+    // relative to the stash root (callers set cwd to the file's directory).
     const interpreter = INTERPRETER_MAP[ext];
     if (interpreter) {
-        hints.run = `${interpreter} ${filePath}`;
+        hints.run = `${interpreter} ${path.basename(filePath)}`;
     }
     // Setup from nearby dependency files
     const dir = path.dirname(filePath);
@@ -206,7 +207,7 @@ const commandMdRenderer = {
             action: "Fill $ARGUMENTS placeholders in the template, then dispatch",
             description: toStringOrUndefined(parsedMd.data.description),
             template,
-            modelHint: parsedMd.data.model,
+            modelHint: typeof parsedMd.data.model === "string" ? parsedMd.data.model : undefined,
             agent: toStringOrUndefined(parsedMd.data.agent),
             parameters: extractParameters(template),
         };
@@ -226,7 +227,7 @@ const agentMdRenderer = {
             description: toStringOrUndefined(parsedMd.data.description),
             prompt: parsedMd.content,
             toolPolicy: parsedMd.data.tools,
-            modelHint: parsedMd.data.model,
+            modelHint: typeof parsedMd.data.model === "string" ? parsedMd.data.model : undefined,
         };
     },
 };
@@ -308,7 +309,21 @@ const knowledgeMdRenderer = {
         }
     },
 };
-// ── 5. script-source ─────────────────────────────────────────────────────────
+// ── 5. memory-md ─────────────────────────────────────────────────────────────
+const memoryMdRenderer = {
+    name: "memory-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        return {
+            type: "memory",
+            name,
+            path: ctx.absPath,
+            action: "Recall context — read the content below",
+            content: ctx.content(),
+        };
+    },
+};
+// ── 6. script-source ─────────────────────────────────────────────────────────
 const scriptSourceRenderer = {
     name: "script-source",
     buildShowResponse(ctx) {
@@ -371,6 +386,7 @@ const builtinRenderers = [
     commandMdRenderer,
     agentMdRenderer,
     knowledgeMdRenderer,
+    memoryMdRenderer,
     scriptSourceRenderer,
 ];
 /**
@@ -383,4 +399,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, scriptSourceRenderer, INTERPRETER_MAP, SETUP_SIGNALS, };
+export { skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, memoryMdRenderer, scriptSourceRenderer, INTERPRETER_MAP, SETUP_SIGNALS, };

package/dist/ripgrep-install.js

@@ -118,9 +118,13 @@ function downloadAndExtractZip(url, archiveName, destBinary) {
         if (dlResult.status !== 0) {
             throw new Error(dlResult.stderr?.trim() || "download failed");
         }
-        // Extract the zip archive using separate spawnSync calls with argument arrays
-        // to avoid shell injection via path interpolation in PowerShell -Command strings
-        const expandResult = spawnSync("powershell", ["-Command", "Expand-Archive", "-Path", tmpZip, "-DestinationPath", destDir, "-Force"], {
+        // Extract the zip archive. Use a single-string -Command with quoted paths to
+        // prevent PowerShell from treating subsequent array elements as separate
+        // arguments to the interpreter itself (PowerShell -Command arg1 arg2 ... would
+        // concatenate them with spaces, causing unexpected evaluation on paths with
+        // backticks or semicolons).
+        const expandCmd = `Expand-Archive -Path '${tmpZip.replace(/'/g, "''")}' -DestinationPath '${destDir.replace(/'/g, "''")}' -Force`;
+        const expandResult = spawnSync("powershell", ["-NonInteractive", "-NoProfile", "-Command", expandCmd], {
             encoding: "utf8",
             timeout: 60_000,
             env: process.env,
@@ -129,7 +133,8 @@ function downloadAndExtractZip(url, archiveName, destBinary) {
             throw new Error(expandResult.stderr?.trim() || "extraction failed");
         }
         const srcRgExe = path.join(destDir, archiveName, "rg.exe");
-        const moveResult = spawnSync("powershell", ["-Command", "Move-Item", "-Force", "-Path", srcRgExe, "-Destination", destBinary], {
+        const moveCmd = `Move-Item -Force -Path '${srcRgExe.replace(/'/g, "''")}' -Destination '${destBinary.replace(/'/g, "''")}'`;
+        const moveResult = spawnSync("powershell", ["-NonInteractive", "-NoProfile", "-Command", moveCmd], {
             encoding: "utf8",
             timeout: 60_000,
             env: process.env,

package/dist/self-update.js

@@ -91,11 +91,21 @@ export async function performUpgrade(check, opts) {
         throw new Error(`Failed to download binary: ${binaryResponse.status} ${binaryResponse.statusText}`);
     }
     const binaryData = new Uint8Array(await binaryResponse.arrayBuffer());
-    // Download and verify checksum
+    // Download and verify checksum (mandatory — upgrade is blocked if checksums cannot be fetched)
     let checksumVerified = false;
+    const skipChecksum = opts?.skipChecksum === true;
     try {
         const checksumsResponse = await fetchWithRetry(checksumsUrl);
-        if (checksumsResponse.ok) {
+        if (!checksumsResponse.ok) {
+            if (skipChecksum) {
+                console.warn(`WARNING: checksums.txt fetch failed (HTTP ${checksumsResponse.status}). Proceeding without verification because --skip-checksum was provided.`);
+            }
+            else {
+                throw new Error(`Checksum verification failed: could not fetch ${checksumsUrl} (HTTP ${checksumsResponse.status}). ` +
+                    `Use --skip-checksum to bypass (not recommended).`);
+            }
+        }
+        else {
             const checksumsText = await checksumsResponse.text();
             const expectedHash = parseChecksumForFile(checksumsText, binaryName);
             if (expectedHash) {
@@ -105,13 +115,30 @@ export async function performUpgrade(check, opts) {
                 }
                 checksumVerified = true;
             }
+            else {
+                if (skipChecksum) {
+                    console.warn(`WARNING: ${binaryName} not found in checksums.txt. Proceeding without verification because --skip-checksum was provided.`);
+                }
+                else {
+                    throw new Error(`Checksum verification failed: ${binaryName} not listed in checksums.txt. ` +
+                        `Use --skip-checksum to bypass (not recommended).`);
+                }
+            }
         }
     }
     catch (err) {
-        if (err instanceof Error && err.message.includes("Checksum mismatch")) {
+        if (err instanceof Error &&
+            (err.message.includes("Checksum mismatch") || err.message.includes("Checksum verification failed"))) {
             throw err;
         }
-        // Non-fatal: checksum file missing or unparseable
+        // Network or parse failure
+        if (skipChecksum) {
+            console.warn(`WARNING: Could not fetch or parse checksums: ${err instanceof Error ? err.message : String(err)}. Proceeding because --skip-checksum was provided.`);
+        }
+        else {
+            throw new Error(`Checksum verification failed: ${err instanceof Error ? err.message : String(err)}. ` +
+                `Use --skip-checksum to bypass (not recommended).`);
+        }
     }
     const execPath = process.execPath;
     const execDir = path.dirname(execPath);

package/dist/stash-add.js

@@ -1,15 +1,77 @@
 import fs from "node:fs";
+import path from "node:path";
 import { resolveStashDir } from "./common";
-import { loadConfig } from "./config";
+import { loadConfig, saveConfig } from "./config";
 import { UsageError } from "./errors";
 import { agentikitIndex } from "./indexer";
 import { upsertLockEntry } from "./lockfile";
-import { installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
+import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
+import { parseRegistryRef } from "./registry-resolve";
 export async function agentikitAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
         throw new UsageError("Install ref or local directory is required.");
     const stashDir = resolveStashDir();
+    // Detect local directory refs and route them to stashes[] instead of installed[]
+    try {
+        const parsed = parseRegistryRef(ref);
+        if (parsed.source === "local") {
+            return addLocalStashSource(ref, parsed.sourcePath, stashDir);
+        }
+    }
+    catch {
+        // Not a local ref — fall through to registry install
+    }
+    return addRegistryKit(ref, stashDir);
+}
+/**
+ * Add a local directory as a filesystem stash source.
+ * Creates a stashes[] entry instead of an installed[] entry.
+ */
+async function addLocalStashSource(ref, sourcePath, stashDir) {
+    const stashRoot = detectStashRoot(sourcePath);
+    const resolvedPath = path.resolve(stashRoot);
+    const config = loadConfig();
+    // Check for duplicates in stashes[]
+    const stashes = [...(config.stashes ?? [])];
+    const existing = stashes.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
+    if (!existing) {
+        const entry = {
+            type: "filesystem",
+            path: resolvedPath,
+            name: toReadableId(resolvedPath),
+        };
+        stashes.push(entry);
+        saveConfig({ ...config, stashes });
+    }
+    const index = await agentikitIndex({ stashDir });
+    const updatedConfig = loadConfig();
+    return {
+        schemaVersion: 1,
+        stashDir,
+        ref,
+        stashSource: {
+            type: "filesystem",
+            path: resolvedPath,
+            name: toReadableId(resolvedPath),
+            stashRoot: resolvedPath,
+        },
+        config: {
+            searchPaths: updatedConfig.searchPaths,
+            installedKitCount: updatedConfig.installed?.length ?? 0,
+        },
+        index: {
+            mode: index.mode,
+            totalEntries: index.totalEntries,
+            directoriesScanned: index.directoriesScanned,
+            directoriesSkipped: index.directoriesSkipped,
+        },
+    };
+}
+/**
+ * Install a kit from a registry (npm, github, git).
+ */
+async function addRegistryKit(ref, stashDir) {
     const installed = await installRegistryRef(ref);
     const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === installed.id);
     const config = upsertInstalledRegistryEntry({
@@ -23,16 +85,16 @@ export async function agentikitAdd(input) {
         cacheDir: installed.cacheDir,
         installedAt: installed.installedAt,
     });
-    upsertLockEntry({
+    await upsertLockEntry({
         id: installed.id,
         source: installed.source,
         ref: installed.ref,
         resolvedVersion: installed.resolvedVersion,
         resolvedRevision: installed.resolvedRevision,
-        integrity: installed.integrity ?? (installed.source === "local" ? "local" : undefined),
+        integrity: installed.integrity,
     });
-    // Clean up old cache directory on re-install (skip for local sources — no cache to clean)
-    if (replaced && replaced.source !== "local" && replaced.cacheDir !== installed.cacheDir) {
+    // Clean up old cache directory on re-install
+    if (replaced && replaced.cacheDir !== installed.cacheDir) {
         try {
             fs.rmSync(replaced.cacheDir, { recursive: true, force: true });
         }
@@ -69,3 +131,10 @@ export async function agentikitAdd(input) {
         },
     };
 }
+function toReadableId(resolvedPath) {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (home && resolvedPath.startsWith(home + path.sep)) {
+        return `~${resolvedPath.slice(home.length)}`;
+    }
+    return resolvedPath;
+}

package/dist/stash-clone.js

@@ -47,7 +47,7 @@ export async function agentikitClone(options) {
     let lastError;
     for (const source of searchSources) {
         try {
-            sourcePath = resolveAssetPath(source.path, parsed.type, parsed.name);
+            sourcePath = await resolveAssetPath(source.path, parsed.type, parsed.name);
             break;
         }
         catch (err) {

package/dist/stash-provider-factory.js

@@ -0,0 +1,37 @@
+/**
+ * Stash provider factory map.
+ *
+ * Maps stash source type identifiers (e.g. "filesystem", "openviking") to
+ * factory functions that create StashProvider instances from a StashConfigEntry.
+ *
+ * "Stash providers" are runtime data sources for the search and show commands —
+ * distinct from the kit-discovery registries (registry-factory.ts) and the
+ * installed-kit operations (installed-kits.ts).
+ */
+import { createProviderRegistry } from "./create-provider-registry";
+// ── Factory map ─────────────────────────────────────────────────────────────
+const registry = createProviderRegistry();
+export function registerStashProvider(type, factory) {
+    registry.register(type, factory);
+}
+export function resolveStashProviderFactory(type) {
+    return registry.resolve(type);
+}
+/**
+ * Resolve all non-filesystem stash providers from config.
+ * Filesystem entries are excluded — they are handled by resolveStashSources().
+ */
+export function resolveStashProviders(config) {
+    const providers = [];
+    for (const entry of config.stashes ?? []) {
+        if (entry.enabled === false)
+            continue;
+        if (entry.type === "filesystem")
+            continue;
+        const factory = registry.resolve(entry.type);
+        if (factory) {
+            providers.push(factory(entry));
+        }
+    }
+    return providers;
+}

package/dist/stash-provider.js

@@ -0,0 +1 @@
+export {};

package/dist/stash-providers/filesystem.js

@@ -0,0 +1,42 @@
+import { resolveStashDir } from "../common";
+import { loadConfig } from "../config";
+import { searchLocal } from "../local-search";
+import { registerStashProvider } from "../stash-provider-factory";
+import { showLocal } from "../stash-show";
+import { resolveStashSources } from "../stash-source";
+class FilesystemStashProvider {
+    type = "filesystem";
+    name;
+    stashDir;
+    config;
+    constructor(entry) {
+        this.config = loadConfig();
+        this.stashDir = entry.path ?? resolveStashDir();
+        this.name = entry.name ?? this.stashDir;
+    }
+    async search(options) {
+        const sources = resolveStashSources(this.stashDir, this.config);
+        const result = await searchLocal({
+            query: options.query.toLowerCase(),
+            searchType: options.type ?? "any",
+            limit: options.limit,
+            stashDir: this.stashDir,
+            sources,
+            config: this.config,
+        });
+        return {
+            hits: result.hits,
+            warnings: result.warnings,
+            embedMs: result.embedMs,
+            rankMs: result.rankMs,
+        };
+    }
+    async show(ref, view) {
+        return showLocal({ ref, view });
+    }
+    canShow(ref) {
+        return !ref.trim().startsWith("viking://");
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerStashProvider("filesystem", (config) => new FilesystemStashProvider(config));

package/dist/stash-providers/index.js

@@ -0,0 +1,9 @@
+/**
+ * Centralized stash provider registration.
+ *
+ * Import this module (side-effect import) to register all built-in stash
+ * providers with the provider registry. This replaces the individual
+ * side-effect imports that were duplicated in stash-search.ts and stash-show.ts.
+ */
+import "./filesystem";
+import "./openviking";