akm-cli 0.5.0 → 0.6.0-rc2

package/docs/README.md

@@ -0,0 +1,30 @@
+# Documentation
+
+## Getting Started
+
+- [Concepts](concepts.md) -- Stashes, registries, asset types, and refs
+- [Getting Started](getting-started.md) -- Quick setup guide
+- [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated install for agents
+- [Stash Maker's Guide](stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
+
+## Upgrading
+
+- [v0.5 → v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
+
+## Reference
+
+- [CLI](cli.md) -- All `akm` commands and flags
+- [Registry](registry.md) -- Registries, search, hosting, and managing sources
+- [Configuration](configuration.md) -- Providers, settings, and Ollama setup
+- [Filesystem](technical/filesystem.md) -- Directory layout and `.stash.json` schema
+
+## Internals
+
+- [Search](technical/search.md) -- Hybrid search architecture and scoring
+- [Indexing](technical/indexing.md) -- How the search index is built
+- [Classification](technical/classification.md) -- Matcher and renderer behavior
+- [Show Response](technical/show-response.md) -- `akm show` output fields by asset type
+- [Testing Workflow](technical/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation
+- [Ref Format](technical/ref.md) -- Wire format for asset references
+- [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
+- [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints

package/docs/migration/release-notes/0.0.13.md

@@ -0,0 +1,4 @@
+Migration notes for akm v0.0.13
+
+- Initial public release.
+- No migration steps are required for earlier akm versions.

package/docs/migration/release-notes/0.1.0.md

@@ -0,0 +1,6 @@
+Migration notes for akm v0.1.0
+
+- The package and project were rebranded from Agent-i-Kit to akm.
+- Update package references from `agent-i-kit` to `akm-cli`.
+- Update config, registry, plugin, path, and environment-variable references from `agent-i-kit` / `AGENT_I_KIT_*` to `akm` / `AKM_*`.
+- The `tool` asset type and `submit` command were removed.

package/docs/migration/release-notes/0.2.0.md

@@ -0,0 +1,6 @@
+Migration notes for akm v0.2.0
+
+- Asset refs are user-facing `type:name` values; do not rely on URI-style refs.
+- The old fixed asset-type union was replaced by an extensible asset type system.
+- `tool` assets were removed; use `script` assets instead.
+- Config and docs should treat remote provider scores and local scores as part of one shared search pipeline.

package/docs/migration/release-notes/0.3.0.md

@@ -0,0 +1,5 @@
+Migration notes for akm v0.3.0
+
+- The old `stash` and `kit` command groups were folded into the top-level CLI.
+- Use `akm add`, `akm list`, and `akm remove` instead of the older split command surfaces.
+- Documentation and examples from older releases should be updated to the unified source model.

package/docs/migration/release-notes/0.5.0.md

@@ -0,0 +1,6 @@
+Migration notes for akm v0.5.0
+
+- New top-level surfaces: `akm wiki …`, `akm workflow …`, `akm vault …`, and `akm save`.
+- If you tried the unreleased single-wiki LLM prototype, move to the new `akm wiki …` workflow.
+- Removed from the prototype surface: `akm lint`, `akm import --llm`, `akm import --dry-run`, `knowledge.pageKinds`, and the old ingest/lint LLM prompts.
+- Existing raw wiki-like content should be moved into `wikis/<name>/raw/` and then managed with the new wiki commands.

package/docs/migration/release-notes/0.6.0.md

@@ -0,0 +1,75 @@
+Migration notes for akm v0.6.0
+
+This release ships the v1 architecture refactor on top of the earlier 0.6
+terminology cut (`kit` → `stash` in the registry wire format). The CLI
+command surface is unchanged. Most users have nothing to do.
+
+Locked v1 decisions:
+- `writable` defaults to `true` on `filesystem`, `false` on `git` /
+  `website` / `npm`.
+- Registry results are off by default in `akm search`; pass
+  `--include-registry` (or `--source registry|both`) to include them.
+- Write target resolves as: `--target` flag → `defaultWriteTarget` config
+  key → `stashDir` (working stash) → `ConfigError`.
+- `writable: true` on `website` / `npm` is rejected at config load.
+
+Manual actions required:
+- If your config contains an `openviking` source, remove it. akm exits at
+  load with `ConfigError` and points to `akm config sources remove <name>`.
+  API-backed sources will return as a separate `QuerySource` tier post-v1.
+- If your config sets `writable: true` on a `website` or `npm` source,
+  drop the flag or re-add the path as a `filesystem` source.
+- If you previously ran `akm enable context-hub` / `akm disable
+  context-hub`, those toggles are gone. Add Context Hub as a regular git
+  source with `akm add github:andrewyng/context-hub`, or list it as a kit
+  entry in your registry.
+
+Automatic (no action required):
+- Config key `stashes[]` is loaded as `sources[]` with one deprecation
+  warning. The new key is persisted on the next `akm config` write.
+- `stash.lock` is renamed to `akm.lock` on startup.
+- `config.installed[]` entries are mapped to `config.sources[]` plus
+  `akm.lock` records.
+- `stashDir` is loaded as an implicit `primary: true` filesystem source.
+- Stash type aliases `"context-hub"` and `"github"` normalize to `"git"`.
+
+What changed under the hood (no user impact):
+- `SourceProvider` interface simplified to `{ name, kind, init, path,
+  sync? }`. Plugin authors should re-read the v1 spec.
+- Search and show consult the unified FTS5 index and read files from
+  disk; the per-provider fan-out is gone.
+- Single write helper (`writeAssetToSource`) handles filesystem and git
+  destinations.
+- Error classes own their `hint()` text. Hints now print to stderr inline
+  without `--verbose`.
+- Registry providers (`static-index`, `skills-sh`) loop through a uniform
+  interface; the Context Hub special case was deleted.
+- `src/` reorganized into purpose-named subdirectories (`commands/`,
+  `core/`, `indexer/`, `output/`, `registry/`, `setup/`, `sources/`,
+  `wiki/`, `workflows/`). akm has no public API, so external consumers
+  are unaffected.
+- Removed legacy re-export shims: `src/llm.ts`, `src/registry-provider.ts`,
+  `src/ripgrep.ts`.
+
+Earlier-in-cycle terminology cut (still applies):
+- The registry wire format `kits[]` is renamed to `stashes[]` with schema
+  bumped to v3. `akm-cli >= 0.6.0` only parses v3 indexes.
+- npm packages and GitHub repos are discovered via the `akm-stash`
+  keyword/topic only. `akm-kit` and `agentikit` are no longer honored.
+- Internal types: `RegistryKitEntry` → `RegistryStashEntry`,
+  `InstalledKitEntry` → `InstalledStashEntry`,
+  `KitInstallStatus` → `StashInstallStatus`, `KitSource` → `StashSource`.
+- Documentation: `docs/kit-makers.md` → `docs/stash-makers.md`.
+
+CLI command surface (unchanged in 0.6.0):
+add | remove | list | update | search | show | clone | index | setup |
+remember | import | feedback | registry * | info | curate | workflow |
+vault | wiki | enable | disable | completions | upgrade | save | help |
+hints
+
+Full migration guides:
+- https://github.com/itlackey/akm/blob/main/docs/migration/v1.md (v1
+  architecture refactor — read this first if you are coming from 0.5.x or
+  an earlier 0.6 pre-release)
+- https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md
+  (terminology cut, registry schema v3, publisher changes)

package/docs/migration/release-notes/README.md

@@ -0,0 +1,21 @@
+# Release-notes corpus for `akm help migrate`
+
+This directory holds one `.md` file per release. Each file is the short,
+focused migration note that `akm help migrate <version>` prints to the
+terminal. The longform cross-release guides (e.g. `v0.5-to-v0.6.md`)
+live one level up in `docs/migration/`.
+
+## Adding notes for a new release
+
+1. Create `<version>.md` in this directory (e.g. `0.7.0.md`).
+2. Write plain text — the content is printed verbatim. Start the body
+   with a line like `Migration notes for akm v0.7.0`, then list the
+   automatic migrations, manual actions, publisher changes, etc.
+3. The file ships with the published package via `package.json` →
+   `files[]` and is resolved at runtime from either `src/` or `dist/`,
+   so no code change is required.
+4. Link to the longform guide in the last paragraph if one exists.
+
+Keep each note self-contained: it should tell a user everything they
+need to upgrade without requiring them to open a browser (the longform
+guide link is the last resort, not the first).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.5.0",
+  "version": "0.6.0-rc2",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -35,7 +35,8 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/migration/release-notes"
   ],
   "bin": {
     "akm": "dist/cli.js"

package/dist/embedder.js

@@ -1,351 +0,0 @@
-import path from "node:path";
-import { fetchWithTimeout, isHttpUrl } from "./common";
-import { getCacheDir } from "./paths";
-import { warn } from "./warn";
-// ── Default local model ─────────────────────────────────────────────────────
-/**
- * Default local transformer model for embeddings.
- * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
- * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
- */
-export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
-/**
- * Return the local model name that will be used for embedding.
- * When `overrideModel` is provided it takes precedence; otherwise
- * the default model is returned.
- */
-function getLocalModelName(overrideModel) {
-    return overrideModel || DEFAULT_LOCAL_MODEL;
-}
-const LOCAL_EMBEDDER_DTYPE = "fp32";
-const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
-// Cache the promise itself (not the resolved result) so concurrent calls share
-// the same initialisation work and never download the model twice.
-// The cache is keyed by model name so switching models gets a fresh pipeline.
-let localEmbedderPromise;
-let localEmbedderModelName;
-async function getLocalEmbedder(modelName) {
-    const resolvedModel = getLocalModelName(modelName);
-    // If the cached pipeline was created for a different model, discard it.
-    if (localEmbedderPromise && localEmbedderModelName !== resolvedModel) {
-        localEmbedderPromise = undefined;
-        localEmbedderModelName = undefined;
-    }
-    if (!localEmbedderPromise) {
-        localEmbedderModelName = resolvedModel;
-        localEmbedderPromise = (async () => {
-            // Ensure HuggingFace model cache lives in a stable location outside
-            // node_modules so it survives package reinstalls.
-            if (!process.env.HF_HOME) {
-                process.env.HF_HOME = path.join(getCacheDir(), "models");
-            }
-            let pipeline;
-            try {
-                const mod = await import("@huggingface/transformers");
-                pipeline = mod.pipeline;
-            }
-            catch (importError) {
-                const msg = importError instanceof Error ? importError.message : String(importError);
-                if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
-                    throw new Error("Semantic search requires @huggingface/transformers. Install it with: bun add @huggingface/transformers");
-                }
-                throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
-            }
-            const pipelineFn = pipeline;
-            return createLocalPipeline(pipelineFn, resolvedModel);
-        })();
-        // HI-13: Clear the cached promise on failure so the next call retries
-        // instead of permanently rejecting every subsequent call with the same error.
-        localEmbedderPromise.catch(() => {
-            localEmbedderPromise = undefined;
-            localEmbedderModelName = undefined;
-        });
-    }
-    return localEmbedderPromise;
-}
-async function createLocalPipeline(pipelineFn, modelName) {
-    try {
-        return await pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_DTYPE });
-    }
-    catch (error) {
-        if (!shouldRetryWithoutExplicitDtype(error)) {
-            throw error;
-        }
-        warn('Local embedding model "%s" rejected explicit dtype "%s"; retrying with explicit fallback dtype "%s".', modelName, LOCAL_EMBEDDER_DTYPE, LOCAL_EMBEDDER_FALLBACK_DTYPE);
-        return pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_FALLBACK_DTYPE });
-    }
-}
-function shouldRetryWithoutExplicitDtype(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return /dtype|fp32|precision|quant/i.test(message);
-}
-export function resetLocalEmbedder() {
-    localEmbedderPromise = undefined;
-    localEmbedderModelName = undefined;
-}
-async function embedLocal(text, modelName) {
-    const model = await getLocalEmbedder(modelName);
-    const result = await model(text, { pooling: "mean", normalize: true });
-    return Array.from(result.data);
-}
-// ── Vector normalization ─────────────────────────────────────────────────────
-/**
- * L2-normalize a vector to unit length.
- * Required for remote embeddings because the scoring pipeline's L2-to-cosine
- * conversion formula (1 - distance^2/2) is only correct for unit vectors.
- * The local embedder already normalizes via `normalize: true`.
- */
-function l2Normalize(vec) {
-    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
-    if (norm === 0)
-        return vec;
-    return vec.map((v) => v / norm);
-}
-// ── OpenAI-compatible remote embedder ───────────────────────────────────────
-function normalizeEmbeddingEndpoint(endpoint) {
-    let parsed;
-    try {
-        parsed = new URL(endpoint);
-    }
-    catch {
-        return endpoint;
-    }
-    const normalizedPath = parsed.pathname.replace(/\/+$/, "");
-    if (normalizedPath.endsWith("/embeddings")) {
-        return parsed.toString();
-    }
-    parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
-    return parsed.toString();
-}
-function embeddingEndpointPathHint(endpoint) {
-    const normalizedEndpoint = normalizeEmbeddingEndpoint(endpoint);
-    if (normalizedEndpoint !== endpoint) {
-        return ` Check that your endpoint includes the full embeddings path (for example "${normalizedEndpoint}", not just "${endpoint}").`;
-    }
-    return "";
-}
-async function embedRemote(text, config) {
-    const headers = { "Content-Type": "application/json" };
-    if (config.apiKey) {
-        headers.Authorization = `Bearer ${config.apiKey}`;
-    }
-    const body = {
-        input: text,
-        model: config.model,
-    };
-    if (config.dimension) {
-        body.dimensions = config.dimension;
-    }
-    const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(config.endpoint), {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-    });
-    if (!response.ok) {
-        const body = await response.text().catch(() => "");
-        throw new Error(`Embedding request failed (${response.status}): ${body}`);
-    }
-    const json = (await response.json());
-    if (!json.data?.[0]?.embedding) {
-        throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(config.endpoint)}`);
-    }
-    return l2Normalize(json.data[0].embedding);
-}
-// ── Helpers ──────────────────────────────────────────────────────────────────
-/** Check whether an EmbeddingConnectionConfig has a valid remote endpoint. */
-function hasRemoteEndpoint(config) {
-    return isHttpUrl(config.endpoint);
-}
-// ── LRU embedding cache ─────────────────────────────────────────────────────
-// Caches query embeddings to avoid redundant computation for repeated queries.
-// Uses a simple Map with LRU eviction (delete + re-insert to move to end).
-const EMBED_CACHE_MAX = 100;
-const embedCache = new Map();
-/**
- * Build a cache key from query text and optional config.
- * Different endpoints/models should not share cached embeddings.
- * apiKey deliberately excluded: same endpoint+model produce identical embeddings regardless of auth
- */
-function embedCacheKey(text, config) {
-    if (!config)
-        return `local::${text}`;
-    const endpoint = config.endpoint || "";
-    const model = config.model || config.localModel || "";
-    return `${endpoint}:${model}:${text}`;
-}
-/**
- * Clear the embedding cache. Call when the embedding model changes
- * or when you want to force fresh embeddings.
- */
-export function clearEmbeddingCache() {
-    embedCache.clear();
-}
-// ── Public API ──────────────────────────────────────────────────────────────
-/**
- * Generate an embedding for the given text.
- * If embeddingConfig has a remote endpoint, uses the configured OpenAI-compatible endpoint.
- * Otherwise falls back to local @huggingface/transformers using the model from
- * `embeddingConfig.localModel` or `DEFAULT_LOCAL_MODEL`.
- *
- * Results are cached in an LRU cache (max ~100 entries) keyed by query text
- * and embedding config. Repeated identical queries return the cached vector.
- */
-export async function embed(text, embeddingConfig) {
-    const key = embedCacheKey(text, embeddingConfig);
-    // Check cache first
-    const cached = embedCache.get(key);
-    if (cached) {
-        // Move to end (most recently used) for LRU ordering
-        embedCache.delete(key);
-        embedCache.set(key, cached);
-        return cached;
-    }
-    // Compute the embedding
-    const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
-        ? await embedRemote(text, embeddingConfig)
-        : await embedLocal(text, embeddingConfig?.localModel);
-    // Evict oldest entry if at capacity
-    if (embedCache.size >= EMBED_CACHE_MAX) {
-        const oldest = embedCache.keys().next().value;
-        if (oldest !== undefined) {
-            embedCache.delete(oldest);
-        }
-    }
-    embedCache.set(key, result);
-    return result;
-}
-// ── Batch embedding ─────────────────────────────────────────────────────────
-/**
- * Generate embeddings for multiple texts in batch.
- * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for local transformer pipeline.
- */
-export async function embedBatch(texts, embeddingConfig) {
-    if (texts.length === 0)
-        return [];
-    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
-        return embedRemoteBatch(texts, embeddingConfig);
-    }
-    // Local transformer: process sequentially (pipeline handles one at a time)
-    const localModel = embeddingConfig?.localModel;
-    const results = [];
-    for (const text of texts) {
-        results.push(await embedLocal(text, localModel));
-    }
-    return results;
-}
-async function embedRemoteBatch(texts, config) {
-    const BATCH_SIZE = 100;
-    const results = [];
-    const headers = { "Content-Type": "application/json" };
-    if (config.apiKey) {
-        headers.Authorization = `Bearer ${config.apiKey}`;
-    }
-    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
-        const batch = texts.slice(i, i + BATCH_SIZE);
-        const body = {
-            input: batch,
-            model: config.model,
-        };
-        if (config.dimension) {
-            body.dimensions = config.dimension;
-        }
-        const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(config.endpoint), {
-            method: "POST",
-            headers,
-            body: JSON.stringify(body),
-        });
-        if (!response.ok) {
-            const respBody = await response.text().catch(() => "");
-            throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
-        }
-        const json = (await response.json());
-        if (!json.data || json.data.length !== batch.length) {
-            throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(config.endpoint)}`);
-        }
-        // Sort by index to guarantee correct order (OpenAI API doesn't guarantee order)
-        const sorted = [...json.data].sort((a, b) => a.index - b.index);
-        for (const [idx, d] of sorted.entries()) {
-            if (!Array.isArray(d.embedding)) {
-                throw new Error(`Unexpected embedding at batch index ${idx}: missing or invalid`);
-            }
-            results.push(l2Normalize(d.embedding));
-        }
-    }
-    return results;
-}
-// ── Similarity ──────────────────────────────────────────────────────────────
-export function cosineSimilarity(a, b) {
-    if (a.length !== b.length) {
-        // MD-4: Return 0 on dimension mismatch rather than silently computing on a
-        // truncated view, which would produce meaningless similarity scores.
-        warn("cosineSimilarity: vector dimension mismatch (%d vs %d) — re-index recommended", a.length, b.length);
-        return 0;
-    }
-    const len = a.length;
-    if (len === 0)
-        return 0;
-    let dot = 0, magA = 0, magB = 0;
-    for (let i = 0; i < len; i++) {
-        dot += a[i] * b[i];
-        magA += a[i] * a[i];
-        magB += b[i] * b[i];
-    }
-    const denom = Math.sqrt(magA) * Math.sqrt(magB);
-    return denom === 0 ? 0 : dot / denom;
-}
-// ── Availability check ──────────────────────────────────────────────────────
-/**
- * Check whether the `@huggingface/transformers` package can be imported.
- * Returns `true` if it can, `false` otherwise.
- */
-export async function isTransformersAvailable() {
-    try {
-        await import("@huggingface/transformers");
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Check whether embedding is available with a detailed reason on failure.
- */
-export async function checkEmbeddingAvailability(embeddingConfig) {
-    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
-        try {
-            await embedRemote("test", embeddingConfig);
-            return { available: true };
-        }
-        catch (err) {
-            return {
-                available: false,
-                reason: "remote-unreachable",
-                message: err instanceof Error ? err.message : String(err),
-            };
-        }
-    }
-    // Check if the package is importable before attempting the model download.
-    if (!(await isTransformersAvailable())) {
-        return {
-            available: false,
-            reason: "missing-package",
-            message: "@huggingface/transformers is not installed.",
-        };
-    }
-    try {
-        await getLocalEmbedder(embeddingConfig?.localModel);
-        return { available: true };
-    }
-    catch (err) {
-        return {
-            available: false,
-            reason: "model-download-failed",
-            message: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-export async function isEmbeddingAvailable(embeddingConfig) {
-    const result = await checkEmbeddingAvailability(embeddingConfig);
-    return result.available;
-}

package/dist/errors.js

@@ -1,34 +0,0 @@
-/**
- * Typed error classes for structured exit code classification.
- *
- * - ConfigError  -> exit 78  (configuration / environment problems)
- * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
- * - NotFoundError -> exit 1  (requested resource missing)
- */
-/** Raised when configuration or environment is invalid or missing. */
-export class ConfigError extends Error {
-    constructor(msg) {
-        super(msg);
-        this.name = "ConfigError";
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-/** Raised when the user supplies invalid arguments or input. */
-export class UsageError extends Error {
-    constructor(msg) {
-        super(msg);
-        this.name = "UsageError";
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-/** Raised when a requested resource (asset, entry, file) is not found. */
-export class NotFoundError extends Error {
-    constructor(msg) {
-        super(msg);
-        this.name = "NotFoundError";
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}