@side-quest/kit 0.0.0 → 0.2.0
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.
- package/CHANGELOG.md +36 -0
- package/README.md +54 -352
- package/dist/cli.d.ts +14 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +156 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +8 -2509
- package/dist/index.js.map +1 -0
- package/dist/lib/ast/index.d.ts +11 -0
- package/dist/lib/ast/index.d.ts.map +1 -0
- package/dist/lib/ast/index.js +15 -0
- package/dist/lib/ast/index.js.map +1 -0
- package/dist/lib/ast/languages.d.ts +55 -0
- package/dist/lib/ast/languages.d.ts.map +1 -0
- package/dist/lib/ast/languages.js +146 -0
- package/dist/lib/ast/languages.js.map +1 -0
- package/dist/lib/ast/pattern.d.ts +84 -0
- package/dist/lib/ast/pattern.d.ts.map +1 -0
- package/dist/lib/ast/pattern.js +268 -0
- package/dist/lib/ast/pattern.js.map +1 -0
- package/dist/lib/ast/searcher.d.ts +89 -0
- package/dist/lib/ast/searcher.d.ts.map +1 -0
- package/dist/lib/ast/searcher.js +316 -0
- package/dist/lib/ast/searcher.js.map +1 -0
- package/dist/lib/ast/types.d.ts +93 -0
- package/dist/lib/ast/types.d.ts.map +1 -0
- package/dist/lib/ast/types.js +23 -0
- package/dist/lib/ast/types.js.map +1 -0
- package/dist/lib/commands/callers.d.ts +20 -0
- package/dist/lib/commands/callers.d.ts.map +1 -0
- package/dist/lib/commands/callers.js +162 -0
- package/dist/lib/commands/callers.js.map +1 -0
- package/dist/lib/commands/find.d.ts +15 -0
- package/dist/lib/commands/find.d.ts.map +1 -0
- package/dist/lib/commands/find.js +113 -0
- package/dist/lib/commands/find.js.map +1 -0
- package/dist/lib/commands/overview.d.ts +6 -0
- package/dist/lib/commands/overview.d.ts.map +1 -0
- package/dist/lib/commands/overview.js +52 -0
- package/dist/lib/commands/overview.js.map +1 -0
- package/dist/lib/commands/prime.d.ts +16 -0
- package/dist/lib/commands/prime.d.ts.map +1 -0
- package/dist/lib/commands/prime.js +168 -0
- package/dist/lib/commands/prime.js.map +1 -0
- package/dist/lib/commands/search.d.ts +20 -0
- package/dist/lib/commands/search.d.ts.map +1 -0
- package/dist/lib/commands/search.js +111 -0
- package/dist/lib/commands/search.js.map +1 -0
- package/dist/lib/errors.d.ts +80 -0
- package/dist/lib/errors.d.ts.map +1 -0
- package/dist/lib/errors.js +189 -0
- package/dist/lib/errors.js.map +1 -0
- package/dist/lib/formatters/output.d.ts +5 -0
- package/dist/lib/formatters/output.d.ts.map +1 -0
- package/dist/lib/formatters/output.js +5 -0
- package/dist/lib/formatters/output.js.map +1 -0
- package/dist/lib/formatters.d.ts +29 -0
- package/dist/lib/formatters.d.ts.map +1 -0
- package/dist/lib/formatters.js +141 -0
- package/dist/lib/formatters.js.map +1 -0
- package/dist/lib/index-tools.d.ts +108 -0
- package/dist/lib/index-tools.d.ts.map +1 -0
- package/dist/lib/index-tools.js +311 -0
- package/dist/lib/index-tools.js.map +1 -0
- package/dist/lib/index.d.ts +21 -0
- package/dist/lib/index.d.ts.map +1 -0
- package/dist/lib/index.js +42 -0
- package/dist/lib/index.js.map +1 -0
- package/dist/lib/kit-wrapper.d.ts +70 -0
- package/dist/lib/kit-wrapper.d.ts.map +1 -0
- package/dist/lib/kit-wrapper.js +462 -0
- package/dist/lib/kit-wrapper.js.map +1 -0
- package/dist/lib/logger.d.ts +28 -0
- package/dist/lib/logger.d.ts.map +1 -0
- package/dist/lib/logger.js +39 -0
- package/dist/lib/logger.js.map +1 -0
- package/dist/lib/types.d.ts +179 -0
- package/dist/lib/types.d.ts.map +1 -0
- package/dist/lib/types.js +48 -0
- package/dist/lib/types.js.map +1 -0
- package/dist/lib/utils/args.d.ts +40 -0
- package/dist/lib/utils/args.d.ts.map +1 -0
- package/dist/lib/utils/args.js +58 -0
- package/dist/lib/utils/args.js.map +1 -0
- package/dist/lib/utils/git.d.ts +23 -0
- package/dist/lib/utils/git.d.ts.map +1 -0
- package/dist/lib/utils/git.js +50 -0
- package/dist/lib/utils/git.js.map +1 -0
- package/dist/lib/utils/index-parser.d.ts +155 -0
- package/dist/lib/utils/index-parser.d.ts.map +1 -0
- package/dist/lib/utils/index-parser.js +252 -0
- package/dist/lib/utils/index-parser.js.map +1 -0
- package/dist/lib/validators.d.ts +138 -0
- package/dist/lib/validators.d.ts.map +1 -0
- package/dist/lib/validators.js +302 -0
- package/dist/lib/validators.js.map +1 -0
- package/dist/mcp/index.d.ts +19 -0
- package/dist/mcp/index.d.ts.map +1 -0
- package/dist/mcp/index.js +769 -0
- package/dist/mcp/index.js.map +1 -0
- package/package.json +5 -2
- package/src/cli.ts +170 -0
- package/src/lib/ast/index.ts +32 -0
- package/src/lib/ast/languages.ts +172 -0
- package/src/lib/ast/pattern.ts +299 -0
- package/src/lib/ast/searcher.ts +381 -0
- package/src/lib/ast/types.ts +99 -0
- package/src/lib/commands/callers.ts +226 -0
- package/src/lib/commands/find.ts +159 -0
- package/src/lib/commands/overview.ts +73 -0
- package/src/lib/commands/prime.ts +271 -0
- package/src/lib/commands/search.ts +146 -0
- package/src/lib/errors.ts +221 -0
- package/src/lib/formatters/output.ts +9 -0
- package/src/lib/formatters.ts +189 -0
- package/src/lib/index-tools.ts +471 -0
- package/src/lib/index.ts +122 -0
- package/src/lib/kit-wrapper.ts +675 -0
- package/src/lib/logger.ts +57 -0
- package/src/lib/types.ts +228 -0
- package/src/lib/utils/args.ts +72 -0
- package/src/lib/utils/git.ts +65 -0
- package/src/lib/utils/index-parser.ts +350 -0
- package/src/lib/validators.ts +437 -0
- package/src/mcp/index.ts +144 -79
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,41 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#7](https://github.com/nathanvale/side-quest-kit/pull/7) [`9268c7c`](https://github.com/nathanvale/side-quest-kit/commit/9268c7c1d0b11fc781f7eb371941d8887b309436) Thanks [@nathanvale](https://github.com/nathanvale)! - Initial release of @side-quest/kit - MCP server with 7 tools for token-efficient codebase navigation via the Kit CLI (cased-kit).
|
|
8
|
+
|
|
9
|
+
MCP Tools:
|
|
10
|
+
|
|
11
|
+
- `kit_prime` - Generate/refresh PROJECT_INDEX.json for token-efficient symbol lookup
|
|
12
|
+
- `kit_find` - Symbol lookup and file overview from PROJECT_INDEX.json
|
|
13
|
+
- `kit_references` - Find all references to a symbol (callers + usages)
|
|
14
|
+
- `kit_semantic` - Semantic code search via vector embeddings with grep fallback
|
|
15
|
+
- `kit_ast_search` - Tree-sitter powered structural code search
|
|
16
|
+
- `kit_context` - Extract enclosing definition around a file:line location
|
|
17
|
+
- `kit_chunk` - Split files into LLM-friendly chunks (symbols or lines strategy)
|
|
18
|
+
|
|
19
|
+
### Patch Changes
|
|
20
|
+
|
|
21
|
+
- [#10](https://github.com/nathanvale/side-quest-kit/pull/10) [`9bf7a7f`](https://github.com/nathanvale/side-quest-kit/commit/9bf7a7f529f9293bb1eab3986c55c56c64ea1e77) Thanks [@nathanvale](https://github.com/nathanvale)! - Sync CI/CD improvements from upstream bun-typescript-starter template
|
|
22
|
+
|
|
23
|
+
## 0.1.0
|
|
24
|
+
|
|
25
|
+
### Minor Changes
|
|
26
|
+
|
|
27
|
+
- [#5](https://github.com/nathanvale/side-quest-kit/pull/5) [`279b000`](https://github.com/nathanvale/side-quest-kit/commit/279b0004159b2787cbf38c834f748498d98a21c0) Thanks [@nathanvale](https://github.com/nathanvale)! - Initial release of @side-quest/kit - MCP server with 7 tools for token-efficient codebase navigation.
|
|
28
|
+
|
|
29
|
+
Tools included:
|
|
30
|
+
|
|
31
|
+
- `kit_grep` - fast regex search across files
|
|
32
|
+
- `kit_files` - glob-based file discovery
|
|
33
|
+
- `kit_semantic` - semantic code search via embeddings
|
|
34
|
+
- `kit_symbols` - AST-powered symbol extraction
|
|
35
|
+
- `kit_callers` - find callers of a function/method
|
|
36
|
+
- `kit_context` - retrieve file context around a location
|
|
37
|
+
- `kit_index_find` - query the kit index for matches
|
|
38
|
+
|
|
3
39
|
All notable changes to this project will be documented in this file.
|
|
4
40
|
|
|
5
41
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
package/README.md
CHANGED
|
@@ -1,399 +1,101 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @side-quest/kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MCP server with 7 tools for token-efficient codebase navigation using the [Kit CLI](https://github.com/cased/kit) (cased-kit).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Uses PROJECT_INDEX.json for up to 50x token savings compared to reading full source files.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **TypeScript 5.9+** - Strict mode, ESM only
|
|
9
|
-
- **Biome** - Lightning-fast linting and formatting (replaces ESLint + Prettier)
|
|
10
|
-
- **Vitest** - Fast unit testing with native Bun support
|
|
11
|
-
- **Changesets** - Automated versioning and changelog generation
|
|
12
|
-
- **GitHub Actions** - Comprehensive CI/CD with OIDC npm publishing
|
|
13
|
-
- **Conventional Commits** - Enforced via commitlint + Husky
|
|
7
|
+
## Prerequisites
|
|
14
8
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
### Prerequisites
|
|
18
|
-
|
|
19
|
-
- [Bun](https://bun.sh) installed (`curl -fsSL https://bun.sh/install | bash`)
|
|
20
|
-
- [GitHub CLI](https://cli.github.com) installed and authenticated (`gh auth login`)
|
|
21
|
-
- [npm account](https://www.npmjs.com) with a granular access token (see [NPM Token Setup](#npm-token-setup))
|
|
22
|
-
|
|
23
|
-
### Option A: GitHub CLI (Recommended)
|
|
24
|
-
|
|
25
|
-
Create a new repo from this template and set it up in one command:
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
# Create repo from template
|
|
29
|
-
gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
|
|
30
|
-
|
|
31
|
-
# Run setup (interactive)
|
|
32
|
-
cd my-lib
|
|
33
|
-
bun run setup
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
### Option B: CLI Mode (Non-Interactive)
|
|
37
|
-
|
|
38
|
-
For automated/scripted setups, pass all arguments via CLI flags:
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
# Create repo from template
|
|
42
|
-
gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
|
|
43
|
-
cd my-lib
|
|
44
|
-
|
|
45
|
-
# Run setup with all arguments (no prompts)
|
|
46
|
-
bun run setup -- \
|
|
47
|
-
--name "@myusername/my-lib" \
|
|
48
|
-
--description "My awesome library" \
|
|
49
|
-
--author "Your Name" \
|
|
50
|
-
--yes
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### Option C: degit
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
npx degit nathanvale/bun-typescript-starter my-lib
|
|
57
|
-
cd my-lib
|
|
58
|
-
bun run setup
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## Setup Script
|
|
62
|
-
|
|
63
|
-
The setup script configures your project and optionally creates the GitHub repository with all settings pre-configured.
|
|
64
|
-
|
|
65
|
-
### Interactive Mode
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
bun run setup
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
Prompts for:
|
|
72
|
-
- Package name (e.g., `@myusername/my-lib` or `my-lib`)
|
|
73
|
-
- Repository name
|
|
74
|
-
- GitHub username/org
|
|
75
|
-
- Project description
|
|
76
|
-
- Author name
|
|
77
|
-
|
|
78
|
-
### CLI Mode
|
|
79
|
-
|
|
80
|
-
```bash
|
|
81
|
-
bun run setup -- [options]
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
| Flag | Short | Description |
|
|
85
|
-
|------|-------|-------------|
|
|
86
|
-
| `--name` | `-n` | Package name (e.g., `@myusername/my-lib`) |
|
|
87
|
-
| `--repo` | `-r` | Repository name (defaults to package name) |
|
|
88
|
-
| `--user` | `-u` | GitHub username/org (auto-detected from `gh`) |
|
|
89
|
-
| `--description` | `-d` | Project description |
|
|
90
|
-
| `--author` | `-a` | Author name |
|
|
91
|
-
| `--yes` | `-y` | Skip confirmation prompts (auto-yes) |
|
|
92
|
-
| `--no-github` | | Skip GitHub repo creation/configuration |
|
|
93
|
-
| `--help` | `-h` | Show help |
|
|
94
|
-
|
|
95
|
-
### What Setup Does
|
|
96
|
-
|
|
97
|
-
1. **Configures files** - Replaces placeholders in `package.json` and `.changeset/config.json`
|
|
98
|
-
2. **Installs dependencies** - Runs `bun install`
|
|
99
|
-
3. **Creates initial commit** - Commits all configured files
|
|
100
|
-
4. **Creates GitHub repo** (if it doesn't exist) - Uses `gh repo create`
|
|
101
|
-
5. **Configures GitHub settings**:
|
|
102
|
-
- Enables workflow permissions for PR creation
|
|
103
|
-
- Sets squash-only merging
|
|
104
|
-
- Enables auto-delete branches
|
|
105
|
-
- Enables auto-merge
|
|
106
|
-
- Configures branch protection rules
|
|
107
|
-
|
|
108
|
-
## Complete Setup Guide
|
|
109
|
-
|
|
110
|
-
This guide walks through the full process of creating a new package and publishing it to npm.
|
|
111
|
-
|
|
112
|
-
### Step 1: Create Repository
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
# Create and clone from template
|
|
116
|
-
gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
|
|
117
|
-
cd my-lib
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
### Step 2: Run Setup
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
# Interactive mode
|
|
124
|
-
bun run setup
|
|
125
|
-
|
|
126
|
-
# Or non-interactive mode
|
|
127
|
-
bun run setup -- \
|
|
128
|
-
--name "@myusername/my-lib" \
|
|
129
|
-
--description "My awesome library" \
|
|
130
|
-
--author "Your Name" \
|
|
131
|
-
--yes
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
### Step 3: Install Changeset Bot
|
|
135
|
-
|
|
136
|
-
Install the [Changeset Bot](https://github.com/apps/changeset-bot) GitHub App on your repo. It comments on every PR with changeset status so you know at a glance whether version bumps are queued.
|
|
137
|
-
|
|
138
|
-
1. Visit https://github.com/apps/changeset-bot
|
|
139
|
-
2. Click **Install** and select your repository
|
|
140
|
-
3. Grant the requested permissions (pull request read/write, contents read-only)
|
|
141
|
-
|
|
142
|
-
> The bot works alongside the `autogenerate-changeset.yml` workflow — the bot comments instantly, and the workflow auto-generates a changeset file if one is missing.
|
|
143
|
-
|
|
144
|
-
### Step 4: Configure NPM Token
|
|
145
|
-
|
|
146
|
-
Before publishing, you need to add your npm token to GitHub secrets.
|
|
147
|
-
|
|
148
|
-
#### Create npm Granular Access Token
|
|
149
|
-
|
|
150
|
-
1. Go to [npmjs.com](https://www.npmjs.com) → Access Tokens → Generate New Token → **Granular Access Token**
|
|
151
|
-
|
|
152
|
-
2. Configure the token:
|
|
153
|
-
- **Token name:** `github-actions-publish` (or any name)
|
|
154
|
-
- **Expiration:** 90 days (maximum for granular tokens)
|
|
155
|
-
- **Packages and scopes:** Select "All packages" for new packages, or specific packages for existing ones
|
|
156
|
-
- **Permissions:** Read and write
|
|
157
|
-
- **IMPORTANT:** Check **"Bypass two-factor authentication for automation"**
|
|
158
|
-
|
|
159
|
-
> Without "Bypass 2FA", CI/CD publishing will fail with "Access token expired or revoked"
|
|
160
|
-
|
|
161
|
-
3. Copy the token (starts with `npm_`)
|
|
162
|
-
|
|
163
|
-
#### Add Token to GitHub Secrets
|
|
9
|
+
Install the Kit CLI:
|
|
164
10
|
|
|
165
11
|
```bash
|
|
166
|
-
#
|
|
167
|
-
|
|
12
|
+
# Basic installation
|
|
13
|
+
uv tool install cased-kit
|
|
168
14
|
|
|
169
|
-
#
|
|
170
|
-
|
|
171
|
-
# Paste your token when prompted
|
|
15
|
+
# With ML dependencies (required for semantic search)
|
|
16
|
+
uv tool install 'cased-kit[ml]'
|
|
172
17
|
```
|
|
173
18
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
Create a changeset describing your initial release:
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
# Create a feature branch
|
|
180
|
-
git checkout -b feat/initial-release
|
|
181
|
-
|
|
182
|
-
# Create changeset file
|
|
183
|
-
mkdir -p .changeset
|
|
184
|
-
cat > .changeset/initial-release.md << 'EOF'
|
|
185
|
-
---
|
|
186
|
-
"@myusername/my-lib": minor
|
|
187
|
-
---
|
|
188
|
-
|
|
189
|
-
Initial release
|
|
190
|
-
EOF
|
|
191
|
-
|
|
192
|
-
# Commit and push
|
|
193
|
-
git add .changeset/initial-release.md
|
|
194
|
-
git commit -m "chore: add changeset for initial release"
|
|
195
|
-
git push -u origin feat/initial-release
|
|
196
|
-
|
|
197
|
-
# Create PR
|
|
198
|
-
gh pr create --title "chore: add changeset for initial release" --body "Initial release"
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
### Step 6: Merge and Publish
|
|
202
|
-
|
|
203
|
-
1. **Wait for CI checks** to pass on your PR
|
|
204
|
-
2. **Merge the PR** - This triggers the changesets workflow
|
|
205
|
-
3. **A "Version Packages" PR** will be automatically created
|
|
206
|
-
4. **Merge the Version PR** - This triggers the publish workflow
|
|
207
|
-
5. **Package is published to npm!**
|
|
19
|
+
## Installation
|
|
208
20
|
|
|
209
21
|
```bash
|
|
210
|
-
|
|
211
|
-
npm view @myusername/my-lib
|
|
22
|
+
npm install @side-quest/kit
|
|
212
23
|
```
|
|
213
24
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
After the first publish, you can enable token-free publishing via OIDC:
|
|
217
|
-
|
|
218
|
-
1. Go to [npmjs.com](https://www.npmjs.com) → Your Package → Settings → Publishing Access
|
|
219
|
-
2. Click "Add Trusted Publisher"
|
|
220
|
-
3. Configure:
|
|
221
|
-
- **Owner:** Your GitHub username/org
|
|
222
|
-
- **Repository:** Your repo name
|
|
223
|
-
- **Workflow file:** `publish.yml`
|
|
224
|
-
4. Save changes
|
|
225
|
-
5. Optionally remove the `NPM_TOKEN` secret from GitHub
|
|
226
|
-
|
|
227
|
-
Now future releases will publish automatically without any tokens!
|
|
228
|
-
|
|
229
|
-
## NPM Token Setup
|
|
25
|
+
## MCP Server Configuration
|
|
230
26
|
|
|
231
|
-
|
|
27
|
+
Add to your Claude Code MCP config:
|
|
232
28
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
| **Bypass 2FA** | **Checked** | **Required for CI/CD** |
|
|
243
|
-
|
|
244
|
-
### Common Errors
|
|
245
|
-
|
|
246
|
-
| Error | Cause | Fix |
|
|
247
|
-
|-------|-------|-----|
|
|
248
|
-
| "Access token expired or revoked" | Token doesn't have "Bypass 2FA" | Create new token with 2FA bypass |
|
|
249
|
-
| "E404 Not Found" | Token doesn't have publish permissions | Check token has read/write access |
|
|
250
|
-
| "E403 Forbidden" | Package scope mismatch | Ensure token covers your package scope |
|
|
251
|
-
|
|
252
|
-
## What's Included
|
|
253
|
-
|
|
254
|
-
### CI/CD Workflows
|
|
255
|
-
|
|
256
|
-
| Workflow | Trigger | Purpose |
|
|
257
|
-
|----------|---------|---------|
|
|
258
|
-
| `pr-quality.yml` | PR | Lint, Typecheck, Test with coverage |
|
|
259
|
-
| `publish.yml` | Push to main | Auto-publish via Changesets |
|
|
260
|
-
| `autogenerate-changeset.yml` | PR | Auto-generate changeset if missing |
|
|
261
|
-
| `commitlint.yml` | PR | Enforce conventional commits |
|
|
262
|
-
| `pr-title.yml` | PR | Validate PR title format |
|
|
263
|
-
| `security.yml` | Push/Schedule | CodeQL + Trivy scanning |
|
|
264
|
-
| `dependency-review.yml` | PR | Supply chain security |
|
|
265
|
-
| `dependabot-auto-merge.yml` | Dependabot PR | Auto-merge patch updates |
|
|
266
|
-
|
|
267
|
-
### GitHub Apps
|
|
268
|
-
|
|
269
|
-
| App | Purpose |
|
|
270
|
-
|-----|---------|
|
|
271
|
-
| [Changeset Bot](https://github.com/apps/changeset-bot) | PR comments with changeset status |
|
|
272
|
-
|
|
273
|
-
### Scripts
|
|
274
|
-
|
|
275
|
-
```bash
|
|
276
|
-
# Development
|
|
277
|
-
bun dev # Watch mode
|
|
278
|
-
bun run build # Build for production
|
|
279
|
-
bun run clean # Remove dist/
|
|
280
|
-
|
|
281
|
-
# Quality
|
|
282
|
-
bun run check # Biome lint + format (write)
|
|
283
|
-
bun run lint # Lint only
|
|
284
|
-
bun run format # Format only
|
|
285
|
-
bun run typecheck # TypeScript type check
|
|
286
|
-
bun run validate # Full quality check (lint + types + build + test)
|
|
287
|
-
|
|
288
|
-
# Testing
|
|
289
|
-
bun test # Run tests
|
|
290
|
-
bun test --watch # Watch mode
|
|
291
|
-
bun run coverage # With coverage report
|
|
292
|
-
|
|
293
|
-
# Publishing
|
|
294
|
-
bun run version:gen # Create changeset interactively
|
|
295
|
-
bun run release # Publish to npm (CI handles this)
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"mcpServers": {
|
|
32
|
+
"kit": {
|
|
33
|
+
"command": "bunx",
|
|
34
|
+
"args": ["--bun", "@side-quest/kit"]
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
296
38
|
```
|
|
297
39
|
|
|
298
|
-
##
|
|
40
|
+
## MCP Tools
|
|
299
41
|
|
|
300
|
-
|
|
301
|
-
├── .github/
|
|
302
|
-
│ ├── workflows/ # CI/CD workflows
|
|
303
|
-
│ ├── actions/ # Reusable composite actions
|
|
304
|
-
│ └── scripts/ # CI helper scripts
|
|
305
|
-
├── .husky/ # Git hooks
|
|
306
|
-
├── .changeset/ # Changeset config
|
|
307
|
-
├── src/
|
|
308
|
-
│ └── index.ts # Main entry point
|
|
309
|
-
├── tests/
|
|
310
|
-
│ └── index.test.ts # Example test
|
|
311
|
-
├── biome.json # Biome config
|
|
312
|
-
├── tsconfig.json # TypeScript config
|
|
313
|
-
├── bunup.config.ts # Build config
|
|
314
|
-
└── package.json
|
|
315
|
-
```
|
|
42
|
+
### kit_prime
|
|
316
43
|
|
|
317
|
-
|
|
44
|
+
Generate or refresh the PROJECT_INDEX.json file for a repository. Run this first to enable token-efficient symbol lookup.
|
|
318
45
|
|
|
319
|
-
###
|
|
46
|
+
### kit_find
|
|
320
47
|
|
|
321
|
-
|
|
322
|
-
- Tab indentation
|
|
323
|
-
- 80 character line width
|
|
324
|
-
- Single quotes
|
|
325
|
-
- Organize imports on save
|
|
48
|
+
Look up symbol definitions or get an overview of all symbols in a file from the PROJECT_INDEX.json index. Supports exact and fuzzy matching.
|
|
326
49
|
|
|
327
|
-
###
|
|
50
|
+
### kit_references
|
|
328
51
|
|
|
329
|
-
-
|
|
330
|
-
- ESM output
|
|
331
|
-
- Source maps and declarations
|
|
52
|
+
Find all references to a symbol - callers, usages, or both. Supports three modes: `all`, `callers_only`, and `definitions_only`.
|
|
332
53
|
|
|
333
|
-
###
|
|
54
|
+
### kit_semantic
|
|
334
55
|
|
|
335
|
-
-
|
|
336
|
-
- Public npm access
|
|
337
|
-
- Provenance enabled
|
|
56
|
+
Semantic code search using vector embeddings. Falls back to grep-based search if the ML index is not available. Supports `chunk_by` parameter for different chunking strategies.
|
|
338
57
|
|
|
339
|
-
|
|
58
|
+
### kit_ast_search
|
|
340
59
|
|
|
341
|
-
|
|
60
|
+
Structural code search using Tree-sitter AST parsing. Search for patterns like "async functions that call fetch" or specific code structures using `simple` or `pattern` mode.
|
|
342
61
|
|
|
343
|
-
|
|
344
|
-
- Require status checks to pass ("All checks passed")
|
|
345
|
-
- Require linear history
|
|
346
|
-
- No force pushes
|
|
347
|
-
- No deletions
|
|
62
|
+
### kit_context
|
|
348
63
|
|
|
349
|
-
|
|
64
|
+
Extract the full enclosing definition (function, class, method) around a specific file and line number. Useful for getting complete context without reading entire files.
|
|
350
65
|
|
|
351
|
-
|
|
352
|
-
2. Branch name pattern: `main`
|
|
353
|
-
3. Enable the settings above
|
|
66
|
+
### kit_chunk
|
|
354
67
|
|
|
355
|
-
|
|
68
|
+
Split a source file into LLM-friendly chunks. Supports two strategies:
|
|
69
|
+
- `symbols` - chunk at function/class boundaries (default)
|
|
70
|
+
- `lines` - chunk by line count with configurable `max_lines`
|
|
356
71
|
|
|
357
|
-
|
|
72
|
+
## CLI
|
|
358
73
|
|
|
359
|
-
|
|
74
|
+
The package also includes a CLI for direct terminal usage:
|
|
360
75
|
|
|
361
76
|
```bash
|
|
362
|
-
|
|
363
|
-
|
|
77
|
+
# Generate index
|
|
78
|
+
side-quest-kit prime [path]
|
|
364
79
|
|
|
365
|
-
|
|
80
|
+
# Find symbols
|
|
81
|
+
side-quest-kit find <symbol> [--format json|markdown]
|
|
366
82
|
|
|
367
|
-
|
|
83
|
+
# Search semantically
|
|
84
|
+
side-quest-kit search <query> [--top-k 10]
|
|
368
85
|
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
--method PUT \
|
|
372
|
-
-f default_workflow_permissions=write \
|
|
373
|
-
-F can_approve_pull_request_reviews=true
|
|
86
|
+
# Find callers
|
|
87
|
+
side-quest-kit callers <symbol> [--format json|markdown]
|
|
374
88
|
```
|
|
375
89
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
Bot-created PRs don't trigger workflows. Push an empty commit:
|
|
90
|
+
## Development
|
|
379
91
|
|
|
380
92
|
```bash
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
93
|
+
bun install
|
|
94
|
+
bun test
|
|
95
|
+
bun run build
|
|
96
|
+
bun run validate # Full quality check (lint + types + build + test)
|
|
385
97
|
```
|
|
386
98
|
|
|
387
|
-
### npm publish fails with 404
|
|
388
|
-
|
|
389
|
-
1. Ensure your npm token has "Bypass 2FA" checked
|
|
390
|
-
2. Ensure token has "Read and write" permissions
|
|
391
|
-
3. Ensure token covers "All packages" (for new packages)
|
|
392
|
-
|
|
393
99
|
## License
|
|
394
100
|
|
|
395
101
|
MIT
|
|
396
|
-
|
|
397
|
-
---
|
|
398
|
-
|
|
399
|
-
Built with [bun-typescript-starter](https://github.com/nathanvale/bun-typescript-starter)
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Kit Index CLI
|
|
4
|
+
*
|
|
5
|
+
* Command-line interface for PROJECT_INDEX.json management.
|
|
6
|
+
* Centralizes all index operations with dual output formats (markdown/JSON).
|
|
7
|
+
*
|
|
8
|
+
* Usage:
|
|
9
|
+
* bun run src/cli.ts <command> [args] [--format md|json]
|
|
10
|
+
*
|
|
11
|
+
* Based on cinema-bandit CLI architecture pattern.
|
|
12
|
+
*/
|
|
13
|
+
export {};
|
|
14
|
+
//# sourceMappingURL=cli.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Kit Index CLI
|
|
4
|
+
*
|
|
5
|
+
* Command-line interface for PROJECT_INDEX.json management.
|
|
6
|
+
* Centralizes all index operations with dual output formats (markdown/JSON).
|
|
7
|
+
*
|
|
8
|
+
* Usage:
|
|
9
|
+
* bun run src/cli.ts <command> [args] [--format md|json]
|
|
10
|
+
*
|
|
11
|
+
* Based on cinema-bandit CLI architecture pattern.
|
|
12
|
+
*/
|
|
13
|
+
import { parseOutputFormat } from './lib/formatters/output';
|
|
14
|
+
import { parseArgs } from './lib/utils/args';
|
|
15
|
+
function printUsage() {
|
|
16
|
+
console.log(`
|
|
17
|
+
Kit Index CLI - PROJECT_INDEX.json Management
|
|
18
|
+
|
|
19
|
+
Usage:
|
|
20
|
+
bun run src/cli.ts prime [path] [--force] [--format md|json]
|
|
21
|
+
bun run src/cli.ts find <symbol> [--format md|json]
|
|
22
|
+
bun run src/cli.ts overview <file> [--format md|json]
|
|
23
|
+
bun run src/cli.ts search <query> [--path <dir>] [--top-k N] [--chunk-by symbols|lines] [--build-index] [--format md|json]
|
|
24
|
+
bun run src/cli.ts callers <function> [--format md|json]
|
|
25
|
+
|
|
26
|
+
Commands:
|
|
27
|
+
prime Generate/refresh PROJECT_INDEX.json
|
|
28
|
+
Args: [path] - Optional directory to index (defaults to git root or CWD)
|
|
29
|
+
Options: --force (regenerate even if < 24h old)
|
|
30
|
+
|
|
31
|
+
find Find symbol definitions by name
|
|
32
|
+
Args: <symbol> - Symbol name to search for
|
|
33
|
+
|
|
34
|
+
overview List all symbols in a file
|
|
35
|
+
Args: <file> - File path (relative or absolute)
|
|
36
|
+
|
|
37
|
+
search Semantic search using natural language
|
|
38
|
+
Args: <query> - Natural language search query
|
|
39
|
+
Options:
|
|
40
|
+
--path <dir> - Directory to search (default: git root)
|
|
41
|
+
--top-k <N> - Number of results (default: 5)
|
|
42
|
+
--chunk-by <mode> - Chunking strategy: symbols|lines (default: symbols)
|
|
43
|
+
--build-index - Force rebuild vector index
|
|
44
|
+
|
|
45
|
+
callers Find who calls a function (call sites)
|
|
46
|
+
Args: <function> - Function name to analyze
|
|
47
|
+
|
|
48
|
+
Options:
|
|
49
|
+
--format <type> Output format: "md" (default) or "json"
|
|
50
|
+
Markdown is human-readable with colors
|
|
51
|
+
JSON is machine-readable for parsing
|
|
52
|
+
|
|
53
|
+
--force Force regenerate (prime command only)
|
|
54
|
+
--help Show this help message
|
|
55
|
+
|
|
56
|
+
Examples:
|
|
57
|
+
# Generate index at git root
|
|
58
|
+
bun run src/cli.ts prime
|
|
59
|
+
|
|
60
|
+
# Generate index for specific directory
|
|
61
|
+
bun run src/cli.ts prime /path/to/project
|
|
62
|
+
|
|
63
|
+
# Force regenerate
|
|
64
|
+
bun run src/cli.ts prime --force
|
|
65
|
+
|
|
66
|
+
# Find symbol
|
|
67
|
+
bun run src/cli.ts find MyFunction
|
|
68
|
+
|
|
69
|
+
# Get file overview
|
|
70
|
+
bun run src/cli.ts overview src/index.ts
|
|
71
|
+
|
|
72
|
+
# Find callers with JSON output
|
|
73
|
+
bun run src/cli.ts callers executeFind --format json
|
|
74
|
+
`);
|
|
75
|
+
}
|
|
76
|
+
async function main() {
|
|
77
|
+
const args = process.argv.slice(2);
|
|
78
|
+
// Show help if no args or --help flag
|
|
79
|
+
if (args.length === 0 || args.includes('--help')) {
|
|
80
|
+
printUsage();
|
|
81
|
+
process.exit(0);
|
|
82
|
+
}
|
|
83
|
+
const { command, positional, flags } = parseArgs(args);
|
|
84
|
+
const format = parseOutputFormat(flags.format);
|
|
85
|
+
try {
|
|
86
|
+
switch (command) {
|
|
87
|
+
case 'prime': {
|
|
88
|
+
const path = positional[0]; // Optional path argument
|
|
89
|
+
const { executePrime } = await import('./lib/commands/prime');
|
|
90
|
+
await executePrime(flags.force === 'true', format, path);
|
|
91
|
+
break;
|
|
92
|
+
}
|
|
93
|
+
case 'find': {
|
|
94
|
+
const symbol = positional[0];
|
|
95
|
+
if (!symbol) {
|
|
96
|
+
console.error('Error: <symbol> required for find command');
|
|
97
|
+
console.error('Usage: bun run src/cli.ts find <symbol>');
|
|
98
|
+
process.exit(1);
|
|
99
|
+
}
|
|
100
|
+
const { executeFind } = await import('./lib/commands/find');
|
|
101
|
+
await executeFind(symbol, format);
|
|
102
|
+
break;
|
|
103
|
+
}
|
|
104
|
+
case 'overview': {
|
|
105
|
+
const file = positional[0];
|
|
106
|
+
if (!file) {
|
|
107
|
+
console.error('Error: <file> required for overview command');
|
|
108
|
+
console.error('Usage: bun run src/cli.ts overview <file>');
|
|
109
|
+
process.exit(1);
|
|
110
|
+
}
|
|
111
|
+
const { executeOverview } = await import('./lib/commands/overview');
|
|
112
|
+
await executeOverview(file, format);
|
|
113
|
+
break;
|
|
114
|
+
}
|
|
115
|
+
case 'search': {
|
|
116
|
+
const query = positional[0];
|
|
117
|
+
if (!query) {
|
|
118
|
+
console.error('Error: <query> required for search command');
|
|
119
|
+
console.error('Usage: bun run src/cli.ts search <query> [options]');
|
|
120
|
+
process.exit(1);
|
|
121
|
+
}
|
|
122
|
+
const { executeSearch } = await import('./lib/commands/search');
|
|
123
|
+
// Parse options
|
|
124
|
+
const options = {
|
|
125
|
+
path: flags.path,
|
|
126
|
+
topK: flags['top-k'] ? Number(flags['top-k']) : undefined,
|
|
127
|
+
chunkBy: flags['chunk-by'],
|
|
128
|
+
buildIndex: flags['build-index'] === 'true',
|
|
129
|
+
};
|
|
130
|
+
await executeSearch(query, options, format);
|
|
131
|
+
break;
|
|
132
|
+
}
|
|
133
|
+
case 'callers': {
|
|
134
|
+
const functionName = positional[0];
|
|
135
|
+
if (!functionName) {
|
|
136
|
+
console.error('Error: <function> required for callers command');
|
|
137
|
+
console.error('Usage: bun run src/cli.ts callers <function>');
|
|
138
|
+
process.exit(1);
|
|
139
|
+
}
|
|
140
|
+
const { executeCallers } = await import('./lib/commands/callers');
|
|
141
|
+
await executeCallers(functionName, format);
|
|
142
|
+
break;
|
|
143
|
+
}
|
|
144
|
+
default:
|
|
145
|
+
console.error(`Unknown command: ${command}`);
|
|
146
|
+
console.error("Run 'bun run src/cli.ts --help' for usage");
|
|
147
|
+
process.exit(1);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
catch (error) {
|
|
151
|
+
console.error('Error:', error instanceof Error ? error.message : error);
|
|
152
|
+
process.exit(1);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
main();
|
|
156
|
+
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|