agentikit 0.0.3 → 0.0.8

package/README.md

@@ -1,15 +1,17 @@
 # agentikit
 
-Agentikit is a stash toolkit for AI coding assistants. It exposes three tools so agents can **search**, **open**, and **run** extension assets directly from a stash directory. Works as both an **OpenCode plugin** and a **Claude Code plugin**.
+Agentikit is a CLI tool and library for managing a stash of extension assets for AI coding assistants. It lets you **search** and **show** tools, skills, commands, and agents from a stash directory.
+
+The CLI is called **akm** (Agentikit Manager).
 
 ## Installation
 
 ### npm / bun
 
 ```sh
-npm install @itlackey/agentikit
+npm install -g agentikit
 # or
-bun add @itlackey/agentikit
+bun add -g agentikit
 ```
 
 ### Standalone binary
@@ -17,131 +19,165 @@ bun add @itlackey/agentikit
 Use the install scripts for a copy/paste install:
 
 ```sh
-# macOS / Linux (recommended: pin a release tag)
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
+# pin a release tag)
 curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash -s -- v1.2.3
-```
 
-```sh
 # PowerShell (Windows)
-irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1 v1.2.3
+irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
 ```
 
 The shell installer verifies the downloaded binary against release `checksums.txt` before installing it.
 
-### OpenCode plugin
+## Stash model
 
-Add agentikit to the `plugin` array in your OpenCode config (`opencode.json`):
+Set a stash path via `AGENTIKIT_STASH_DIR`, or run `akm init` to create one automatically.
 
-```json
-{
-  "plugin": ["@itlackey/agentikit"]
-}
+```sh
+export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
 ```
 
-### Claude Code plugin
+Expected stash layout:
+
+```
+$AGENTIKIT_STASH_DIR/
+├── tools/      # recursive files (.sh, .ts, .js, .ps1, .cmd, .bat)
+├── skills/     # skill directories containing SKILL.md
+├── commands/   # markdown files
+├── agents/     # markdown files
+└── knowledge/  # markdown files
+```
 
-Install agentikit as a Claude Code plugin by pointing to the repo directory:
+## CLI usage
 
 ```sh
-claude --plugin-dir /path/to/agentikit
+akm init                 # Initialize stash directory and set AGENTIKIT_STASH_DIR
+akm index [--full]       # Build search index (incremental by default)
+akm search [query]       # Search the stash
+akm show <type:name>     # Read a stash asset by ref
 ```
 
-Or add it to a plugin marketplace for team distribution. See the [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins) for details.
+### search
 
-Once installed, the plugin provides:
+Search the stash for extension assets.
 
-- **Skill** (`agentikit:stash`) — Claude automatically uses this when you ask about stash assets
-- **Commands** — `/agentikit:search`, `/agentikit:open`, `/agentikit:run` slash commands
+```sh
+akm search "deploy" --type tool --limit 10
+```
 
-## Stash model
+- `query`: case-insensitive substring over stable names (relative paths)
+- `--type`: `tool | skill | command | agent | knowledge | any` (default: `any`)
+- `--limit`: defaults to `20`
+
+Returns typed hits with `openRef`, score/explainability details (`score`, `whyMatched`), and, for tools, execution-ready `runCmd`.
 
-Set a stash path via `AGENTIKIT_STASH_DIR`.
+### show
+
+Show a hit using `openRef` from search results.
 
 ```sh
-export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
+akm show skill:code-review
+akm show knowledge:guide.md --view toc
+akm show knowledge:guide.md --view section --heading "Getting Started"
+akm show knowledge:guide.md --view lines --start 10 --end 30
 ```
 
-Expected stash layout:
+Returns full payload by type:
 
-```
-$AGENTIKIT_STASH_DIR/
-├── tools/      # recursive files (.sh, .ts, .js, .ps1, .cmd, .bat)
-├── skills/     # skill directories containing SKILL.md
-├── commands/   # markdown files
-└── agents/     # markdown files
+- `skill` — full `SKILL.md` content
+- `command` — full markdown body as `template` (+ best-effort `description`)
+- `agent` — full markdown body as `prompt` (+ best-effort `description`, `toolPolicy`, `modelHint`)
+- `tool` — `runCmd`/`kind` (the agent uses the host's shell to execute `runCmd`)
+- `knowledge` — content with optional view modes (`full`, `toc`, `frontmatter`, `section`, `lines`)
+
+## Library API
+
+Agentikit also exports its core functions for use as a library:
+
+```ts
+import { agentikitSearch, agentikitShow, agentikitInit, agentikitIndex } from "agentikit"
 ```
 
-## Tools
+- `agentikitSearch({ query, type?, limit? })` — search the stash
+- `agentikitShow({ ref, view? })` — show a stash asset
+- `agentikitInit()` — initialize stash directory
+- `agentikitIndex()` — build/rebuild search index
 
-When loaded as a plugin (OpenCode or Claude Code), Agentikit provides three tools:
+## Configuration
 
-- `agentikit_search({ query, type?, limit? })`
-- `agentikit_open({ ref })`
-- `agentikit_run({ ref })`
+Agentikit stores configuration in `config.json` inside the stash directory.
 
-### `agentikit_search`
+```sh
+akm config                    # Show current config
+akm config --set key=value    # Update a config key
+```
 
-Search the stash for extension assets.
+### Embedding connection
 
-- `query`: case-insensitive substring over stable names (relative paths)
-- `type`: `tool | skill | command | agent | any` (default: `any`)
-- `limit`: defaults to `20`
+By default, agentikit uses the local `@xenova/transformers` library for embeddings. You can configure an OpenAI-compatible embedding endpoint instead:
 
-Returns typed hits with `openRef` and, for tools, execution-ready `runCmd`.
+```sh
+akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
+```
 
-Tool command generation:
+To clear the custom embedding config and revert to local embeddings:
 
-- `.sh` → `bash "<absolute-file>"`
-- `.ps1` → `powershell -ExecutionPolicy Bypass -File "<absolute-file>"`
-- `.cmd`/`.bat` → `cmd /c "<absolute-file>"`
-- `.ts`/`.js`:
-  - find nearest `package.json` from script dir upward to stash `tools/` root
-  - if found: `cd "<pkgDir>" && bun "<absolute-file>"`
-  - else: `bun "<absolute-file>"`
-  - optional: set `AGENTIKIT_BUN_INSTALL=true` to include `bun install` before running
+```sh
+akm config --set 'embedding=null'
+```
 
-### `agentikit_open`
+### LLM connection
 
-Open a hit using `openRef` from search results.
+When configured, agentikit uses an OpenAI-compatible LLM to generate richer metadata (descriptions, intents, tags) during indexing:
 
-Returns full payload by type:
+```sh
+akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
+```
 
-- `skill` → full `SKILL.md` content
-- `command` → full markdown body as `template` (+ best-effort `description`)
-- `agent` → full markdown body as `prompt` (+ best-effort `description`, `toolPolicy`, `modelHint`)
-- `tool` → `runCmd`/`kind`
+To clear:
 
-### `agentikit_run`
+```sh
+akm config --set 'llm=null'
+```
 
-Execute a tool from the stash by its `openRef`. Only `tool:` refs are supported.
+### Using a local Ollama instance
 
-- `ref`: open reference of a tool returned by `agentikit_search`
+[Ollama](https://ollama.com) provides local models with an OpenAI-compatible API. After installing Ollama and pulling your models:
 
-Returns `{ type, name, path, output, exitCode }`.
+```sh
+# Pull models
+ollama pull nomic-embed-text
+ollama pull llama3.2
 
-## Usage example
+# Configure agentikit to use Ollama for both embeddings and metadata generation
+akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
+akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
 
-1. `agentikit_search({ query: "deploy", type: "tool" })`
-2. `agentikit_run({ ref: "<openRef from search>" })`
+# Rebuild the index — embeddings use Ollama, metadata is LLM-enhanced
+akm index --full
+```
 
-Or:
+Both `embedding` and `llm` accept an optional `apiKey` field for authenticated endpoints:
 
-1. `agentikit_search({ query: "release", type: "command" })`
-2. `agentikit_open({ ref: "<openRef from search>" })`
-3. Apply returned template in-session
+```json
+{
+  "endpoint": "https://api.openai.com/v1/embeddings",
+  "model": "text-embedding-3-small",
+  "apiKey": "sk-..."
+}
+```
 
-## Package exports
+### Config reference
 
-- `plugin` — OpenCode plugin exposing `agentikit_search`, `agentikit_open`, and `agentikit_run`
-- `agentikitSearch` / `agentikitOpen` / `agentikitRun` — direct library APIs
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `semanticSearch` | `boolean` | `true` | Enable semantic search ranking |
+| `additionalStashDirs` | `string[]` | `[]` | Extra stash directories to search |
+| `embedding` | `object` | not set | OpenAI-compatible embedding endpoint (`endpoint`, `model`, `apiKey?`) |
+| `llm` | `object` | not set | OpenAI-compatible LLM endpoint (`endpoint`, `model`, `apiKey?`) |
 
 ## Notes
 
-- Agentikit does not write to `.opencode/` or `.claude/`.
 - Agentikit does not install or copy kit files.
 - Missing or unreadable stash paths return friendly errors.
-
-## Docs
-
-- **OpenCode**: [Plugins](https://opencode.ai/docs/plugins/) · [Commands](https://opencode.ai/docs/commands/) · [Agents](https://opencode.ai/docs/agents/) · [Agent Skills](https://opencode.ai/docs/skills/) · [Custom tools](https://opencode.ai/docs/custom-tools/) · [Config](https://opencode.ai/docs/config/)
-- **Claude Code**: [Plugins](https://code.claude.com/docs/en/plugins) · [Skills](https://code.claude.com/docs/en/skills) · [Plugins reference](https://code.claude.com/docs/en/plugins-reference)

package/dist/index.d.ts

@@ -1,6 +1,18 @@
-export { plugin } from "./src/plugin";
-export { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./src/stash";
-export type { AgentikitAssetType, AgentikitSearchType, SearchHit, SearchResponse, OpenResponse, RunResponse, InitResponse, } from "./src/stash";
+export { agentikitSearch, agentikitShow } from "./src/stash";
+export { agentikitInit } from "./src/init";
+export type { InitResponse } from "./src/init";
+export type { AgentikitAssetType, AgentikitSearchType, SearchHit, SearchResponse, ShowResponse, KnowledgeView, } from "./src/stash";
+export type { ToolKind } from "./src/tool-runner";
 export { agentikitIndex } from "./src/indexer";
 export type { IndexResponse } from "./src/indexer";
 export type { StashEntry, StashFile, StashIntent } from "./src/metadata";
+export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
+export type { EnsureRgResult } from "./src/ripgrep";
+export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./src/markdown";
+export type { TocHeading, KnowledgeToc } from "./src/markdown";
+export { parseFrontmatter } from "./src/frontmatter";
+export { loadConfig, saveConfig, updateConfig } from "./src/config";
+export type { AgentikitConfig, EmbeddingConnectionConfig, LlmConnectionConfig } from "./src/config";
+export { enhanceMetadata, isLlmAvailable } from "./src/llm";
+export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";
+export type { EmbeddingVector } from "./src/embedder";

package/dist/index.js

@@ -1,3 +1,9 @@
-export { plugin } from "./src/plugin";
-export { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./src/stash";
+export { agentikitSearch, agentikitShow } from "./src/stash";
+export { agentikitInit } from "./src/init";
 export { agentikitIndex } from "./src/indexer";
+export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
+export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./src/markdown";
+export { parseFrontmatter } from "./src/frontmatter";
+export { loadConfig, saveConfig, updateConfig } from "./src/config";
+export { enhanceMetadata, isLlmAvailable } from "./src/llm";
+export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";

package/dist/src/asset-spec.d.ts

@@ -0,0 +1,14 @@
+import type { AgentikitAssetType } from "./common";
+export declare const SCRIPT_EXTENSIONS: Set<string>;
+export interface AssetSpec {
+    stashDir: string;
+    isRelevantFile: (fileName: string) => boolean;
+    toCanonicalName: (typeRoot: string, filePath: string) => string | undefined;
+    toAssetPath: (typeRoot: string, name: string) => string;
+}
+export declare const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec>;
+export declare const ASSET_TYPES: AgentikitAssetType[];
+export declare const TYPE_DIRS: Record<AgentikitAssetType, string>;
+export declare function isRelevantAssetFile(assetType: AgentikitAssetType, fileName: string): boolean;
+export declare function deriveCanonicalAssetName(assetType: AgentikitAssetType, typeRoot: string, filePath: string): string | undefined;
+export declare function resolveAssetPathFromName(assetType: AgentikitAssetType, typeRoot: string, name: string): string;

package/dist/src/asset-spec.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
+const markdownSpec = {
+    isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
+    toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+    toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+};
+export const ASSET_SPECS = {
+    tool: {
+        stashDir: "tools",
+        isRelevantFile: (fileName) => SCRIPT_EXTENSIONS.has(path.extname(fileName).toLowerCase()),
+        toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+    },
+    skill: {
+        stashDir: "skills",
+        isRelevantFile: (fileName) => fileName === "SKILL.md",
+        toCanonicalName: (typeRoot, filePath) => {
+            const relDir = toPosix(path.dirname(path.relative(typeRoot, filePath)));
+            if (!relDir || relDir === ".")
+                return undefined;
+            return relDir;
+        },
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name, "SKILL.md"),
+    },
+    command: { stashDir: "commands", ...markdownSpec },
+    agent: { stashDir: "agents", ...markdownSpec },
+    knowledge: { stashDir: "knowledge", ...markdownSpec },
+};
+export const ASSET_TYPES = Object.keys(ASSET_SPECS);
+export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
+    acc[type] = ASSET_SPECS[type].stashDir;
+    return acc;
+}, {});
+export function isRelevantAssetFile(assetType, fileName) {
+    return ASSET_SPECS[assetType].isRelevantFile(fileName);
+}
+export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
+    return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath);
+}
+export function resolveAssetPathFromName(assetType, typeRoot, name) {
+    return ASSET_SPECS[assetType].toAssetPath(typeRoot, name);
+}
+function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}

package/dist/src/cli.js

@@ -1,62 +1,164 @@
 #!/usr/bin/env node
-import { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./stash";
+import { defineCommand, runMain } from "citty";
+import { agentikitSearch, agentikitShow } from "./stash";
+import { agentikitInit } from "./init";
 import { agentikitIndex } from "./indexer";
-const args = process.argv.slice(2);
-const command = args[0];
-function flag(name) {
-    const idx = args.indexOf(name);
-    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
-}
-function usage() {
-    console.error("Usage: agentikit <init|search|open|run> [options]");
-    console.error("");
-    console.error("Commands:");
-    console.error("  init                 Initialize agentikit stash directory and set AGENTIKIT_STASH_DIR");
-    console.error("  index                Build search index with metadata generation");
-    console.error("  search [query]       Search the stash (--type tool|skill|command|agent|any) (--limit N)");
-    console.error("  open <type:name>     Open a stash asset by ref");
-    console.error("  run <type:name>      Run a tool by ref");
-    process.exit(1);
-}
-switch (command) {
-    case "init": {
+import { loadConfig, updateConfig } from "./config";
+import { resolveStashDir } from "./common";
+const initCommand = defineCommand({
+    meta: { name: "init", description: "Initialize agentikit stash directory and set AGENTIKIT_STASH_DIR" },
+    run() {
         const result = agentikitInit();
         console.log(JSON.stringify(result, null, 2));
-        break;
-    }
-    case "index": {
-        const result = agentikitIndex();
+    },
+});
+const indexCommand = defineCommand({
+    meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
+    args: {
+        full: { type: "boolean", description: "Force full reindex", default: false },
+    },
+    async run({ args }) {
+        const result = await agentikitIndex({ full: args.full });
         console.log(JSON.stringify(result, null, 2));
-        break;
+    },
+});
+const searchCommand = defineCommand({
+    meta: { name: "search", description: "Search the stash" },
+    args: {
+        query: { type: "positional", description: "Search query", required: false, default: "" },
+        type: { type: "string", description: "Asset type filter (tool|skill|command|agent|knowledge|any)" },
+        limit: { type: "string", description: "Maximum number of results" },
+    },
+    async run({ args }) {
+        const type = args.type;
+        const limit = args.limit ? parseInt(args.limit, 10) : undefined;
+        console.log(JSON.stringify(await agentikitSearch({ query: args.query, type, limit }), null, 2));
+    },
+});
+const showCommand = defineCommand({
+    meta: { name: "show", description: "Show a stash asset by ref (e.g. agent:bunjs-typescript-coder.md)" },
+    args: {
+        ref: { type: "positional", description: "Asset ref (type:name)", required: true },
+        view: { type: "string", description: "Knowledge view mode (full|toc|frontmatter|section|lines)" },
+        heading: { type: "string", description: "Section heading (for --view section)" },
+        start: { type: "string", description: "Start line (for --view lines)" },
+        end: { type: "string", description: "End line (for --view lines)" },
+    },
+    run({ args }) {
+        let view;
+        if (args.view) {
+            switch (args.view) {
+                case "section":
+                    view = { mode: "section", heading: args.heading ?? "" };
+                    break;
+                case "lines":
+                    view = {
+                        mode: "lines",
+                        start: Number(args.start ?? "1"),
+                        end: args.end ? parseInt(args.end, 10) : Number.MAX_SAFE_INTEGER,
+                    };
+                    break;
+                case "toc":
+                case "frontmatter":
+                case "full":
+                    view = { mode: args.view };
+                    break;
+                default:
+                    console.error(`Unknown view mode: ${args.view}`);
+                    process.exit(1);
+            }
+        }
+        console.log(JSON.stringify(agentikitShow({ ref: args.ref, view }), null, 2));
+    },
+});
+const configCommand = defineCommand({
+    meta: { name: "config", description: "Show or update configuration" },
+    args: {
+        set: { type: "string", description: "Update a config key (key=value format)" },
+    },
+    run({ args }) {
+        const stashDir = resolveStashDir();
+        if (args.set) {
+            const eqIndex = args.set.indexOf("=");
+            if (eqIndex === -1) {
+                console.error("Error: --set expects key=value format");
+                process.exit(1);
+            }
+            const key = args.set.slice(0, eqIndex);
+            const value = args.set.slice(eqIndex + 1);
+            const partial = parseConfigValue(key, value);
+            const config = updateConfig(partial, stashDir);
+            console.log(JSON.stringify(config, null, 2));
+        }
+        else {
+            const config = loadConfig(stashDir);
+            console.log(JSON.stringify(config, null, 2));
+        }
+    },
+});
+const main = defineCommand({
+    meta: {
+        name: "akm",
+        description: "CLI tool to search, open, and run extension assets from an agentikit stash directory.",
+    },
+    subCommands: {
+        init: initCommand,
+        index: indexCommand,
+        search: searchCommand,
+        show: showCommand,
+        config: configCommand,
+    },
+});
+runMain(main);
+function parseConnectionValue(key, value, exampleEndpoint, exampleModel) {
+    if (value === "null" || value === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
     }
-    case "search": {
-        const query = args.find((a, i) => i > 0 && !a.startsWith("--") && args[i - 1] !== "--type" && args[i - 1] !== "--limit") ?? "";
-        const type = flag("--type");
-        const limitStr = flag("--limit");
-        const limit = limitStr ? parseInt(limitStr, 10) : undefined;
-        console.log(JSON.stringify(agentikitSearch({ query, type, limit }), null, 2));
-        break;
+    catch {
+        throw new Error(`Invalid value for ${key}: expected JSON object with endpoint and model`
+            + ` (e.g. '{"endpoint":"${exampleEndpoint}","model":"${exampleModel}"}')`);
     }
-    case "open": {
-        const ref = args[1];
-        if (!ref) {
-            console.error("Error: missing ref argument\n");
-            usage();
-        }
-        console.log(JSON.stringify(agentikitOpen({ ref }), null, 2));
-        break;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Invalid value for ${key}: expected a JSON object`);
     }
-    case "run": {
-        const ref = args[1];
-        if (!ref) {
-            console.error("Error: missing ref argument\n");
-            usage();
-        }
-        const result = agentikitRun({ ref });
-        console.log(JSON.stringify(result, null, 2));
-        process.exit(result.exitCode);
-        break;
+    const obj = parsed;
+    if (typeof obj.endpoint !== "string" || !obj.endpoint || typeof obj.model !== "string" || !obj.model) {
+        throw new Error(`Invalid value for ${key}: "endpoint" and "model" are required string fields`);
+    }
+    const result = {
+        endpoint: obj.endpoint,
+        model: obj.model,
+    };
+    if (typeof obj.apiKey === "string" && obj.apiKey) {
+        result.apiKey = obj.apiKey;
+    }
+    return result;
+}
+function parseConfigValue(key, value) {
+    switch (key) {
+        case "semanticSearch":
+            if (value !== "true" && value !== "false") {
+                throw new Error(`Invalid value for semanticSearch: expected "true" or "false"`);
+            }
+            return { semanticSearch: value === "true" };
+        case "additionalStashDirs":
+            try {
+                const parsed = JSON.parse(value);
+                if (!Array.isArray(parsed))
+                    throw new Error("expected JSON array");
+                return { additionalStashDirs: parsed.filter((d) => typeof d === "string") };
+            }
+            catch {
+                throw new Error(`Invalid value for additionalStashDirs: expected JSON array (e.g. '["/path/a","/path/b"]')`);
+            }
+        case "embedding":
+            return { embedding: parseConnectionValue("embedding", value, "http://localhost:11434/v1/embeddings", "nomic-embed-text") };
+        case "llm":
+            return { llm: parseConnectionValue("llm", value, "http://localhost:11434/v1/chat/completions", "llama3.2") };
+        default:
+            throw new Error(`Unknown config key: ${key}`);
     }
-    default:
-        usage();
 }

package/dist/src/common.d.ts

@@ -0,0 +1,8 @@
+export type AgentikitAssetType = "tool" | "skill" | "command" | "agent" | "knowledge";
+export declare const IS_WINDOWS: boolean;
+export { SCRIPT_EXTENSIONS, TYPE_DIRS } from "./asset-spec";
+export declare function isAssetType(type: string): type is AgentikitAssetType;
+export declare function resolveStashDir(): string;
+export declare function toPosix(input: string): string;
+export declare function hasErrnoCode(error: unknown, code: string): boolean;
+export declare function isWithin(candidate: string, root: string): boolean;

package/dist/src/common.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "./asset-spec";
+// ── Constants ───────────────────────────────────────────────────────────────
+export const IS_WINDOWS = process.platform === "win32";
+export { SCRIPT_EXTENSIONS, TYPE_DIRS } from "./asset-spec";
+// ── Validators ──────────────────────────────────────────────────────────────
+export function isAssetType(type) {
+    return type in TYPE_DIRS;
+}
+// ── Utilities ───────────────────────────────────────────────────────────────
+export function resolveStashDir() {
+    const raw = process.env.AGENTIKIT_STASH_DIR?.trim();
+    if (!raw) {
+        throw new Error("AGENTIKIT_STASH_DIR is not set. Set it to your Agentikit stash path.");
+    }
+    const stashDir = path.resolve(raw);
+    let stat;
+    try {
+        stat = fs.statSync(stashDir);
+    }
+    catch {
+        throw new Error(`Unable to read AGENTIKIT_STASH_DIR at "${stashDir}".`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`AGENTIKIT_STASH_DIR must point to a directory: "${stashDir}".`);
+    }
+    return stashDir;
+}
+export function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}
+export function hasErrnoCode(error, code) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === code;
+}
+export function isWithin(candidate, root) {
+    const normalizedRoot = normalizeFsPathForComparison(path.resolve(root));
+    const normalizedCandidate = normalizeFsPathForComparison(path.resolve(candidate));
+    const rel = path.relative(normalizedRoot, normalizedCandidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function normalizeFsPathForComparison(value) {
+    return process.platform === "win32" ? value.toLowerCase() : value;
+}