akm-cli 0.6.0-rc1 → 0.6.0

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

@@ -1,29 +1,97 @@
 Migration notes for akm v0.6.0
 
-This release is a clean break: the runtime "kit" / "source" concept is renamed to **stash**, the registry wire format moves from `kits[]` to `stashes[]` (schema v3), and the discovery keyword/topic is renamed from `akm-kit` to `akm-stash`.
+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.
+
+## Workflows: schema-driven indexing
+
+Workflows are now compiled into a validated `WorkflowDocument` JSON shape
+with line-anchored `SourceRef`s back into the source markdown, cached in a
+new `workflow_documents` table in `index.db`. `akm workflow next` reads from
+the cache instead of re-parsing markdown each step.
+
+A new `akm workflow validate <ref|path>` subcommand surfaces every error in
+one pass (without running a full reindex), formatted as `path:line — message`.
+
+`DB_VERSION` is bumped 8 → 9 to introduce the table; first run after upgrade
+drops + recreates all `index.db` tables (preserving `usage_events`). The next
+`akm index` rebuilds. Run-state in `workflow.db` is untouched.
+
+## Feedback expanded to any indexed ref
+
+`akm feedback <ref>` now accepts any indexed ref — `memory:`, `vault:`,
+`workflow:`, `wiki:` etc. The ref must be present in the local index.
+Vault feedback never echoes vault values. Telemetry persists both
+`entry_ref` and `entry_id` so signals survive a reindex, and feedback
+events now feed into utility recomputation alongside search/show signals.
+
+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.stashes[]` + `akm.lock` records.
-- `stashDir` is loaded as an implicit `primary: true` filesystem stash entry.
-- Stash type aliases `"context-hub"` and `"github"` normalize to `"git"` in memory.
+- `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"`.
 
-Manual actions required:
-- Replace `akm enable context-hub` / `akm disable context-hub` with
-  `akm add github:andrewyng/context-hub --name context-hub`.
-- Switch error-handling scripts from string-matching the `error` message
-  to comparing the new machine-readable `code` field.
-- Replace `--for-agent` with `--detail=agent` (old flag is retained as a
-  deprecated alias for one release cycle).
-- Replace `disableGlobalStashes: true` with `stashInheritance: "replace"`.
-
-Publishers:
-- The discovery keyword/topic was renamed from `akm-kit` to `akm-stash`.
-  Update your npm `keywords` and GitHub topics. Legacy keywords are no
-  longer honored — clean break, no transition window.
-
-Self-hosted registries:
-- The wire format `kits[]` is renamed to `stashes[]`. Schema is bumped
-  to v3 and `akm-cli >= 0.6.0` only parses v3.
-
-Full migration guide: https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.6.0-rc1",
+  "version": "0.6.0",
   "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": [

package/dist/errors.js

@@ -1,45 +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)
- *
- * Each error carries a machine-readable `code` field. Codes are stable
- * identifiers safe to consume from scripts and JSON output. Existing throw
- * sites without an explicit code receive a default code per error class so
- * older call sites continue to compile and behave unchanged.
- */
-/** Raised when configuration or environment is invalid or missing. */
-export class ConfigError extends Error {
-    code;
-    constructor(msg, code = "INVALID_CONFIG_FILE") {
-        super(msg);
-        this.name = "ConfigError";
-        this.code = code;
-        // 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 {
-    code;
-    constructor(msg, code = "INVALID_FLAG_VALUE") {
-        super(msg);
-        this.name = "UsageError";
-        this.code = code;
-        // 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 {
-    code;
-    constructor(msg, code = "ASSET_NOT_FOUND") {
-        super(msg);
-        this.name = "NotFoundError";
-        this.code = code;
-        // Fixes `instanceof` checks under ES5 transpilation targets.
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}

package/dist/llm.js

@@ -1,16 +0,0 @@
-/**
- * Backward-compatible facade for the LLM module.
- *
- * The implementation has been split into:
- * - `./llm-client`     — transport (chatCompletion, parseJsonResponse,
- *                       isLlmAvailable, probeLlmCapabilities, ChatMessage,
- *                       ChatCompletionOptions, stripJsonFences)
- * - `./metadata-enhance` — higher-level metadata enhancement workflow
- *                          (enhanceMetadata)
- *
- * New code should import from those modules directly. This re-export barrel
- * exists so existing call sites and tests that import from `./llm` keep
- * working without modification.
- */
-export * from "./llm-client";
-export { enhanceMetadata } from "./metadata-enhance";

package/dist/registry-factory.js

@@ -1,19 +0,0 @@
-/**
- * Registry provider factory map.
- *
- * Maps registry provider type identifiers (e.g. "static-index", "skills-sh")
- * to factory functions that create RegistryProvider instances.
- *
- * "Registry" here refers to the stash discovery registries (npm, GitHub, static
- * index files) — not to be confused with the stash provider factory map in
- * stash-provider-factory.ts or the installed-stash operations in installed-stashes.ts.
- */
-import { createProviderRegistry } from "./create-provider-registry";
-// ── Factory map ─────────────────────────────────────────────────────────────
-const registry = createProviderRegistry();
-export function registerProvider(type, factory) {
-    registry.register(type, factory);
-}
-export function resolveProviderFactory(type) {
-    return registry.resolve(type);
-}

package/dist/ripgrep.js

@@ -1,2 +0,0 @@
-export { ensureRg } from "./ripgrep-install";
-export { isRgAvailable, resolveRg } from "./ripgrep-resolve";

package/dist/stash-provider-factory.js

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

package/dist/stash-provider.js

@@ -1,3 +0,0 @@
-export function isSyncable(p) {
-    return p.kind === "syncable";
-}

package/dist/stash-providers/filesystem.js

@@ -1,71 +0,0 @@
-import { resolveStashDir } from "../common";
-import { loadConfig } from "../config";
-import { searchLocal } from "../db-search";
-import { ConfigError } from "../errors";
-import { resolveStashSources } from "../search-source";
-import { registerStashProvider } from "../stash-provider-factory";
-import { showLocal } from "../stash-show";
-import { detectStashRoot } from "./provider-utils";
-class FilesystemStashProvider {
-    type = "filesystem";
-    kind = "syncable";
-    name;
-    stashDir;
-    constructor(entry) {
-        this.stashDir = entry.path ?? resolveStashDir();
-        this.name = entry.name ?? this.stashDir;
-    }
-    async search(options) {
-        const config = loadConfig();
-        const sources = resolveStashSources(this.stashDir, config);
-        const result = await searchLocal({
-            query: options.query.toLowerCase(),
-            searchType: options.type ?? "any",
-            limit: options.limit,
-            stashDir: this.stashDir,
-            sources,
-            config,
-        });
-        return {
-            hits: result.hits,
-            warnings: result.warnings,
-            embedMs: result.embedMs,
-            rankMs: result.rankMs,
-        };
-    }
-    async show(ref, view) {
-        return showLocal({ ref, view });
-    }
-    canShow(ref) {
-        return !ref.includes("://");
-    }
-    /** No-op: a filesystem stash already lives on disk. */
-    async sync(config, options) {
-        if (!config.path) {
-            throw new ConfigError("filesystem stash entry must include a `path`");
-        }
-        const stashRoot = detectStashRoot(config.path);
-        const syncedAt = (options?.now ?? new Date()).toISOString();
-        return {
-            id: stashRoot,
-            source: "local",
-            ref: stashRoot,
-            artifactUrl: stashRoot,
-            contentDir: stashRoot,
-            cacheDir: stashRoot,
-            extractedDir: stashRoot,
-            syncedAt,
-        };
-    }
-    getContentDir(config) {
-        if (!config.path) {
-            throw new ConfigError("filesystem stash entry must include a `path`");
-        }
-        return config.path;
-    }
-    async remove(_config) {
-        // Filesystem stashes are user-managed; never delete the source on `akm remove`.
-    }
-}
-// ── Self-register ───────────────────────────────────────────────────────────
-registerStashProvider("filesystem", (config) => new FilesystemStashProvider(config));