akm-cli 0.0.19 → 0.0.21

package/README.md

@@ -10,167 +10,97 @@ A package manager for AI agent capabilities -- scripts, skills, commands,
 agents, and knowledge -- that works with any AI coding assistant that can run
 shell commands.
 
-`akm` organizes reusable scripts, prompts, and agent configs into a searchable
-**stash**, shares them as installable **kits** via **registries**, and gives
-any model a way to discover and use them. No plugins required -- just CLI
-output any tool-calling model can read.
+## Install
 
-## Requirements
+```sh
+# Standalone binary (no runtime dependencies)
+curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
 
-`akm` requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses Bun-specific
-APIs (`bun:sqlite`) that are **not available in Node.js**.
+# Or via Bun
+bun install -g akm-cli
+```
 
-> **Don't want Bun?** Use the [standalone binary](#standalone-binary) instead -- it
-> bundles everything and has no runtime dependencies.
+Upgrade in place with `akm upgrade`.
 
 ## Quick Start
 
 ```sh
-# Install (requires Bun v1.0+)
-bun install -g akm-cli
-
-# Initialize your stash
-akm init
-
-# Add a kit from GitHub
-akm add github:owner/repo
-
-# Clone an asset to a specific directory
-akm clone script:deploy.sh --dest ./project/.claude
-
-# Search for assets
-akm search "deploy"
-
-# Show an asset
-akm show script:deploy.sh
+akm init                          # Initialize your 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
 ```
 
-## Works Any AI Agent
-
-`akm` is platform agnostic. Any model that can execute shell commands can search
-your stash and use what it finds. The workflow is three commands:
-
-1. `akm search "what you need"` -- find relevant assets (returns JSON by default)
-2. `akm show <ref>` -- get the details (run command, instructions, prompt, etc.)
-3. Use the asset -- execute the `run` command, follow the skill instructions, fill in the template
+## Features
 
-### Drop-in prompt snippet
+### Works with Any AI Agent
 
-Add this to your `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, system prompt, or any instruction
-file to give your agent access to your stash without any additional setup:
+Any model that can run shell commands can use `akm`. Add this to your
+`AGENTS.md`, `CLAUDE.md`, or system prompt:
 
 ~~~markdown
 ## Resources & Capabilities
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via the `akm` CLI. Use it to find and use capabilities before writing something from scratch. Always search the stash first when you need a capability.
-
-Use `akm -h` for more information about searching and using assets.
+You have access to a searchable library of scripts, skills, commands, agents,
+and knowledge documents via the `akm` CLI. Use `akm -h` for details.
 ~~~
 
-That's it. No plugin, no SDK, no integration code. The model reads the JSON
-output from `akm` and acts on it. If you would like more detailed instructions, check out the example [AGENTS.md](docs/AGENTS.md)
-
-### Platform plugins (optional)
+No plugins, SDKs, or integration code required. Platform-specific plugins
+(e.g., [OpenCode](https://github.com/itlackey/akm-plugins?tab=readme-ov-file#opencode))
+are available for tighter integration but purely optional.
 
-For tighter integration, plugins are available for some platforms. These add
-native tool bindings so the agent doesn't need to shell out, but they're
-purely optional -- the CLI works everywhere.
+### Clone Assets Anywhere
 
-**OpenCode** -- Add the [OpenCode plugin](https://github.com/itlackey/akm-plugins?tab=readme-ov-file#opencode) to your `opencode.json`:
-
-```json
-{
-  "plugin": ["akm-opencode"]
-}
-```
-
-**Claude Code** -- Add the prompt snippet above to your `CLAUDE.md` or
-project instructions. Claude Code can run `akm` commands directly.
-
-**Everything else** -- If your agent can run shell commands, it can use `akm`.
-Add the prompt snippet above or in [AGENTS.md](docs/AGENTS.md) to whatever instruction/rules mechanism your platform uses.
-
-## The Stash
-
-Your stash is the local library where assets live. It combines three sources
-in priority order:
-
-1. **Primary stash** -- Your personal assets (`AKM_STASH_DIR`), created by `akm init`
-2. **Search paths** -- Additional directories (team shares, project dirs, etc.)
-3. **Installed kits** -- Kits from npm, GitHub, or git via `akm add` (cache-managed)
-
-The first match wins, so local assets always override installed ones. Use
-`akm clone` to fork an installed asset into your stash for editing.
-
-## Registries
-
-Registries are indexes of available kits. akm ships with the official
-[akm-registry](https://github.com/itlackey/akm-registry) pre-configured.
+`akm clone` copies any asset from your stash or a remote source into a
+target directory for local editing:
 
 ```sh
-# Search the official registry
-akm registry search "code review"
-
-# Add a third-party registry
-akm registry add https://example.com/registry/index.json --name team
-
-# List configured registries
-akm registry list
+akm clone script:deploy.sh                              # Clone to your stash
+akm clone script:deploy.sh --dest ./project/.claude     # Clone to a specific directory
+akm clone script:deploy.sh --name my-deploy.sh          # Clone with a new name
+akm clone "npm:@scope/pkg//script:deploy.sh" --force    # Clone from a remote package
 ```
 
-See the [Registry docs](docs/registry.md) for hosting your own registry,
-the v2 index format with asset-level metadata, and more.
+Key behaviors:
+- Type subdirectories are appended automatically (e.g., `--dest ./project/.claude` becomes `./project/.claude/scripts/deploy.sh`)
+- Skills clone as entire directories; scripts/commands clone as single files
+- Remote packages are fetched on-demand without registering as installed kits
+- `--force` overwrites existing assets
 
-## Searching and Showing Assets
+### skills.sh Integration
 
-Search returns brief JSON by default. Use `--detail normal` or `--detail full`
-when you want origin, tags, or explainability metadata:
+`akm` includes [skills.sh](https://skills.sh) as a built-in registry. Community
+skills from skills.sh are searchable out of the box alongside the official
+registry -- no setup required:
 
 ```sh
-akm search "docker" --type script
+akm search "code review"             # Searches skills.sh and official registry
+akm registry search "code review"    # Search registries directly
 ```
 
-```json
-{
-  "hits": [
-    {
-      "name": "docker-build",
-      "type": "script",
-      "description": "Build and push Docker images",
-      "action": "akm show script:docker-build.sh -> execute the run command"
-    }
-  ]
-}
-```
+Results include install counts and link back to skills.sh for details. The
+provider caches queries for 15 minutes with a 24-hour stale fallback.
 
-Show returns everything the agent needs to act:
+### Registries and Private Registry Support
 
-```sh
-akm show script:docker-build.sh
-```
-
-```json
-{
-  "type": "script",
-  "name": "docker-build.sh",
-  "origin": null,
-  "action": "Execute the run command below",
-  "run": "bash /path/to/scripts/docker-build.sh",
-  "setup": "bun install",
-  "cwd": "/path/to/scripts"
-}
-```
-
-For knowledge assets, navigate without loading the entire document:
+Registries are indexes of available kits. The official
+[akm-registry](https://github.com/itlackey/akm-registry) is pre-configured.
 
 ```sh
-akm show knowledge:api-guide toc
-akm show knowledge:api-guide section "Authentication"
+akm registry search "code review"                                        # Search registries
+akm registry add https://example.com/registry/index.json --name team     # Add a registry
+akm registry list                                                        # List configured registries
 ```
 
-## Installing and Sharing Kits
+Private access is supported through:
+- **GitHub tokens** -- Set `GITHUB_TOKEN` to access private GitHub repos when installing kits
+- **Provider options** -- Each registry entry supports an `options` field for provider-specific configuration (tokens, custom headers)
+- **Pluggable providers** -- Custom registry providers can implement their own authentication
+
+See the [Registry docs](docs/registry.md) for hosting your own registry and
+the v2 index format.
 
-Install kits from npm, GitHub, any git host, or local directories:
+### Install Kits from Anywhere
 
 ```sh
 akm add @scope/my-kit                       # npm
@@ -179,75 +109,27 @@ akm add git+https://gitlab.com/org/kit      # Any git repo
 akm add ./path/to/local/kit                 # Local directory
 ```
 
-Manage installed kits:
-
-```sh
-akm list                        # Show installed kits with status
-akm update --all                # Update all (reports version changes)
-akm remove owner/repo           # Remove and reindex
-akm clone script:deploy.sh      # Fork an asset into your stash for editing
-```
+Manage kits with `akm list`, `akm update --all`, and `akm remove`.
 
-### Publishing your own kit
+### Publish Your Own Kit
 
-1. Organize your assets (directory conventions are optional)
-2. Add `"akm"` to `keywords` in `package.json` or add the `akm` topic to your GitHub repo
+1. Organize your assets into a directory
+2. Add `"akm"` to `keywords` in `package.json` or the `akm` topic to your GitHub repo
 3. Optionally add `akm.include` in `package.json` to control what gets installed
 4. Publish to npm or push to GitHub
 
 See the [Kit Maker's Guide](docs/kit-makers.md) for a full walkthrough.
 
-## Installation
-
-`akm` requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses Bun-specific
-APIs (`bun:sqlite`) that are not available in Node.js.
-
-```sh
-# Install Bun if you don't have it
-curl -fsSL https://bun.sh/install | bash
-
-# Install akm
-bun install -g akm-cli
-```
-
-### Standalone binary
-
-The standalone binary bundles everything and has **no runtime dependencies** --
-no Bun, no Node.js.
-
-```sh
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
-
-# Windows (PowerShell)
-irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
-```
-
-The shell installer verifies the binary against release checksums.
-
-Upgrade the binary in place:
-
-```sh
-akm upgrade           # Download and replace the running binary
-akm upgrade --check   # Check for updates without installing
-```
-
 ## Documentation
 
 | Doc | Description |
 | --- | --- |
 | [Getting Started](docs/getting-started.md) | Quick setup guide |
-| [CLI Reference](docs/cli.md) | All `akm` commands and flags |
-| [Configuration](docs/configuration.md) | Providers, settings, and Ollama setup |
-| [Concepts](docs/concepts.md) | Asset types, classification, stash sources, metadata |
-| [Kit Maker's Guide](docs/kit-makers.md) | Build and share a kit on GitHub, npm, or a network share |
-| [Registry](docs/registry.md) | Registries, search, and managing kits |
-
-## Status
-
-`akm` is approaching v1.0. The core CLI, stash model, and registry are generally stable
-and in daily use. Feedback, issues, and PRs welcome -- especially around
-real-world usage patterns and integrations with different AI coding assistants.
+| [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 |
+| [Kit Maker's Guide](docs/kit-makers.md) | Build and share kits |
+| [Registry](docs/registry.md) | Registries, search, and the v2 index format |
 
 ## License
 

package/dist/asset-spec.js

@@ -65,6 +65,12 @@ export function isRelevantAssetFile(assetType, fileName) {
 export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
     return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath);
 }
+export function deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, filePath) {
+    const relPath = toPosix(path.relative(stashRoot, filePath));
+    const firstSegment = relPath.split("/").filter(Boolean)[0];
+    const typeRoot = firstSegment === TYPE_DIRS[assetType] ? path.join(stashRoot, firstSegment) : stashRoot;
+    return deriveCanonicalAssetName(assetType, typeRoot, filePath);
+}
 export function resolveAssetPathFromName(assetType, typeRoot, name) {
     return ASSET_SPECS[assetType].toAssetPath(typeRoot, name);
 }

package/dist/config.js

@@ -5,7 +5,10 @@ import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "
 export const DEFAULT_CONFIG = {
     semanticSearch: true,
     searchPaths: [],
-    registries: [{ url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" }],
+    registries: [
+        { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" },
+        { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh" },
+    ],
     output: {
         format: "json",
         detail: "brief",

package/dist/metadata.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetName, isRelevantAssetFile, TYPE_DIRS } from "./asset-spec";
+import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile } from "./asset-spec";
 import { isAssetType } from "./common";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
@@ -204,8 +204,6 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
     }
     return { entries };
 }
-/** Set of all known type directory names (e.g. "scripts", "skills", "agents") */
-const TYPE_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
 /**
  * Generate metadata for files using the matcher system instead of a fixed asset type.
  *
@@ -227,11 +225,9 @@ export function generateMetadataFlat(stashRoot, files) {
         // If the file lives under a known type directory, use that as the root
         // for canonical naming so names don't include the type prefix.
         // e.g. scripts/deploy.sh → "deploy.sh" not "scripts/deploy.sh"
-        const firstAncestor = ctx.ancestorDirs[0];
-        const effectiveRoot = firstAncestor && TYPE_DIR_NAMES.has(firstAncestor) ? path.join(stashRoot, firstAncestor) : stashRoot;
         const ext = path.extname(file).toLowerCase();
         const baseName = path.basename(file, ext);
-        const canonicalName = deriveCanonicalAssetName(assetType, effectiveRoot, file) ?? baseName;
+        const canonicalName = deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, file) ?? baseName;
         const entry = {
             name: canonicalName,
             type: assetType,

package/dist/stash-resolve.js

@@ -1,13 +1,25 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "./asset-spec";
 import { hasErrnoCode, isWithin } from "./common";
 import { NotFoundError, UsageError } from "./errors";
+import { runMatchers } from "./file-context";
+import { walkStashFlat } from "./walker";
 /**
  * Resolve an asset path from a stash directory, type, and name.
  */
 export function resolveAssetPath(stashDir, type, name) {
-    return resolveInTypeDir(stashDir, TYPE_DIRS[type], type, name);
+    try {
+        return resolveInTypeDir(stashDir, TYPE_DIRS[type], type, name);
+    }
+    catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
+        const fallback = resolveByCanonicalName(stashDir, type, name);
+        if (fallback)
+            return fallback;
+        throw error;
+    }
 }
 /**
  * Try to resolve an asset path within a specific type directory.
@@ -53,3 +65,21 @@ function readTypeRootStat(root, type, name) {
         throw error;
     }
 }
+function resolveByCanonicalName(stashDir, type, name) {
+    const normalizedName = name.replace(/\\/g, "/");
+    for (const ctx of walkStashFlat(stashDir)) {
+        const match = runMatchers(ctx);
+        if (!match || match.type !== type)
+            continue;
+        const canonicalName = deriveCanonicalAssetNameFromStashRoot(type, stashDir, ctx.absPath);
+        if (canonicalName !== normalizedName)
+            continue;
+        const realTarget = fs.realpathSync(ctx.absPath);
+        const resolvedRoot = fs.realpathSync(stashDir);
+        if (!isWithin(realTarget, resolvedRoot)) {
+            throw new UsageError("Ref resolves outside the stash root.");
+        }
+        return realTarget;
+    }
+    return undefined;
+}

package/dist/stash-search.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetName, TYPE_DIRS } from "./asset-spec";
+import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
 import { loadConfig } from "./config";
 import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, openDatabase, searchFts, searchVec, } from "./db";
 import { UsageError } from "./errors";
@@ -303,8 +303,7 @@ function substringSearch(query, searchType, limit, stashDir, sources, config) {
 // ── Hit building ────────────────────────────────────────────────────────────
 function buildDbHit(input) {
     const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
-    const typeRoot = path.join(entryStashDir, TYPE_DIRS[input.entry.type]);
-    const canonical = deriveCanonicalAssetName(input.entry.type, typeRoot, input.path);
+    const canonical = deriveCanonicalAssetNameFromStashRoot(input.entry.type, entryStashDir, input.path);
     // Guard against path traversal when the file is outside the expected type root
     // (e.g. source detection fell back to defaultStashDir for a file from another source)
     const refName = canonical && !canonical.startsWith("../") && !canonical.startsWith("..\\") ? canonical : input.entry.name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [