akm-cli 0.0.22 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Agent Kit Manager
 
-> Agent-i-Kit
+> **akm** — Agent Kit Manager
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![CI](https://github.com/itlackey/agentikit/actions/workflows/ci.yml/badge.svg)](https://github.com/itlackey/agentikit/actions/workflows/ci.yml)
@@ -25,7 +25,7 @@ Upgrade in place with `akm upgrade`.
 ## Quick Start
 
 ```sh
-akm init                          # Initialize your stash
+akm init                          # Initialize your working stash
 akm add github:owner/repo         # Add a kit from GitHub
 akm search "deploy"               # Find assets
 akm show script:deploy.sh         # View details and run command
@@ -89,7 +89,7 @@ Registries are indexes of available kits. The official
 ```sh
 akm registry search "code review"                                        # Search registries
 akm registry add https://example.com/registry/index.json --name team     # Add a registry
-akm sources add http://host:1933 --provider openviking \
+akm stash add http://host:1933 --provider openviking \
   --options '{"apiKey":"key"}'                                            # Add an OpenViking stash source
 akm registry list                                                        # List configured registries
 akm show viking://resources/my-doc                                       # Fetch remote content from OpenViking
@@ -130,7 +130,7 @@ See the [Kit Maker's Guide](docs/kit-makers.md) for a full walkthrough.
 | [Getting Started](docs/getting-started.md) | Quick setup guide |
 | [CLI Reference](docs/cli.md) | All commands and flags |
 | [Configuration](docs/configuration.md) | Settings, providers, and Ollama setup |
-| [Concepts](docs/concepts.md) | Asset types, classification, stash model |
+| [Concepts](docs/concepts.md) | Stashes, kits, registries, asset types |
 | [Kit Maker's Guide](docs/kit-makers.md) | Build and share kits |
 | [Registry](docs/registry.md) | Registries, search, and the v2 index format |
 

package/dist/asset-spec.js

@@ -79,7 +79,7 @@ export function _setAssetTypeHooks(rendererHook, actionBuilderHook) {
     _registerActionBuilder = actionBuilderHook;
 }
 /**
- * Register a custom asset type with the Agentikit asset system.
+ * Register a custom asset type with the akm asset system.
  *
  * ## Full extension registration API
  *

package/dist/cli.js

@@ -6,18 +6,18 @@ import { resolveStashDir } from "./common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./config-cli";
 import { ConfigError, NotFoundError, UsageError } from "./errors";
-import { agentikitIndex } from "./indexer";
-import { agentikitInit } from "./init";
-import { agentikitList, agentikitRemove, agentikitUpdate } from "./installed-kits";
+import { akmIndex } from "./indexer";
+import { akmInit } from "./init";
+import { akmList, akmRemove, akmUpdate } from "./installed-kits";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
 import { buildRegistryIndex, writeRegistryIndex } from "./registry-build-index";
 import { searchRegistry } from "./registry-search";
 import { checkForUpdate, performUpgrade } from "./self-update";
-import { agentikitAdd } from "./stash-add";
-import { agentikitClone } from "./stash-clone";
-import { agentikitSearch, parseSearchSource } from "./stash-search";
-import { agentikitShowUnified } from "./stash-show";
-import { resolveStashSources } from "./stash-source";
+import { akmAdd, akmKitAdd } from "./stash-add";
+import { akmClone } from "./stash-clone";
+import { akmSearch, parseSearchSource } from "./stash-search";
+import { akmShowUnified } from "./stash-show";
+import { addStash, listStashes, removeStash } from "./stash-source-manage";
 import { setQuiet, warn } from "./warn";
 // Version: prefer compile-time define, then package.json, then fallback
 const pkgVersion = (() => {
@@ -405,14 +405,14 @@ function formatSearchPlain(r, detail) {
 const initCommand = defineCommand({
     meta: {
         name: "init",
-        description: "Initialize Agent-i-Kit's working stash directory and persist stashDir in config",
+        description: "Initialize akm's working stash directory and persist stashDir in config",
     },
     args: {
         dir: { type: "string", description: "Custom stash directory path (default: ~/akm)" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitInit({ dir: args.dir });
+            const result = await akmInit({ dir: args.dir });
             output("init", result);
         });
     },
@@ -424,7 +424,7 @@ const indexCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitIndex({ full: args.full });
+            const result = await akmIndex({ full: args.full });
             output("index", result);
         });
     },
@@ -451,7 +451,7 @@ const searchCommand = defineCommand({
             }
             const limit = limitRaw;
             const source = parseSearchSource(args.source);
-            const result = await agentikitSearch({ query: args.query, type, limit, source });
+            const result = await akmSearch({ query: args.query, type, limit, source });
             output("search", result);
         });
     },
@@ -467,7 +467,7 @@ const addCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitAdd({ ref: args.ref });
+            const result = await akmAdd({ ref: args.ref });
             output("add", result);
         });
     },
@@ -476,7 +476,7 @@ const listCommand = defineCommand({
     meta: { name: "list", description: "List installed kits" },
     async run() {
         await runWithJsonErrors(async () => {
-            const result = await agentikitList();
+            const result = await akmList();
             output("list", result);
         });
     },
@@ -488,7 +488,7 @@ const removeCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitRemove({ target: args.target });
+            const result = await akmRemove({ target: args.target });
             output("remove", result);
         });
     },
@@ -502,11 +502,36 @@ const updateCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitUpdate({ target: args.target, all: args.all, force: args.force });
+            const result = await akmUpdate({ target: args.target, all: args.all, force: args.force });
             output("update", result);
         });
     },
 });
+const kitAddCommand = defineCommand({
+    meta: { name: "add", description: "Install a kit from npm, GitHub, or any git host" },
+    args: {
+        ref: {
+            type: "positional",
+            description: "Registry ref (npm package, owner/repo, or git URL)",
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = await akmKitAdd({ ref: args.ref });
+            output("add", result);
+        });
+    },
+});
+const kitCommand = defineCommand({
+    meta: { name: "kit", description: "Manage installed kits" },
+    subCommands: {
+        add: kitAddCommand,
+        list: listCommand,
+        remove: removeCommand,
+        update: updateCommand,
+    },
+});
 const upgradeCommand = defineCommand({
     meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
     args: {
@@ -568,7 +593,7 @@ const showCommand = defineCommand({
                         throw new UsageError(`Unknown view mode: ${args.akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
-            const result = await agentikitShowUnified({ ref: args.ref, view });
+            const result = await akmShowUnified({ ref: args.ref, view });
             output("show", result);
         });
     },
@@ -672,7 +697,7 @@ const configCommand = defineCommand({
 const cloneCommand = defineCommand({
     meta: {
         name: "clone",
-        description: "Clone an asset from any stash source into the working stash or a custom destination",
+        description: "Clone an asset from any source into the working stash or a custom destination",
     },
     args: {
         ref: { type: "positional", description: "Asset ref (e.g. npm:@scope/pkg//script:deploy.sh)", required: true },
@@ -682,7 +707,7 @@ const cloneCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitClone({
+            const result = await akmClone({
                 sourceRef: args.ref,
                 newName: args.name,
                 force: args.force,
@@ -814,28 +839,21 @@ const registryCommand = defineCommand({
         }),
     },
 });
-const sourcesCommand = defineCommand({
-    meta: { name: "sources", description: "Manage stash sources (local paths and remote providers)" },
-    subCommands: {
+/**
+ * Subcommand definitions for managing additional stashes.
+ */
+function buildSourceSubCommands(outputPrefix) {
+    return {
         list: defineCommand({
-            meta: { name: "list", description: "List all stash sources" },
+            meta: { name: "list", description: "List all stashes in search order" },
             run() {
                 return runWithJsonErrors(() => {
-                    const config = loadConfig();
-                    const localSources = resolveStashSources();
-                    const stashes = config.stashes ?? [];
-                    // Legacy fallback: show remoteStashSources if no stashes config
-                    const legacyRemote = !config.stashes ? (config.remoteStashSources ?? []) : [];
-                    output("sources", {
-                        localSources,
-                        stashes,
-                        ...(legacyRemote.length > 0 ? { remoteSources: legacyRemote } : {}),
-                    });
+                    output(`${outputPrefix}`, listStashes());
                 });
             },
         }),
         add: defineCommand({
-            meta: { name: "add", description: "Add a stash source (filesystem path or remote URL)" },
+            meta: { name: "add", description: "Register an additional stash (filesystem path or remote URL)" },
             args: {
                 target: { type: "positional", description: "Path or URL to add", required: true },
                 name: { type: "string", description: "Human-friendly name for the source" },
@@ -844,75 +862,51 @@ const sourcesCommand = defineCommand({
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const config = loadConfig();
-                    const stashes = [...(config.stashes ?? [])];
-                    const isUrl = args.target.startsWith("http://") || args.target.startsWith("https://");
-                    if (isUrl) {
-                        if (args.target.startsWith("http://")) {
-                            warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
-                        }
-                        const providerType = args.provider;
-                        if (!providerType) {
-                            throw new UsageError("--provider is required for URL sources (e.g. --provider openviking)");
-                        }
-                        if (stashes.some((s) => s.url === args.target)) {
-                            output("sources-add", { stashes, added: false, message: "Source URL already configured" });
-                            return;
-                        }
-                        const entry = { type: providerType, url: args.target };
-                        if (args.name)
-                            entry.name = args.name;
-                        if (args.options) {
-                            try {
-                                entry.options = JSON.parse(args.options);
-                            }
-                            catch {
-                                throw new UsageError("--options must be valid JSON");
+                    if (args.target.startsWith("http://")) {
+                        warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
+                    }
+                    let parsedOptions;
+                    if (args.options) {
+                        try {
+                            const parsed = JSON.parse(args.options);
+                            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                                throw new UsageError("--options must be a JSON object");
                             }
+                            parsedOptions = parsed;
                         }
-                        stashes.push(entry);
-                    }
-                    else {
-                        // Filesystem path
-                        const resolvedPath = path.resolve(args.target);
-                        if (stashes.some((s) => s.path === resolvedPath)) {
-                            output("sources-add", { stashes, added: false, message: "Source path already configured" });
-                            return;
+                        catch (err) {
+                            if (err instanceof UsageError)
+                                throw err;
+                            throw new UsageError("--options must be valid JSON");
                         }
-                        const entry = { type: "filesystem", path: resolvedPath };
-                        if (args.name)
-                            entry.name = args.name;
-                        stashes.push(entry);
                     }
-                    // Migrate: remove remoteStashSources when moving to stashes
-                    const { remoteStashSources, ...rest } = config;
-                    saveConfig({ ...rest, stashes });
-                    output("sources-add", { stashes, added: true });
+                    const result = addStash({
+                        target: args.target,
+                        name: args.name,
+                        providerType: args.provider,
+                        options: parsedOptions,
+                    });
+                    output(`${outputPrefix}-add`, result);
                 });
             },
         }),
         remove: defineCommand({
-            meta: { name: "remove", description: "Remove a stash source by URL, path, or name" },
+            meta: { name: "remove", description: "Remove an additional stash by URL, path, or name" },
             args: {
                 target: { type: "positional", description: "Source URL, path, or name to remove", required: true },
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const config = loadConfig();
-                    const stashes = [...(config.stashes ?? [])];
-                    const resolvedTarget = args.target.startsWith("http") ? args.target : path.resolve(args.target);
-                    const idx = stashes.findIndex((s) => s.url === resolvedTarget || s.path === resolvedTarget || s.name === resolvedTarget);
-                    if (idx === -1) {
-                        output("sources-remove", { stashes, removed: false, message: "No matching source found" });
-                        return;
-                    }
-                    const removed = stashes.splice(idx, 1)[0];
-                    saveConfig({ ...config, stashes });
-                    output("sources-remove", { stashes, removed: true, entry: removed });
+                    const result = removeStash(args.target);
+                    output(`${outputPrefix}-remove`, result);
                 });
             },
         }),
-    },
+    };
+}
+const stashCommand = defineCommand({
+    meta: { name: "stash", description: "Manage additional stashes (local directories and remote providers)" },
+    subCommands: buildSourceSubCommands("stash"),
 });
 const hintsCommand = defineCommand({
     meta: {
@@ -931,7 +925,7 @@ const main = defineCommand({
     meta: {
         name: "akm",
         version: pkgVersion,
-        description: "CLI tool to search, open, and manage assets from Agent-i-Kit stash.",
+        description: "Agent Kit Manager — search, show, and manage assets from your stash.",
     },
     args: {
         format: { type: "string", description: "Output format (json|text|yaml)" },
@@ -945,11 +939,12 @@ const main = defineCommand({
         list: listCommand,
         remove: removeCommand,
         update: updateCommand,
+        kit: kitCommand,
         upgrade: upgradeCommand,
         search: searchCommand,
         show: showCommand,
         clone: cloneCommand,
-        sources: sourcesCommand,
+        stash: stashCommand,
         registry: registryCommand,
         config: configCommand,
         hints: hintsCommand,
@@ -1104,14 +1099,14 @@ function loadHints(detail = "normal") {
 }
 const EMBEDDED_HINTS = `# akm CLI
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search the stash first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your stashes first before writing something from scratch.
 
 ## Quick Reference
 
 \`\`\`sh
-akm search "<query>"                          # Search for assets
+akm search "<query>"                          # Search your stashes and installed kits
 akm search "<query>" --type skill             # Filter by type
-akm search "<query>" --source both            # Search stash providers and registries for assets
+akm search "<query>" --source both            # Also search registries for installable kits
 akm show <ref>                                # View asset details
 akm add <ref>                                 # Install a kit (npm, GitHub, git, local)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
@@ -1132,14 +1127,14 @@ Run \`akm -h\` for the full command reference.
 `;
 const EMBEDDED_HINTS_FULL = `# akm CLI — Full Reference
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search the stash first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your stashes first before writing something from scratch.
 
 ## Search
 
 \`\`\`sh
-akm search "<query>"                          # Search local stash
+akm search "<query>"                          # Search your stashes and installed kits
 akm search "<query>" --type skill             # Filter by asset type
-akm search "<query>" --source both            # Search all stash providers and registries
+akm search "<query>" --source both            # Also search registries for installable kits
 akm search "<query>" --source registry        # Search registries only
 akm search "<query>" --limit 10               # Limit results
 akm search "<query>" --detail full            # Include scores, paths, timing
@@ -1180,10 +1175,14 @@ akm show viking://resources/my-doc           # Show remote OpenViking content
 ## Install & Manage Kits
 
 \`\`\`sh
-akm add <ref>                                 # Install a kit
+akm add <ref>                                 # Install a kit (smart router: local dirs become stash adds)
 akm add @scope/kit                            # From npm
 akm add owner/repo                            # From GitHub
-akm add ./path/to/local/kit                   # From local directory
+akm add ./path/to/local/kit                   # From local directory (adds as stash)
+akm kit add <ref>                             # Install a kit (explicit)
+akm kit list                                  # List installed kits
+akm kit remove <target>                       # Remove a kit
+akm kit update --all                          # Update all kits
 akm list                                      # List installed kits
 akm remove <target>                           # Remove by id or ref
 akm update --all                              # Update all installed kits
@@ -1231,10 +1230,11 @@ akm config path --all                         # Show all config paths
 ## Other Commands
 
 \`\`\`sh
-akm init                                      # Initialize stash directory
+akm init                                      # Initialize working stash
 akm index                                     # Rebuild search index
 akm index --full                              # Full reindex
-akm sources                                   # List stash search paths
+akm stash                                     # List all stashes
+akm kit                                       # Kit management (add, list, remove, update)
 akm upgrade                                   # Upgrade akm binary
 akm upgrade --check                           # Check for updates
 akm hints                                     # Print this reference

package/dist/config-cli.js

@@ -9,24 +9,12 @@ export function parseConfigValue(key, value) {
                 throw new UsageError(`Invalid value for semanticSearch: expected "true" or "false"`);
             }
             return { semanticSearch: value === "true" };
-        case "searchPaths":
-            try {
-                const parsed = JSON.parse(value);
-                if (!Array.isArray(parsed))
-                    throw new UsageError("expected JSON array");
-                return { searchPaths: parsed.filter((d) => typeof d === "string") };
-            }
-            catch {
-                throw new UsageError(`Invalid value for searchPaths: expected JSON array (e.g. '["/path/a","/path/b"]')`);
-            }
         case "embedding":
             return { embedding: parseEmbeddingConnectionValue(value) };
         case "llm":
             return { llm: parseLlmConnectionValue(value) };
         case "registries":
             return { registries: parseRegistriesValue(value) };
-        case "remoteStashSources":
-            return { remoteStashSources: parseStashesValue(value) };
         case "stashes":
             return { stashes: parseStashesValue(value) };
         case "output.format":
@@ -43,16 +31,12 @@ export function getConfigValue(config, key) {
             return config.stashDir ?? null;
         case "semanticSearch":
             return config.semanticSearch;
-        case "searchPaths":
-            return [...config.searchPaths];
         case "embedding":
             return config.embedding ?? null;
         case "llm":
             return config.llm ?? null;
         case "registries":
             return config.registries ?? DEFAULT_CONFIG.registries ?? [];
-        case "remoteStashSources":
-            return config.remoteStashSources ?? [];
         case "stashes":
             return config.stashes ?? [];
         case "output.format":
@@ -67,11 +51,9 @@ export function setConfigValue(config, key, rawValue) {
     switch (key) {
         case "stashDir":
         case "semanticSearch":
-        case "searchPaths":
         case "embedding":
         case "llm":
         case "registries":
-        case "remoteStashSources":
         case "stashes":
         case "output.format":
         case "output.detail":
@@ -90,8 +72,6 @@ export function unsetConfigValue(config, key) {
             return { ...config, llm: undefined };
         case "registries":
             return { ...config, registries: undefined };
-        case "remoteStashSources":
-            return { ...config, remoteStashSources: undefined };
         case "stashes":
             return { ...config, stashes: undefined };
         case "output.format":
@@ -115,11 +95,6 @@ export function listConfig(config) {
         result.embedding = config.embedding;
     if (config.llm)
         result.llm = config.llm;
-    // Show legacy keys only if they still have content
-    if (config.searchPaths?.length)
-        result.searchPaths = config.searchPaths;
-    if (config.remoteStashSources?.length)
-        result.remoteStashSources = config.remoteStashSources;
     return result;
 }
 function mergeConfigValue(config, partial) {