akm-cli 0.4.1 → 0.5.0-rc2

package/CHANGELOG.md

@@ -0,0 +1,232 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-04-22
+
+### Added
+
+- **Multi-wiki support** (#119, #121): new `wiki` asset type with nine CLI verbs under `akm wiki …` (`create`, `list`, `show`, `remove`, `pages`, `search`, `stash`, `lint`, `ingest`). Each wiki lives at `<stashDir>/wikis/<name>/` with `schema.md`, `index.md`, `log.md`, `raw/`, and agent-authored pages. Wiki pages are first-class in stash-wide `akm search`. `akm index` regenerates each wiki's `index.md` as a side effect. See `docs/wikis.md` for the full guide. Design principle: **akm surfaces, the agent writes** — no LLM calls, no network access; akm owns only operations with invariants an agent can't reliably enforce (lifecycle, raw-slug uniqueness, structural lint, index regeneration, workflow discovery).
+- **Workflow asset type** (#118): new `workflow` type with `akm workflow create <name>` and `akm workflow next <ref>` for authoring and stepping through multi-step workflows stored in the stash
+- **Vault asset type** (#117): new `vault` type backed by `.env` files; `akm vault` subcommand with `list`, `show`, `load` (emits a `source` snippet for the current shell); values never appear in structured output
+- **`--trust` flag for installs**: `akm add <source> --trust` performs a one-off trusted install, bypassing the install audit for that source
+- **Writable git stash + `akm save`** (#114): `akm add … --writable` opts a remote git-backed stash into push-on-save; `akm save [name] [-m message]` commits (and pushes when writable + remote is set); default stash is auto-initialized as a git repo; git stash provider now uses `git clone` instead of HTTP tarball download
+
+### Removed (breaking)
+
+- The unreleased single-wiki LLM POC: removes `akm lint` command, `akm import --llm` / `--dry-run` flags, `knowledge.pageKinds` config, and the `ingestKnowledgeSource` / `lintKnowledge` LLM prompts. Users of the POC should migrate to the new `akm wiki …` surface; raw content can be manually moved to `wikis/<name>/raw/`.
+
+## [0.4.1] - 2026-04-21
+
+### Added
+
+- **`akm enable` / `akm disable`** (#108): toggle optional components (`skills.sh`, `context-hub`) on/off without manually editing config
+- **`akm remember` and `akm import` commands** (#110): capture in-session knowledge directly from the CLI; `akm remember` records a memory to the default stash (supports stdin); `akm import` ingests a file or stdin as a knowledge asset
+- **Karpathy-style wiki workflow in knowledge assets** (#113): `akm show knowledge:<doc>` now surfaces an `ingest` workflow for knowledge documents; `--dry-run` flag added; `pageKind` taxonomy made extensible
+- Documentation: expanded `agent-install.md`, added `info` and `feedback` command docs, global flags reference (#106)
+
+### Fixed
+
+- Remote embedding endpoint URL normalization — trailing slashes and path segments now handled correctly (#112)
+- Reduced fallback capture-name collisions in `akm remember`
+
+## [0.4.0] - 2026-04-19
+
+### Added
+
+- **Install security audit**: new pre-install scanner inspects kit contents for dangerous patterns and executable scripts before install; configurable via `config` CLI
+- **Project-level config stash merging**: `.akm.json` in a project directory merges its stash/registry entries with user config during CLI runs
+- **Disable inherited project stashes**: project config can disable stashes inherited from parent/user scopes
+- **`akm curate` command**: new subcommand for curating assets from the stash (initial skeleton)
+
+### Fixed
+
+- Index nested agent markdown files as agents so `akm search agent:...` finds them
+- `install-audit` now reads at most `MAX_SCANNED_FILE_BYTES` per file using `Buffer.alloc`, with the file descriptor always closed via `try/finally`, and corrects the `scannedBytes` counter
+
+## [0.3.1] - 2026-04-01
+
+### Added
+
+- **Website stash provider**: add a URL directly as a stash source with `akm stash add <url>`; crawls the site and indexes pages as knowledge assets
+- Website provider options: `--max-pages` and `--depth` flags to bound crawling
+
+### Fixed
+
+- Relaxed HTTP warnings for localhost website sources
+- Addressed review feedback around website provider routing and security heuristics
+
+## [0.3.0] - 2026-03-30
+
+### Added
+
+- Regression tests for vector/semantic search readiness, install, and setup flows
+- `CONTRIBUTING.md` and "Why akm" section in documentation
+- Three draft SEO blog posts
+
+### Changed
+
+- **Unified source model**: replaced the `kit` vs `stash` split with a single source concept; `akm add` works for all source types
+- Removed `stash` and `kit` subcommand groups; their behaviors fold into the top-level CLI (`akm list`, `akm add`, etc.)
+- Refactored semantic search readiness tracking for clearer state transitions
+- Aligned documentation voice and updated older posts for the current CLI surface
+
+### Fixed
+
+- Embedding fingerprint is purged on model change and `usage_events` are re-linked correctly
+- Local embedder dtype selection
+- Release validation workflow
+- Prereleases (versions with suffixes) are marked as such on GitHub releases and published to npm with `--tag next`
+
+## [0.2.2] - 2026-03-28
+
+### Fixed
+
+- Binary install detection in `akm upgrade` self-update; centralized `AKM_VERSION` declaration with binary detection tests
+
+## [0.2.1] - 2026-03-25
+
+### Added
+
+- Docker-based install tests covering multiple OS configurations (skipped in CI)
+- Detailed error reporting in embedding availability checks
+- Actionable guidance when `sqlite-vec` fails to open the DB
+
+### Changed
+
+- **Rename**: project renamed from `Agent-i-Kit` to `akm` across docs and links
+- Local embeddings switched to `@huggingface/transformers`
+- `@huggingface/transformers` moved to `optionalDependencies`, then promoted to a runtime dependency
+- Improved semantic search setup and index UX
+
+## [0.2.0] - 2026-03-18
+
+### Added
+
+- **Extensible asset type system**: `AkmAssetType` (formerly `AgentIKitAssetType`) is now `string` instead of a fixed union; new types can be registered at runtime via `registerAssetType()`
+- **Memory asset type**: built-in `memory` type stored in `memories/`, with `memory-md` renderer and directory/parent-dir-hint matchers
+- **OpenViking stash provider**: `openviking` provider type for searching OpenViking servers via REST; add with `akm stash add <url> --provider openviking`
+- **Remote show for `viking://` URIs**: `akm show viking://resources/my-doc` fetches content directly from an OpenViking server (returns `editable: false`)
+- **`--options` flag** for `akm registry add` and `akm stash add`: pass provider-specific JSON config (e.g., `--options '{"apiKey":"key"}'`)
+- **`akm registry build-index` command**: generates a v2 registry index JSON from npm/GitHub discovery with `--out`, `--manual`, `--npmRegistry`, `--githubApi`, and `--format` flags
+- Exact-name match, type-relevance, and alias boosts in the search scoring pipeline
+- Ranking regression tests with a synthetic fixture stash and a 41-case benchmark suite (MRR / Recall@5)
+- `estimatedTokens` on context-hub provider search results and in `--for-agent` output
+- Architecture docs and test fixture for OpenViking manual testing (`tests/fixtures/openviking/`)
+
+### Changed
+
+- Unified context-hub indexing and fair provider scoring: local FTS scores are preserved everywhere and remote provider scores compete on equal footing
+- Replaced RRF with normalized BM25 scoring across all merge paths
+- EMA utility decay is now time-proportional instead of tied to index frequency
+- Replaced the `(Bun as any).YAML` hack with a proper `yaml` package dependency
+- YAML output format fixed; local registry refs now use a `file:` prefix
+
+### Removed
+
+- `manifest` subcommand (adds no value over `search`)
+- URI schemes (`viking://`, `context-hub://`) from user-facing refs — assets are addressed as `type:name`; sources use URLs
+- Stale audit/ergonomics markdown from the repo
+
+### Fixed
+
+- `skills.sh` install refs now produce valid `akm add` commands (#82)
+- Prevented `akm remove` and `akm update --force` from deleting user-owned local source directories installed via path refs
+- `usage_events` reverted to `DELETE` on full reindex
+
+## [0.1.0] - 2026-03-10
+
+Major internal overhaul and rebrand. This release simplifies the asset model,
+cleans up the CLI surface, and renames the package from `agent-i-kit` to `akm-cli`.
+
+### Added
+
+- `--verbose` flag on `search` for detailed scoring output
+- ExecHints system (`run`, `cwd`, `setup`) for script assets, replacing the old tool-runner
+- New environment variable overrides: `AKM_CONFIG_DIR`, `AKM_CACHE_DIR`, `AKM_STASH_DIR`
+- CI workflow running lint, type-check, and tests on every push/PR
+- Biome linter and formatter configuration
+- README badges (npm version, CI status, license)
+
+### Changed
+
+- **Rebrand**: npm package `agent-i-kit` renamed to `akm-cli`; binary remains `akm`
+- **Rebrand**: config field `"agent-i-kit"` renamed to `"akm"` in `package.json`
+- **Rebrand**: plugin `agent-i-kit-opencode` renamed to `akm-opencode`
+- **Rebrand**: registry `agent-i-kit-registry` renamed to `akm-registry`
+- **Rebrand**: default paths changed (`~/agent-i-kit` to `~/akm`, `~/.config/agent-i-kit` to `~/.config/akm`)
+- **Rebrand**: environment variables `AGENT_I_KIT_*` renamed to `AKM_*`
+- Removed `tool` asset type entirely; `script` is the only script-like type
+- `.stash.json` field renames: `intents` to `searchHints`, `entry` to `filename`; removed `generated` boolean
+- `show` command: `--view` flag replaced with positional syntax (`akm show <ref> toc`)
+- Collapsed `AssetTypeHandler` handlers into a unified renderer pipeline
+- Dropped provider presets (raw JSON config only)
+- Pinned `sqlite-vec` to exact version `0.1.7-alpha.2` (removed caret range)
+- Replaced `(Bun as any).YAML` cast with proper type guard in CLI
+- Version now injected at compile time via `--define AKM_VERSION` with safe runtime fallback
+
+### Removed
+
+- `submit` command
+- Provider presets (configure providers with raw JSON)
+- `generated` boolean from `.stash.json`
+
+### Fixed
+
+- CLI crash on macOS when running as compiled binary (`package.json` not embedded)
+- Cleaned up search output formatting
+
+## [0.0.17] - 2026-03-12
+
+Registry refactor and documentation overhaul. This release introduces a
+first-class registry management CLI, modernizes the config schema, and
+rewrites all documentation against the final asset model.
+
+### Added
+
+- `akm registry` subcommand group with `list`, `add`, `remove`, and `search` subcommands
+- `akm registry search --assets` flag for asset-level search against v2 registry indexes
+- `registries` config field (`RegistryConfigEntry[]`) with `url`, `name`, and `enabled` properties
+- Registry Index v2 schema with optional `assets` array on kit entries for asset-level discovery
+- Official registry pre-configured by default in new installations
+- Type names: `KitSource`, `InstalledKitEntry`, `KitInstallResult`, `KitInstallStatus`, `InstalledKitListEntry`
+
+### Changed
+
+- Config: `installed` is now a top-level field (`config.installed`) instead of nested under `config.registry.installed`
+- Config: registry URLs configured via `registries` array instead of `registryUrls`
+- Documentation: complete rewrite of concepts, registry, CLI reference, README, and all technical docs
+- Documentation: added "Mental Model" (registries --> kits --> stash --> assets) to concepts
+- Documentation: added asset classification taxonomy description
+- Documentation: merged ref format documentation into concepts (removed "opaque handle" framing)
+- Documentation: revised apt analogy in core principles to map registries, kits, stash, and assets
+- Documentation: added `akm registry` subcommand group to CLI reference
+- Documentation: added registry hosting and v2 index format guides
+
+### Removed
+
+- `tool` asset type (fully removed across all documentation and code)
+- `registryUrls` config field (replaced by `registries`)
+- `config.registry.installed` nesting (replaced by `config.installed`)
+- All `tools/` directory references from documentation
+
+## [0.0.13] - 2026-03-09
+
+Initial public release of Agent-i-Kit (`akm` CLI).
+
+### Added
+
+- CLI tool (`akm`) for searching, showing, and running Agent-i-Kit stash assets
+- Hybrid search with FTS5 full-text and optional vector similarity scoring
+- Registry support for discovering, installing, and updating community kits
+- Multiple install sources: npm, GitHub, git URLs, and local directories
+- Self-update via `akm upgrade`
+- Multiple output formats: plain text, YAML, and JSON (`--json`)
+- Knowledge asset navigation with TOC, section, and line-range views
+- `akm clone` to fork installed assets into your working stash
+- Configuration system with embedding and LLM provider management
+- Standalone binary distribution (no runtime dependencies)

package/dist/asset-registry.js

@@ -10,6 +10,7 @@
  * `local-search.ts` import from, eliminating the import-order dependency
  * entirely.
  */
+import { buildWorkflowAction } from "./renderers";
 /** Map asset types to their primary renderer names. */
 export const TYPE_TO_RENDERER = {
     script: "script-source",
@@ -18,6 +19,9 @@ export const TYPE_TO_RENDERER = {
     agent: "agent-md",
     knowledge: "knowledge-md",
     memory: "memory-md",
+    workflow: "workflow-md",
+    vault: "vault-env",
+    wiki: "wiki-md",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -27,6 +31,9 @@ export const ACTION_BUILDERS = {
     agent: (ref) => `akm show ${ref} -> dispatch with full prompt`,
     knowledge: (ref) => `akm show ${ref} -> read reference material`,
     memory: (ref) => `akm show ${ref} -> recall context`,
+    workflow: (ref) => buildWorkflowAction(ref),
+    vault: (ref) => `akm vault list ${ref} -> see key names; eval "$(akm vault load ${ref})" -> load values into the current shell (values never echoed)`,
+    wiki: (ref) => `akm show ${ref} -> read the wiki page`,
 };
 /**
  * Register a type-to-renderer mapping.

package/dist/asset-spec.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
 import { toPosix } from "./common";
+import { buildWorkflowAction } from "./renderers";
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -53,8 +54,42 @@ const ASSET_SPECS_INTERNAL = {
     command: { stashDir: "commands", ...markdownSpec },
     agent: { stashDir: "agents", ...markdownSpec },
     knowledge: { stashDir: "knowledge", ...markdownSpec },
+    workflow: {
+        stashDir: "workflows",
+        ...markdownSpec,
+        rendererName: "workflow-md",
+        actionBuilder: (ref) => buildWorkflowAction(ref),
+    },
     script: { stashDir: "scripts", ...scriptSpec },
     memory: { stashDir: "memories", ...markdownSpec },
+    vault: {
+        stashDir: "vaults",
+        isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
+        toCanonicalName: (typeRoot, filePath) => {
+            const rel = toPosix(path.relative(typeRoot, filePath));
+            const fileName = path.basename(rel);
+            // Treat ".env" as the "default" vault; "<name>.env" → "<name>"
+            if (fileName === ".env") {
+                const dir = path.dirname(rel);
+                return dir === "." || dir === "" ? "default" : `${dir}/default`;
+            }
+            const stripped = rel.endsWith(".env") ? rel.slice(0, -4) : rel;
+            return stripped;
+        },
+        toAssetPath: (typeRoot, name) => {
+            if (name === "default")
+                return path.join(typeRoot, ".env");
+            return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
+        },
+        rendererName: "vault-env",
+        actionBuilder: (ref) => `akm vault list ${ref} -> see key names; eval "$(akm vault load ${ref})" -> load values into the current shell (values never echoed)`,
+    },
+    wiki: {
+        stashDir: "wikis",
+        ...markdownSpec,
+        rendererName: "wiki-md",
+        actionBuilder: (ref) => `akm show ${ref} -> read the wiki page`,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**