agentikit 0.0.8 → 0.0.12

package/dist/src/cli.js

@@ -1,15 +1,19 @@
 #!/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";
-import { resolveStashDir } from "./common";
+import { agentikitClone } from "./stash-clone";
+import { resolveStashSources } from "./stash-source";
+import { loadConfig, saveConfig } from "./config";
+import { getConfigValue, listConfig, listProviders, parseConfigValue, setConfigValue, unsetConfigValue, useProvider, } from "./config-cli";
 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));
+    meta: { name: "init", description: "Initialize Agent-i-Kit's working stash directory and set AKM_STASH_DIR" },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await agentikitInit();
+            console.log(JSON.stringify(result, null, 2));
+        });
     },
 });
 const indexCommand = defineCommand({
@@ -18,21 +22,87 @@ 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({
     meta: { name: "search", description: "Search the stash" },
     args: {
         query: { type: "positional", description: "Search query", required: false, default: "" },
-        type: { type: "string", description: "Asset type filter (tool|skill|command|agent|knowledge|any)" },
+        type: { type: "string", description: "Asset type filter (tool|skill|command|agent|knowledge|script|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 }) {
+        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 or local git directory into the stash" },
+    args: {
+        ref: {
+            type: "positional",
+            description: "Registry ref (npm package, owner/repo, github URL, or local git directory)",
+            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 }) {
-        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 () => {
+            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({
@@ -44,121 +114,286 @@ const showCommand = defineCommand({
         start: { type: "string", description: "Start line (for --view lines)" },
         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);
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            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(await agentikitShow({ ref: args.ref, view }), null, 2));
+        });
     },
 });
 const configCommand = defineCommand({
-    meta: { name: "config", description: "Show or update configuration" },
+    meta: { name: "config", description: "Show configuration, get/set keys, and manage embedding/LLM providers" },
     args: {
-        set: { type: "string", description: "Update a config key (key=value format)" },
+        list: { type: "boolean", description: "List current configuration with effective defaults", default: false },
+        get: { type: "string", description: "Get a configuration value by key" },
+        unset: { type: "string", description: "Unset an optional configuration key or whole embedding/llm section" },
+        set: { type: "string", description: "Back-compat alias for updating a key (key=value format)" },
+    },
+    subCommands: {
+        list: defineCommand({
+            meta: { name: "list", description: "List current configuration with effective embedding/LLM settings" },
+            run() {
+                return runWithJsonErrors(() => {
+                    console.log(JSON.stringify(listConfig(loadConfig()), null, 2));
+                });
+            },
+        }),
+        get: defineCommand({
+            meta: { name: "get", description: "Get a configuration value by key" },
+            args: {
+                key: { type: "positional", required: true, description: "Config key (for example: embedding.provider)" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    console.log(JSON.stringify(getConfigValue(loadConfig(), args.key), null, 2));
+                });
+            },
+        }),
+        set: defineCommand({
+            meta: { name: "set", description: "Set a configuration value by key" },
+            args: {
+                key: { type: "positional", required: true, description: "Config key (for example: llm.temperature)" },
+                value: { type: "positional", required: true, description: "Config value" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const updated = setConfigValue(loadConfig(), args.key, args.value);
+                    saveConfig(updated);
+                    console.log(JSON.stringify(listConfig(updated), null, 2));
+                });
+            },
+        }),
+        unset: defineCommand({
+            meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/llm section" },
+            args: {
+                key: { type: "positional", required: true, description: "Config key to unset" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const updated = unsetConfigValue(loadConfig(), args.key);
+                    saveConfig(updated);
+                    console.log(JSON.stringify(listConfig(updated), null, 2));
+                });
+            },
+        }),
+        providers: defineCommand({
+            meta: { name: "providers", description: "List available embedding or LLM providers" },
+            args: {
+                scope: { type: "positional", required: true, description: "Provider scope: embedding or llm" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const scope = parseProviderScope(args.scope);
+                    console.log(JSON.stringify(listProviders(scope, loadConfig()), null, 2));
+                });
+            },
+        }),
+        use: defineCommand({
+            meta: { name: "use", description: "Switch the default embedding or LLM provider" },
+            args: {
+                scope: { type: "positional", required: true, description: "Provider scope: embedding or llm" },
+                provider: { type: "positional", required: true, description: "Provider name" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const scope = parseProviderScope(args.scope);
+                    const updated = useProvider(loadConfig(), scope, args.provider);
+                    saveConfig(updated);
+                    console.log(JSON.stringify(listConfig(updated), null, 2));
+                });
+            },
+        }),
     },
     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(() => {
+            if (hasConfigSubcommand(args))
+                return;
+            if (args.list) {
+                console.log(JSON.stringify(listConfig(loadConfig()), null, 2));
+                return;
+            }
+            if (args.get) {
+                console.log(JSON.stringify(getConfigValue(loadConfig(), args.get), null, 2));
+                return;
+            }
+            if (args.unset) {
+                const updated = unsetConfigValue(loadConfig(), args.unset);
+                saveConfig(updated);
+                console.log(JSON.stringify(listConfig(updated), null, 2));
+                return;
             }
-            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));
-        }
+            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 = { ...loadConfig(), ...partial };
+                saveConfig(config);
+                console.log(JSON.stringify(listConfig(config), null, 2));
+            }
+            else {
+                console.log(JSON.stringify(listConfig(loadConfig()), null, 2));
+            }
+        });
+    },
+});
+const cloneCommand = defineCommand({
+    meta: { name: "clone", description: "Clone an asset from any stash source into the working stash" },
+    args: {
+        ref: { type: "positional", description: "Asset ref (e.g. @installed:pkg/tool:script.sh)", required: true },
+        name: { type: "string", description: "New name for the cloned asset" },
+        force: { type: "boolean", description: "Overwrite if asset already exists in working stash", default: false },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = await agentikitClone({
+                sourceRef: args.ref,
+                newName: args.name,
+                force: args.force,
+            });
+            console.log(JSON.stringify(result, null, 2));
+        });
+    },
+});
+const sourcesCommand = defineCommand({
+    meta: { name: "sources", description: "List all stash sources with their kind, path, and status" },
+    run() {
+        return runWithJsonErrors(() => {
+            const sources = resolveStashSources();
+            console.log(JSON.stringify({ sources }, null, 2));
+        });
     },
 });
 const main = defineCommand({
     meta: {
         name: "akm",
-        description: "CLI tool to search, open, and run extension assets from an agentikit stash directory.",
+        description: "CLI tool to search, open, and manage assets from Agent-i-Kit stash.",
     },
     subCommands: {
         init: initCommand,
         index: indexCommand,
+        add: addCommand,
+        list: listCommand,
+        remove: removeCommand,
+        update: updateCommand,
+        reinstall: reinstallCommand,
         search: searchCommand,
         show: showCommand,
+        clone: cloneCommand,
+        sources: sourcesCommand,
         config: configCommand,
     },
 });
+const SEARCH_USAGE_MODES = ["none", "both", "item", "guide"];
+const SEARCH_SOURCES = ["local", "registry", "both"];
+const CONFIG_SUBCOMMAND_SET = new Set(["list", "get", "set", "unset", "providers", "use"]);
+// Note: citty reads process.argv directly, so we must normalize it in-place.
+// This is done once at startup before runMain.
+normalizeConfigArgv(process.argv);
 runMain(main);
-function parseConnectionValue(key, value, exampleEndpoint, exampleModel) {
-    if (value === "null" || value === "")
-        return undefined;
-    let parsed;
+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("|")}`);
+}
+async function runWithJsonErrors(fn) {
     try {
-        parsed = JSON.parse(value);
+        await fn();
     }
-    catch {
-        throw new Error(`Invalid value for ${key}: expected JSON object with endpoint and model`
-            + ` (e.g. '{"endpoint":"${exampleEndpoint}","model":"${exampleModel}"}')`);
+    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);
     }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Invalid value for ${key}: expected a JSON object`);
+}
+function buildHint(message) {
+    if (message.includes("AKM_STASH_DIR"))
+        return "Run `akm init` or set AKM_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.";
+    if (message.includes("expected JSON object with endpoint and model")) {
+        return "Quote JSON values in your shell, for example: akm config set embedding '{\"endpoint\":\"http://localhost:11434/v1/embeddings\",\"model\":\"nomic-embed-text\"}'.";
+    }
+    return undefined;
+}
+function parseProviderScope(value) {
+    if (value === "embedding" || value === "llm")
+        return value;
+    throw new Error(`Invalid provider scope: ${value}. Expected one of: embedding|llm`);
+}
+function hasConfigSubcommand(args) {
+    const command = Array.isArray(args._) ? args._[0] : undefined;
+    return typeof command === "string" && CONFIG_SUBCOMMAND_SET.has(command);
+}
+/**
+ * Mutate argv before citty parses it so git-style config forms like
+ * `akm config llm.maxTokens 512` and `akm config --get llm.maxTokens`
+ * are normalized into the existing config subcommands.
+ */
+function normalizeConfigArgv(argv) {
+    const [, , command, argAfterCommand, argAfterKey, ...rest] = argv;
+    if (command !== "config")
+        return;
+    if (!argAfterCommand)
+        return;
+    if (argAfterCommand === "--list") {
+        argv.splice(3, argv.length - 3, "list");
+        return;
     }
-    const obj = parsed;
-    if (typeof obj.endpoint !== "string" || !obj.endpoint || typeof obj.model !== "string" || !obj.model) {
-        throw new Error(`Invalid value for ${key}: "endpoint" and "model" are required string fields`);
+    if (argAfterCommand === "--get" && argAfterKey) {
+        argv.splice(3, argv.length - 3, "get", argAfterKey, ...rest);
+        return;
     }
-    const result = {
-        endpoint: obj.endpoint,
-        model: obj.model,
-    };
-    if (typeof obj.apiKey === "string" && obj.apiKey) {
-        result.apiKey = obj.apiKey;
+    if (argAfterCommand === "--unset" && argAfterKey) {
+        argv.splice(3, argv.length - 3, "unset", argAfterKey, ...rest);
+        return;
     }
-    return result;
-}
-function parseConfigValue(key, value) {
-    switch (key) {
-        case "semanticSearch":
-            if (value !== "true" && value !== "false") {
-                throw new Error(`Invalid value for semanticSearch: expected "true" or "false"`);
-            }
-            return { semanticSearch: value === "true" };
-        case "additionalStashDirs":
-            try {
-                const parsed = JSON.parse(value);
-                if (!Array.isArray(parsed))
-                    throw new Error("expected JSON array");
-                return { additionalStashDirs: parsed.filter((d) => typeof d === "string") };
-            }
-            catch {
-                throw new Error(`Invalid value for additionalStashDirs: expected JSON array (e.g. '["/path/a","/path/b"]')`);
-            }
-        case "embedding":
-            return { embedding: parseConnectionValue("embedding", value, "http://localhost:11434/v1/embeddings", "nomic-embed-text") };
-        case "llm":
-            return { llm: parseConnectionValue("llm", value, "http://localhost:11434/v1/chat/completions", "llama3.2") };
-        default:
-            throw new Error(`Unknown config key: ${key}`);
+    if (argAfterCommand.startsWith("-"))
+        return;
+    if (CONFIG_SUBCOMMAND_SET.has(argAfterCommand))
+        return;
+    // A single arg after `config` behaves like `git config <key>` and reads the value.
+    if (argAfterKey === undefined) {
+        argv.splice(3, argv.length - 3, "get", argAfterCommand);
+        return;
     }
+    argv.splice(3, argv.length - 3, "set", argAfterCommand, argAfterKey, ...rest);
 }

package/dist/src/common.d.ts

@@ -1,4 +1,4 @@
-export type AgentikitAssetType = "tool" | "skill" | "command" | "agent" | "knowledge";
+export type AgentikitAssetType = "tool" | "skill" | "command" | "agent" | "knowledge" | "script";
 export declare const IS_WINDOWS: boolean;
 export { SCRIPT_EXTENSIONS, TYPE_DIRS } from "./asset-spec";
 export declare function isAssetType(type: string): type is AgentikitAssetType;
@@ -6,3 +6,8 @@ export declare function resolveStashDir(): string;
 export declare function toPosix(input: string): string;
 export declare function hasErrnoCode(error: unknown, code: string): boolean;
 export declare function isWithin(candidate: string, root: string): boolean;
+/**
+ * Fetch with an AbortController timeout.
+ * Defaults to 30 seconds if no timeout is specified.
+ */
+export declare function fetchWithTimeout(url: string, opts?: RequestInit, timeoutMs?: number): Promise<Response>;

package/dist/src/common.js

@@ -10,9 +10,9 @@ export function isAssetType(type) {
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
 export function resolveStashDir() {
-    const raw = process.env.AGENTIKIT_STASH_DIR?.trim();
+    const raw = process.env.AKM_STASH_DIR?.trim();
     if (!raw) {
-        throw new Error("AGENTIKIT_STASH_DIR is not set. Set it to your Agentikit stash path.");
+        throw new Error("AKM_STASH_DIR is not set. Set it to your Agentikit stash path.");
     }
     const stashDir = path.resolve(raw);
     let stat;
@@ -20,10 +20,10 @@ export function resolveStashDir() {
         stat = fs.statSync(stashDir);
     }
     catch {
-        throw new Error(`Unable to read AGENTIKIT_STASH_DIR at "${stashDir}".`);
+        throw new Error(`Unable to read AKM_STASH_DIR at "${stashDir}".`);
     }
     if (!stat.isDirectory()) {
-        throw new Error(`AGENTIKIT_STASH_DIR must point to a directory: "${stashDir}".`);
+        throw new Error(`AKM_STASH_DIR must point to a directory: "${stashDir}".`);
     }
     return stashDir;
 }
@@ -44,3 +44,17 @@ export function isWithin(candidate, root) {
 function normalizeFsPathForComparison(value) {
     return process.platform === "win32" ? value.toLowerCase() : value;
 }
+/**
+ * Fetch with an AbortController timeout.
+ * Defaults to 30 seconds if no timeout is specified.
+ */
+export async function fetchWithTimeout(url, opts, timeoutMs = 30_000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...opts, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/config-cli.d.ts

@@ -0,0 +1,9 @@
+import { type AgentikitConfig } from "./config";
+export type ConfigProviderScope = "embedding" | "llm";
+export declare function parseConfigValue(key: string, value: string): Partial<AgentikitConfig>;
+export declare function getConfigValue(config: AgentikitConfig, key: string): unknown;
+export declare function setConfigValue(config: AgentikitConfig, key: string, rawValue: string): AgentikitConfig;
+export declare function unsetConfigValue(config: AgentikitConfig, key: string): AgentikitConfig;
+export declare function listConfig(config: AgentikitConfig): Record<string, unknown>;
+export declare function listProviders(scope: ConfigProviderScope, config: AgentikitConfig): Array<Record<string, unknown>>;
+export declare function useProvider(config: AgentikitConfig, scope: ConfigProviderScope, providerName: string): AgentikitConfig;