agentikit 0.0.9 → 0.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/README.md +129 -214
  2. package/dist/index.d.ts +8 -2
  3. package/dist/index.js +4 -1
  4. package/dist/src/asset-spec.d.ts +2 -0
  5. package/dist/src/asset-spec.js +22 -3
  6. package/dist/src/asset-type-handler.d.ts +27 -0
  7. package/dist/src/asset-type-handler.js +33 -0
  8. package/dist/src/cli.js +201 -75
  9. package/dist/src/common.d.ts +6 -1
  10. package/dist/src/common.js +18 -4
  11. package/dist/src/config-cli.d.ts +9 -0
  12. package/dist/src/config-cli.js +473 -0
  13. package/dist/src/config.d.ts +19 -6
  14. package/dist/src/config.js +139 -29
  15. package/dist/src/db.d.ts +46 -0
  16. package/dist/src/db.js +299 -0
  17. package/dist/src/embedder.js +12 -7
  18. package/dist/src/github.d.ts +4 -0
  19. package/dist/src/github.js +19 -0
  20. package/dist/src/handlers/agent-handler.d.ts +2 -0
  21. package/dist/src/handlers/agent-handler.js +26 -0
  22. package/dist/src/handlers/command-handler.d.ts +2 -0
  23. package/dist/src/handlers/command-handler.js +23 -0
  24. package/dist/src/handlers/index.d.ts +6 -0
  25. package/dist/src/handlers/index.js +23 -0
  26. package/dist/src/handlers/knowledge-handler.d.ts +2 -0
  27. package/dist/src/handlers/knowledge-handler.js +56 -0
  28. package/dist/src/handlers/markdown-helpers.d.ts +7 -0
  29. package/dist/src/handlers/markdown-helpers.js +15 -0
  30. package/dist/src/handlers/script-handler.d.ts +2 -0
  31. package/dist/src/handlers/script-handler.js +78 -0
  32. package/dist/src/handlers/skill-handler.d.ts +2 -0
  33. package/dist/src/handlers/skill-handler.js +30 -0
  34. package/dist/src/handlers/tool-handler.d.ts +2 -0
  35. package/dist/src/handlers/tool-handler.js +58 -0
  36. package/dist/src/indexer.d.ts +1 -23
  37. package/dist/src/indexer.js +162 -155
  38. package/dist/src/init.d.ts +2 -2
  39. package/dist/src/init.js +21 -9
  40. package/dist/src/llm.js +4 -3
  41. package/dist/src/metadata.d.ts +0 -1
  42. package/dist/src/metadata.js +6 -64
  43. package/dist/src/origin-resolve.d.ts +19 -0
  44. package/dist/src/origin-resolve.js +53 -0
  45. package/dist/src/registry-install.d.ts +2 -2
  46. package/dist/src/registry-install.js +142 -35
  47. package/dist/src/registry-resolve.js +90 -22
  48. package/dist/src/registry-search.d.ts +22 -0
  49. package/dist/src/registry-search.js +231 -97
  50. package/dist/src/registry-types.d.ts +9 -2
  51. package/dist/src/stash-add.js +4 -4
  52. package/dist/src/stash-clone.d.ts +22 -0
  53. package/dist/src/stash-clone.js +83 -0
  54. package/dist/src/stash-ref.d.ts +27 -3
  55. package/dist/src/stash-ref.js +63 -24
  56. package/dist/src/stash-registry.js +12 -12
  57. package/dist/src/stash-resolve.js +3 -0
  58. package/dist/src/stash-search.js +168 -164
  59. package/dist/src/stash-show.d.ts +1 -1
  60. package/dist/src/stash-show.js +28 -96
  61. package/dist/src/stash-source.d.ts +24 -0
  62. package/dist/src/stash-source.js +81 -0
  63. package/dist/src/stash-types.d.ts +14 -4
  64. package/dist/src/stash.d.ts +6 -0
  65. package/dist/src/stash.js +3 -0
  66. package/dist/src/tool-runner.d.ts +1 -1
  67. package/dist/src/tool-runner.js +18 -5
  68. package/package.json +7 -2
  69. package/src/asset-spec.ts +20 -4
  70. package/src/asset-type-handler.ts +77 -0
  71. package/src/cli.ts +213 -82
  72. package/src/common.ts +23 -5
  73. package/src/config-cli.ts +499 -0
  74. package/src/config.ts +160 -38
  75. package/src/db.ts +411 -0
  76. package/src/embedder.ts +22 -11
  77. package/src/github.ts +21 -0
  78. package/src/handlers/agent-handler.ts +32 -0
  79. package/src/handlers/command-handler.ts +29 -0
  80. package/src/handlers/index.ts +25 -0
  81. package/src/handlers/knowledge-handler.ts +62 -0
  82. package/src/handlers/markdown-helpers.ts +19 -0
  83. package/src/handlers/script-handler.ts +92 -0
  84. package/src/handlers/skill-handler.ts +37 -0
  85. package/src/handlers/tool-handler.ts +71 -0
  86. package/src/indexer.ts +208 -187
  87. package/src/init.ts +17 -9
  88. package/src/llm.ts +4 -3
  89. package/src/metadata.ts +5 -65
  90. package/src/origin-resolve.ts +67 -0
  91. package/src/registry-install.ts +158 -42
  92. package/src/registry-resolve.ts +92 -23
  93. package/src/registry-search.ts +288 -98
  94. package/src/registry-types.ts +10 -2
  95. package/src/stash-add.ts +14 -17
  96. package/src/stash-clone.ts +127 -0
  97. package/src/stash-ref.ts +84 -26
  98. package/src/stash-registry.ts +12 -12
  99. package/src/stash-resolve.ts +3 -0
  100. package/src/stash-search.ts +202 -184
  101. package/src/stash-show.ts +33 -90
  102. package/src/stash-source.ts +103 -0
  103. package/src/stash-types.ts +14 -4
  104. package/src/stash.ts +8 -0
  105. package/src/tool-runner.ts +18 -5
  106. package/dist/src/similarity.d.ts +0 -34
  107. package/src/similarity.ts +0 -271
package/README.md CHANGED
@@ -1,286 +1,201 @@
1
- # agentikit
1
+ # Agent-i-Kit
2
2
 
3
- 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.
3
+ Agent-i-Kit gives AI coding agents a shared library of capabilities they can
4
+ search and use. You organize tools, skills, commands, agents, knowledge, and
5
+ scripts into a **stash**, and agents discover what they need through
6
+ `akm` (Agent Kit Manager).
4
7
 
5
- The CLI is called **akm** (Agentikit Manager).
8
+ ## What Is a Kit?
6
9
 
7
- ## Installation
10
+ A kit is a shareable package of assets. Any directory with asset
11
+ subdirectories is a valid kit:
8
12
 
9
- ### npm / bun
10
-
11
- ```sh
12
- npm install -g agentikit
13
- # or
14
- bun add -g agentikit
13
+ ```text
14
+ my-kit/
15
+ tools/ # Executable scripts (.sh, .ts, .js)
16
+ skills/ # Skill definitions (directories with SKILL.md)
17
+ commands/ # Slash commands (.md)
18
+ agents/ # Agent definitions (.md)
19
+ knowledge/ # Reference documents (.md)
20
+ scripts/ # General scripts (.py, .rb, .go, etc.)
15
21
  ```
16
22
 
17
- ### Standalone binary
23
+ Kits can be published to npm or hosted on GitHub. Tag them with `akm` or
24
+ `agentikit` so others can discover them through registry search.
18
25
 
19
- Use the install scripts for a copy/paste install:
26
+ ## What Is a Stash?
20
27
 
21
- ```sh
22
- # macOS / Linux
23
- curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
24
- # pin a release tag)
25
- curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash -s -- v1.2.3
28
+ The stash is your local library of assets. It combines three sources:
26
29
 
27
- # PowerShell (Windows)
28
- irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
29
- ```
30
+ 1. **Working stash** -- Your personal assets (`AKM_STASH_DIR`). Read-write.
31
+ 2. **Mounted dirs** -- Shared team directories. Read-only.
32
+ 3. **Installed kits** -- Kits from npm or GitHub via `akm add`. Read-only.
30
33
 
31
- The shell installer verifies the downloaded binary against release `checksums.txt` before installing it.
34
+ When you search or open an asset, the working stash takes priority. This
35
+ means you can install a kit and override individual assets by cloning them
36
+ into your working stash.
32
37
 
33
- ## Stash model
34
-
35
- Set a stash path via `AGENTIKIT_STASH_DIR`, or run `akm init` to create one automatically.
38
+ ## Quick Start
36
39
 
37
40
  ```sh
38
- export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
39
- ```
41
+ # Install
42
+ npm install -g agentikit
40
43
 
41
- Expected stash layout:
44
+ # Initialize your stash
45
+ akm init
42
46
 
43
- ```
44
- $AGENTIKIT_STASH_DIR/
45
- ├── tools/ # recursive files (.sh, .ts, .js, .ps1, .cmd, .bat)
46
- ├── skills/ # skill directories containing SKILL.md
47
- ├── commands/ # markdown files
48
- ├── agents/ # markdown files
49
- └── knowledge/ # markdown files
50
- ```
47
+ # Search for assets
48
+ akm search "deploy"
51
49
 
52
- ## CLI usage
50
+ # Show an asset
51
+ akm show tool:deploy.sh
53
52
 
54
- ```sh
55
- akm init # Initialize stash directory and set AGENTIKIT_STASH_DIR
56
- akm index [--full] # Build search index (incremental by default)
57
- akm add <ref> # Install a registry kit by npm/GitHub ref
58
- akm list # List installed registry kits from config.registry.installed
59
- akm remove <target> # Remove installed kit by id/ref (or parsed ref id)
60
- akm update [target] [--all] # Fresh install from current ref(s), report changed revision/version
61
- akm reinstall [target] [--all] # Reinstall from stored refs
62
- akm search [query] # Search local stash and/or registry
63
- akm show <type:name> # Read a stash asset by ref
64
- ```
53
+ # Install a kit from npm
54
+ akm add @scope/my-kit
65
55
 
66
- ### add
67
-
68
- Install a registry reference and make it searchable immediately.
69
-
70
- ```sh
71
- akm add @scope/kit
72
- akm add npm:@scope/kit@latest
73
- akm add owner/repo
74
- akm add github:owner/repo#v1.2.3
56
+ # Search installed and registry kits
57
+ akm search "lint" --source both
75
58
  ```
76
59
 
77
- - Uses registry resolution + install helpers (`npm` and `github` refs)
78
- - Updates `config.json` registry install records and syncs `additionalStashDirs`
79
- - If an existing install with the same id is replaced, old cache directories are cleaned up (best effort)
80
- - Triggers an incremental index build
81
- - Returns JSON with install details and index stats
82
-
83
- ### list
84
-
85
- Show installed entries from `config.registry.installed`.
86
-
87
- - Source of truth is config, not cache directory discovery
88
- - Each entry includes status flags:
89
- - `status.cacheDirExists`
90
- - `status.stashRootExists`
91
-
92
- ### remove
93
-
94
- Remove a single installed entry and reindex incrementally.
60
+ ### Standalone Binary
95
61
 
96
62
  ```sh
97
- akm remove npm:@scope/kit
98
- akm remove github:owner/repo
99
- akm remove owner/repo
100
- ```
63
+ # macOS / Linux
64
+ curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
101
65
 
102
- - Target resolution order: exact `id`, exact stored `ref`, then parsed ref `id`
103
- - Removes entry via config helper (also syncs `additionalStashDirs`)
104
- - Deletes prior `cacheDir` best effort
105
- - Runs one incremental reindex
66
+ # Windows (PowerShell)
67
+ irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
68
+ ```
106
69
 
107
- ### reinstall
70
+ ## Searching and Showing Assets
108
71
 
109
- Reinstall one entry or all entries from stored refs.
72
+ Search returns scored results with metadata explaining why each hit matched:
110
73
 
111
74
  ```sh
112
- akm reinstall npm:@scope/kit
113
- akm reinstall --all
75
+ akm search "docker" --type tool
114
76
  ```
115
77
 
116
- - Uses the same registry install flow as `akm add`
117
- - Upserts config entries + `additionalStashDirs`
118
- - Cleans up replaced cache directories best effort
119
- - Runs one incremental reindex after all installs
120
-
121
- ### update
78
+ ```json
79
+ {
80
+ "hits": [
81
+ {
82
+ "name": "docker-build",
83
+ "type": "tool",
84
+ "description": "Build and push Docker images",
85
+ "openRef": "tool:docker-build.sh",
86
+ "score": 0.92,
87
+ "whyMatched": "matched name tokens, fts bm25 relevance"
88
+ }
89
+ ]
90
+ }
91
+ ```
122
92
 
123
- Update one entry or all entries by doing a fresh resolve/install from each current ref.
93
+ Use `openRef` from search results to show the full asset:
124
94
 
125
95
  ```sh
126
- akm update npm:@scope/kit
127
- akm update --all
96
+ akm show tool:docker-build.sh
128
97
  ```
129
98
 
130
- - Same target selection rules as `reinstall`
131
- - Floating refs (for example `@latest` or default branch) resolve to newest available artifact
132
- - Reports per-entry change flags for version/revision (`changed.version`, `changed.revision`, `changed.any`)
133
- - Runs one incremental reindex after all installs
134
-
135
- ### search
99
+ ```json
100
+ {
101
+ "type": "tool",
102
+ "name": "docker-build.sh",
103
+ "runCmd": "cd \"/path/to/tools\" && bash \"/path/to/tools/docker-build.sh\"",
104
+ "kind": "bash"
105
+ }
106
+ ```
136
107
 
137
- Search local stash assets, registry entries, or both.
108
+ For knowledge assets, views let you navigate large documents:
138
109
 
139
110
  ```sh
140
- akm search "deploy" --type tool --limit 10 --usage both
141
- akm search "lint" --source registry
142
- akm search "docker" --source both
111
+ akm show knowledge:api-guide.md --view toc
112
+ akm show knowledge:api-guide.md --view section --heading "Authentication"
143
113
  ```
144
114
 
145
- - `query`: case-insensitive substring over stable names (relative paths)
146
- - `--type`: `tool | skill | command | agent | knowledge | any` (default: `any`)
147
- - `--limit`: defaults to `20`
148
- - `--usage`: `none | both | item | guide` (default: `both`)
149
- - `--source`: `local | registry | both` (default: `local`)
150
-
151
- By default (`--source local`), results are the existing stash hits with `openRef`, score/explainability details (`score`, `whyMatched`), and, for tools, execution-ready `runCmd`.
152
-
153
- When registry results are included (`--source registry|both`), each registry hit includes explicit install guidance:
115
+ ## Using With AI Agents
154
116
 
155
- - `installRef` (normalized ref for install)
156
- - `installCmd` (ready-to-run command, e.g. `akm add npm:@scope/kit`)
117
+ Agent-i-Kit is designed to be called by AI coding agents. The agent searches
118
+ for capabilities, reads the results, and acts on them.
157
119
 
158
- - `usageGuide` is included by default (`--usage both`) and explains how to use each hit type.
159
- - Per-hit `usage` is optional metadata from `.stash.json` and is included when present.
120
+ ### OpenCode
160
121
 
161
- ### show
122
+ In an OpenCode project, add akm as a tool in your configuration. The agent
123
+ can then search the stash and run tools directly:
162
124
 
163
- Show a hit using `openRef` from search results.
164
-
165
- ```sh
166
- akm show skill:code-review
167
- akm show knowledge:guide.md --view toc
168
- akm show knowledge:guide.md --view section --heading "Getting Started"
169
- akm show knowledge:guide.md --view lines --start 10 --end 30
125
+ ```text
126
+ Search the stash for deployment tools, then run the best match.
170
127
  ```
171
128
 
172
- Returns full payload by type:
173
-
174
- - `skill` — full `SKILL.md` content
175
- - `command` — full markdown body as `template` (+ best-effort `description`)
176
- - `agent` — full markdown body as `prompt` (+ best-effort `description`, `toolPolicy`, `modelHint`)
177
- - `tool` — `runCmd`/`kind` (the agent uses the host's shell to execute `runCmd`)
178
- - `knowledge` — content with optional view modes (`full`, `toc`, `frontmatter`, `section`, `lines`)
179
-
180
- ## Library API
181
-
182
- Agentikit also exports its core functions for use as a library:
183
-
184
- ```ts
185
- import {
186
- agentikitAdd,
187
- agentikitList,
188
- agentikitRemove,
189
- agentikitReinstall,
190
- agentikitUpdate,
191
- agentikitSearch,
192
- agentikitShow,
193
- agentikitInit,
194
- agentikitIndex,
195
- } from "agentikit"
196
- ```
129
+ The agent calls `akm search "deploy" --type tool`, picks the top result,
130
+ reads its `runCmd` from `akm show`, and executes it.
197
131
 
198
- - `agentikitAdd({ ref })` — install a registry reference and index it
199
- - `agentikitList()` — list installed registry entries and filesystem status flags
200
- - `agentikitRemove({ target })` — remove one installed entry and reindex incrementally
201
- - `agentikitReinstall({ target? , all? })` — reinstall one/all installed entries
202
- - `agentikitUpdate({ target? , all? })` — fresh resolve/install one/all installed entries with change reporting
203
- - `agentikitSearch({ query, type?, limit?, usage?, source? })` — search local stash and/or registry
204
- - `agentikitShow({ ref, view? })` — show a stash asset
205
- - `agentikitInit()` — initialize stash directory
206
- - `agentikitIndex()` — build/rebuild search index
132
+ ### Claude Code
207
133
 
208
- ## Configuration
134
+ Add akm commands as tools or reference them from your CLAUDE.md:
209
135
 
210
- Agentikit stores configuration in `config.json` inside the stash directory.
136
+ ```markdown
137
+ ## Available Tools
211
138
 
212
- ```sh
213
- akm config # Show current config
214
- akm config --set key=value # Update a config key
139
+ Use `akm search <query>` to find tools, skills, and commands in the stash.
140
+ Use `akm show <ref>` to read asset details before using them.
215
141
  ```
216
142
 
217
- ### Embedding connection
218
-
219
- By default, agentikit uses the local `@xenova/transformers` library for embeddings. You can configure an OpenAI-compatible embedding endpoint instead:
143
+ ### Any Agent
220
144
 
221
- ```sh
222
- akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
223
- ```
145
+ The JSON output from `akm search` and `akm show` is designed for machine
146
+ consumption. Any agent that can run shell commands can use akm:
224
147
 
225
- To clear the custom embedding config and revert to local embeddings:
226
-
227
- ```sh
228
- akm config --set 'embedding=null'
229
- ```
148
+ 1. `akm search "what you need"` -- Find relevant assets
149
+ 2. `akm show <openRef>` -- Get the details
150
+ 3. Use the asset (run the `runCmd`, follow the skill instructions, etc.)
230
151
 
231
- ### LLM connection
152
+ ## Installing Kits
232
153
 
233
- When configured, agentikit uses an OpenAI-compatible LLM to generate richer metadata (descriptions, intents, tags) during indexing:
154
+ Install kits from npm, GitHub, or local directories:
234
155
 
235
156
  ```sh
236
- akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
157
+ akm add @scope/my-kit # npm package
158
+ akm add github:owner/repo # GitHub repo
159
+ akm add ./path/to/local/kit # Local git directory
237
160
  ```
238
161
 
239
- To clear:
162
+ Search the registry to discover kits:
240
163
 
241
164
  ```sh
242
- akm config --set 'llm=null'
165
+ akm search "code review" --source registry
243
166
  ```
244
167
 
245
- ### Using a local Ollama instance
168
+ Only packages tagged with `akm` or `agentikit` appear in registry results.
169
+ See [docs/registry.md](docs/registry.md) for details.
246
170
 
247
- [Ollama](https://ollama.com) provides local models with an OpenAI-compatible API. After installing Ollama and pulling your models:
171
+ ## Publishing a Kit
248
172
 
249
- ```sh
250
- # Pull models
251
- ollama pull nomic-embed-text
252
- ollama pull llama3.2
253
-
254
- # Configure agentikit to use Ollama for both embeddings and metadata generation
255
- akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
256
- akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
257
-
258
- # Rebuild the index — embeddings use Ollama, metadata is LLM-enhanced
259
- akm index --full
260
- ```
261
-
262
- Both `embedding` and `llm` accept an optional `apiKey` field for authenticated endpoints:
173
+ 1. Organize your assets into the standard directory structure
174
+ 2. Add `"akm"` to `keywords` in `package.json` (for npm) or add the `akm`
175
+ topic to your GitHub repo
176
+ 3. Optionally add an `agentikit.include` array in `package.json` to control
177
+ which paths are included when installed
263
178
 
264
179
  ```json
265
180
  {
266
- "endpoint": "https://api.openai.com/v1/embeddings",
267
- "model": "text-embedding-3-small",
268
- "apiKey": "sk-..."
181
+ "name": "@scope/my-kit",
182
+ "keywords": ["akm"],
183
+ "agentikit": {
184
+ "include": ["tools", "skills", "commands"]
185
+ }
269
186
  }
270
187
  ```
271
188
 
272
- ### Config reference
273
-
274
- | Key | Type | Default | Description |
275
- |-----|------|---------|-------------|
276
- | `semanticSearch` | `boolean` | `true` | Enable semantic search ranking |
277
- | `additionalStashDirs` | `string[]` | `[]` | Extra stash directories to search |
278
- | `embedding` | `object` | not set | OpenAI-compatible embedding endpoint (`endpoint`, `model`, `apiKey?`) |
279
- | `llm` | `object` | not set | OpenAI-compatible LLM endpoint (`endpoint`, `model`, `apiKey?`) |
280
-
281
- ## Notes
189
+ ## Documentation
282
190
 
283
- - `akm add` installs registry kits into the local cache and adds discovered stash roots to `additionalStashDirs`.
284
- - Registry lifecycle commands (`list`, `remove`, `reinstall`, `update`) use `config.registry.installed` as the source of truth.
285
- - When commands fail, CLI errors are returned as structured JSON with `error` and `hint` fields.
286
- - Missing or unreadable stash paths return friendly errors.
191
+ | Doc | Description |
192
+ | --- | --- |
193
+ | [Concepts](docs/concepts.md) | Asset types, stash sources, metadata, tool execution |
194
+ | [CLI Reference](docs/cli.md) | All akm commands and flags |
195
+ | [Kit Maker's Guide](docs/kit-makers.md) | How to build and share a kit |
196
+ | [Registry](docs/registry.md) | Finding, installing, and publishing kits |
197
+ | [Search](docs/search.md) | Hybrid search architecture and scoring |
198
+ | [Indexing](docs/indexing.md) | How the search index is built |
199
+ | [Filesystem](docs/filesystem.md) | Directory layout and `.stash.json` schema |
200
+ | [Configuration](docs/configuration.md) | Providers, settings, and Ollama setup |
201
+ | [Library API](docs/api.md) | Using agentikit as a TypeScript/JS library |
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- export { agentikitAdd, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, } from "./src/stash";
1
+ export { agentikitAdd, agentikitClone, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, resolveStashSources, resolveAllStashDirs, findSourceForPath, } from "./src/stash";
2
2
  export { agentikitInit } from "./src/init";
3
3
  export type { InitResponse } from "./src/init";
4
- export type { AgentikitAssetType, AgentikitSearchType, AddResponse, LocalSearchHit, RegistrySearchResultHit, SearchSource, SearchHit, SearchResponse, ShowResponse, KnowledgeView, ListResponse, RemoveResponse, ReinstallResponse, UpdateResponse, RegistryListEntry, RegistryInstallStatus, ReinstallResultItem, UpdateResultItem, } from "./src/stash";
4
+ export type { AgentikitAssetType, AgentikitSearchType, AddResponse, LocalSearchHit, RegistrySearchResultHit, SearchSource, SearchHit, SearchResponse, ShowResponse, KnowledgeView, ListResponse, RemoveResponse, ReinstallResponse, UpdateResponse, RegistryListEntry, RegistryInstallStatus, ReinstallResultItem, UpdateResultItem, StashSource, StashSourceKind, CloneOptions, CloneResponse, } from "./src/stash";
5
5
  export type { ToolKind } from "./src/tool-runner";
6
6
  export { agentikitIndex } from "./src/indexer";
7
7
  export type { IndexResponse } from "./src/indexer";
@@ -20,3 +20,9 @@ export type { RegistrySource, ParsedRegistryRef, ParsedNpmRef, ParsedGithubRef,
20
20
  export { enhanceMetadata, isLlmAvailable } from "./src/llm";
21
21
  export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";
22
22
  export type { EmbeddingVector } from "./src/embedder";
23
+ export type { SearchUsageMode } from "./src/stash-types";
24
+ export type { AssetTypeHandler, ShowInput } from "./src/asset-type-handler";
25
+ export { registerAssetType, getHandler, tryGetHandler, getAllHandlers, getRegisteredTypeNames } from "./src/asset-type-handler";
26
+ export { parseAssetRef, makeAssetRef } from "./src/stash-ref";
27
+ export type { AssetRef } from "./src/stash-ref";
28
+ export { resolveSourcesForOrigin, isRemoteOrigin } from "./src/origin-resolve";
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- export { agentikitAdd, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, } from "./src/stash";
1
+ export { agentikitAdd, agentikitClone, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, resolveStashSources, resolveAllStashDirs, findSourceForPath, } from "./src/stash";
2
2
  export { agentikitInit } from "./src/init";
3
3
  export { agentikitIndex } from "./src/indexer";
4
4
  export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
@@ -10,3 +10,6 @@ export { searchRegistry } from "./src/registry-search";
10
10
  export { installRegistryRef, upsertInstalledRegistryEntry, removeInstalledRegistryEntry, getRegistryCacheRootDir, detectStashRoot, } from "./src/registry-install";
11
11
  export { enhanceMetadata, isLlmAvailable } from "./src/llm";
12
12
  export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";
13
+ export { registerAssetType, getHandler, tryGetHandler, getAllHandlers, getRegisteredTypeNames } from "./src/asset-type-handler";
14
+ export { parseAssetRef, makeAssetRef } from "./src/stash-ref";
15
+ export { resolveSourcesForOrigin, isRemoteOrigin } from "./src/origin-resolve";
@@ -6,6 +6,8 @@ export interface AssetSpec {
6
6
  toCanonicalName: (typeRoot: string, filePath: string) => string | undefined;
7
7
  toAssetPath: (typeRoot: string, name: string) => string;
8
8
  }
9
+ /** Extended set of script extensions for the script asset type */
10
+ export declare const SCRIPT_EXTENSIONS_BROAD: Set<string>;
9
11
  export declare const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec>;
10
12
  export declare const ASSET_TYPES: AgentikitAssetType[];
11
13
  export declare const TYPE_DIRS: Record<AgentikitAssetType, string>;
@@ -1,10 +1,17 @@
1
1
  import path from "node:path";
2
+ import { toPosix } from "./common";
3
+ import { tryGetHandler } from "./asset-type-handler";
2
4
  export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
3
5
  const markdownSpec = {
4
6
  isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
5
7
  toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
6
8
  toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
7
9
  };
10
+ /** Extended set of script extensions for the script asset type */
11
+ export const SCRIPT_EXTENSIONS_BROAD = new Set([
12
+ ...SCRIPT_EXTENSIONS,
13
+ ".py", ".rb", ".go", ".pl", ".php", ".lua", ".r", ".swift", ".kt", ".kts",
14
+ ]);
8
15
  export const ASSET_SPECS = {
9
16
  tool: {
10
17
  stashDir: "tools",
@@ -26,6 +33,12 @@ export const ASSET_SPECS = {
26
33
  command: { stashDir: "commands", ...markdownSpec },
27
34
  agent: { stashDir: "agents", ...markdownSpec },
28
35
  knowledge: { stashDir: "knowledge", ...markdownSpec },
36
+ script: {
37
+ stashDir: "scripts",
38
+ isRelevantFile: (fileName) => SCRIPT_EXTENSIONS_BROAD.has(path.extname(fileName).toLowerCase()),
39
+ toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
40
+ toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
41
+ },
29
42
  };
30
43
  export const ASSET_TYPES = Object.keys(ASSET_SPECS);
31
44
  export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
@@ -33,14 +46,20 @@ export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
33
46
  return acc;
34
47
  }, {});
35
48
  export function isRelevantAssetFile(assetType, fileName) {
49
+ const handler = tryGetHandler(assetType);
50
+ if (handler)
51
+ return handler.isRelevantFile(fileName);
36
52
  return ASSET_SPECS[assetType].isRelevantFile(fileName);
37
53
  }
38
54
  export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
55
+ const handler = tryGetHandler(assetType);
56
+ if (handler)
57
+ return handler.toCanonicalName(typeRoot, filePath);
39
58
  return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath);
40
59
  }
41
60
  export function resolveAssetPathFromName(assetType, typeRoot, name) {
61
+ const handler = tryGetHandler(assetType);
62
+ if (handler)
63
+ return handler.toAssetPath(typeRoot, name);
42
64
  return ASSET_SPECS[assetType].toAssetPath(typeRoot, name);
43
65
  }
44
- function toPosix(input) {
45
- return input.replace(/\\/g, "/");
46
- }
@@ -0,0 +1,27 @@
1
+ import type { StashEntry } from "./metadata";
2
+ import type { LocalSearchHit, ShowResponse, KnowledgeView } from "./stash-types";
3
+ export interface ShowInput {
4
+ name: string;
5
+ path: string;
6
+ content: string;
7
+ view?: KnowledgeView;
8
+ stashDirs?: string[];
9
+ }
10
+ export interface AssetTypeHandler {
11
+ /** The type name, e.g. "tool", "script" */
12
+ readonly typeName: string;
13
+ /** Directory inside the stash root, e.g. "tools", "scripts" */
14
+ readonly stashDir: string;
15
+ isRelevantFile(fileName: string): boolean;
16
+ toCanonicalName(typeRoot: string, filePath: string): string | undefined;
17
+ toAssetPath(typeRoot: string, name: string): string;
18
+ buildShowResponse(input: ShowInput): ShowResponse;
19
+ enrichSearchHit?(hit: LocalSearchHit, stashDir: string): void;
20
+ readonly defaultUsageGuide: string[];
21
+ extractTypeMetadata?(entry: StashEntry, file: string, ext: string): void;
22
+ }
23
+ export declare function registerAssetType(handler: AssetTypeHandler): void;
24
+ export declare function getHandler(type: string): AssetTypeHandler;
25
+ export declare function tryGetHandler(type: string): AssetTypeHandler | undefined;
26
+ export declare function getAllHandlers(): AssetTypeHandler[];
27
+ export declare function getRegisteredTypeNames(): string[];
@@ -0,0 +1,33 @@
1
+ // ── Registry ─────────────────────────────────────────────────────────────────
2
+ const handlers = new Map();
3
+ let handlersInitialized = false;
4
+ function ensureHandlersRegistered() {
5
+ if (handlersInitialized)
6
+ return;
7
+ handlersInitialized = true;
8
+ // Import handler registrations
9
+ require("./handlers/index");
10
+ }
11
+ export function registerAssetType(handler) {
12
+ handlers.set(handler.typeName, handler);
13
+ }
14
+ export function getHandler(type) {
15
+ ensureHandlersRegistered();
16
+ const handler = handlers.get(type);
17
+ if (!handler) {
18
+ throw new Error(`Unknown asset type: "${type}"`);
19
+ }
20
+ return handler;
21
+ }
22
+ export function tryGetHandler(type) {
23
+ ensureHandlersRegistered();
24
+ return handlers.get(type);
25
+ }
26
+ export function getAllHandlers() {
27
+ ensureHandlersRegistered();
28
+ return Array.from(handlers.values());
29
+ }
30
+ export function getRegisteredTypeNames() {
31
+ ensureHandlersRegistered();
32
+ return Array.from(handlers.keys());
33
+ }