@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.
Files changed (127) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +54 -352
  3. package/dist/cli.d.ts +14 -0
  4. package/dist/cli.d.ts.map +1 -0
  5. package/dist/cli.js +156 -0
  6. package/dist/cli.js.map +1 -0
  7. package/dist/index.d.ts +8 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +8 -2509
  10. package/dist/index.js.map +1 -0
  11. package/dist/lib/ast/index.d.ts +11 -0
  12. package/dist/lib/ast/index.d.ts.map +1 -0
  13. package/dist/lib/ast/index.js +15 -0
  14. package/dist/lib/ast/index.js.map +1 -0
  15. package/dist/lib/ast/languages.d.ts +55 -0
  16. package/dist/lib/ast/languages.d.ts.map +1 -0
  17. package/dist/lib/ast/languages.js +146 -0
  18. package/dist/lib/ast/languages.js.map +1 -0
  19. package/dist/lib/ast/pattern.d.ts +84 -0
  20. package/dist/lib/ast/pattern.d.ts.map +1 -0
  21. package/dist/lib/ast/pattern.js +268 -0
  22. package/dist/lib/ast/pattern.js.map +1 -0
  23. package/dist/lib/ast/searcher.d.ts +89 -0
  24. package/dist/lib/ast/searcher.d.ts.map +1 -0
  25. package/dist/lib/ast/searcher.js +316 -0
  26. package/dist/lib/ast/searcher.js.map +1 -0
  27. package/dist/lib/ast/types.d.ts +93 -0
  28. package/dist/lib/ast/types.d.ts.map +1 -0
  29. package/dist/lib/ast/types.js +23 -0
  30. package/dist/lib/ast/types.js.map +1 -0
  31. package/dist/lib/commands/callers.d.ts +20 -0
  32. package/dist/lib/commands/callers.d.ts.map +1 -0
  33. package/dist/lib/commands/callers.js +162 -0
  34. package/dist/lib/commands/callers.js.map +1 -0
  35. package/dist/lib/commands/find.d.ts +15 -0
  36. package/dist/lib/commands/find.d.ts.map +1 -0
  37. package/dist/lib/commands/find.js +113 -0
  38. package/dist/lib/commands/find.js.map +1 -0
  39. package/dist/lib/commands/overview.d.ts +6 -0
  40. package/dist/lib/commands/overview.d.ts.map +1 -0
  41. package/dist/lib/commands/overview.js +52 -0
  42. package/dist/lib/commands/overview.js.map +1 -0
  43. package/dist/lib/commands/prime.d.ts +16 -0
  44. package/dist/lib/commands/prime.d.ts.map +1 -0
  45. package/dist/lib/commands/prime.js +168 -0
  46. package/dist/lib/commands/prime.js.map +1 -0
  47. package/dist/lib/commands/search.d.ts +20 -0
  48. package/dist/lib/commands/search.d.ts.map +1 -0
  49. package/dist/lib/commands/search.js +111 -0
  50. package/dist/lib/commands/search.js.map +1 -0
  51. package/dist/lib/errors.d.ts +80 -0
  52. package/dist/lib/errors.d.ts.map +1 -0
  53. package/dist/lib/errors.js +189 -0
  54. package/dist/lib/errors.js.map +1 -0
  55. package/dist/lib/formatters/output.d.ts +5 -0
  56. package/dist/lib/formatters/output.d.ts.map +1 -0
  57. package/dist/lib/formatters/output.js +5 -0
  58. package/dist/lib/formatters/output.js.map +1 -0
  59. package/dist/lib/formatters.d.ts +29 -0
  60. package/dist/lib/formatters.d.ts.map +1 -0
  61. package/dist/lib/formatters.js +141 -0
  62. package/dist/lib/formatters.js.map +1 -0
  63. package/dist/lib/index-tools.d.ts +108 -0
  64. package/dist/lib/index-tools.d.ts.map +1 -0
  65. package/dist/lib/index-tools.js +311 -0
  66. package/dist/lib/index-tools.js.map +1 -0
  67. package/dist/lib/index.d.ts +21 -0
  68. package/dist/lib/index.d.ts.map +1 -0
  69. package/dist/lib/index.js +42 -0
  70. package/dist/lib/index.js.map +1 -0
  71. package/dist/lib/kit-wrapper.d.ts +70 -0
  72. package/dist/lib/kit-wrapper.d.ts.map +1 -0
  73. package/dist/lib/kit-wrapper.js +462 -0
  74. package/dist/lib/kit-wrapper.js.map +1 -0
  75. package/dist/lib/logger.d.ts +28 -0
  76. package/dist/lib/logger.d.ts.map +1 -0
  77. package/dist/lib/logger.js +39 -0
  78. package/dist/lib/logger.js.map +1 -0
  79. package/dist/lib/types.d.ts +179 -0
  80. package/dist/lib/types.d.ts.map +1 -0
  81. package/dist/lib/types.js +48 -0
  82. package/dist/lib/types.js.map +1 -0
  83. package/dist/lib/utils/args.d.ts +40 -0
  84. package/dist/lib/utils/args.d.ts.map +1 -0
  85. package/dist/lib/utils/args.js +58 -0
  86. package/dist/lib/utils/args.js.map +1 -0
  87. package/dist/lib/utils/git.d.ts +23 -0
  88. package/dist/lib/utils/git.d.ts.map +1 -0
  89. package/dist/lib/utils/git.js +50 -0
  90. package/dist/lib/utils/git.js.map +1 -0
  91. package/dist/lib/utils/index-parser.d.ts +155 -0
  92. package/dist/lib/utils/index-parser.d.ts.map +1 -0
  93. package/dist/lib/utils/index-parser.js +252 -0
  94. package/dist/lib/utils/index-parser.js.map +1 -0
  95. package/dist/lib/validators.d.ts +138 -0
  96. package/dist/lib/validators.d.ts.map +1 -0
  97. package/dist/lib/validators.js +302 -0
  98. package/dist/lib/validators.js.map +1 -0
  99. package/dist/mcp/index.d.ts +19 -0
  100. package/dist/mcp/index.d.ts.map +1 -0
  101. package/dist/mcp/index.js +769 -0
  102. package/dist/mcp/index.js.map +1 -0
  103. package/package.json +5 -2
  104. package/src/cli.ts +170 -0
  105. package/src/lib/ast/index.ts +32 -0
  106. package/src/lib/ast/languages.ts +172 -0
  107. package/src/lib/ast/pattern.ts +299 -0
  108. package/src/lib/ast/searcher.ts +381 -0
  109. package/src/lib/ast/types.ts +99 -0
  110. package/src/lib/commands/callers.ts +226 -0
  111. package/src/lib/commands/find.ts +159 -0
  112. package/src/lib/commands/overview.ts +73 -0
  113. package/src/lib/commands/prime.ts +271 -0
  114. package/src/lib/commands/search.ts +146 -0
  115. package/src/lib/errors.ts +221 -0
  116. package/src/lib/formatters/output.ts +9 -0
  117. package/src/lib/formatters.ts +189 -0
  118. package/src/lib/index-tools.ts +471 -0
  119. package/src/lib/index.ts +122 -0
  120. package/src/lib/kit-wrapper.ts +675 -0
  121. package/src/lib/logger.ts +57 -0
  122. package/src/lib/types.ts +228 -0
  123. package/src/lib/utils/args.ts +72 -0
  124. package/src/lib/utils/git.ts +65 -0
  125. package/src/lib/utils/index-parser.ts +350 -0
  126. package/src/lib/validators.ts +437 -0
  127. 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
- # bun-typescript-starter
1
+ # @side-quest/kit
2
2
 
3
- Modern TypeScript starter template with enterprise-grade tooling.
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
- ## Features
5
+ Uses PROJECT_INDEX.json for up to 50x token savings compared to reading full source files.
6
6
 
7
- - **Bun** - Fast all-in-one JavaScript runtime and toolkit
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
- ## Quick Start
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
- # If you have NPM_TOKEN in your environment
167
- echo "$NPM_TOKEN" | gh secret set NPM_TOKEN --repo myusername/my-lib
12
+ # Basic installation
13
+ uv tool install cased-kit
168
14
 
169
- # Or set it interactively
170
- gh secret set NPM_TOKEN --repo myusername/my-lib
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
- ### Step 5: Create Initial Release
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
- # Check your package
211
- npm view @myusername/my-lib
22
+ npm install @side-quest/kit
212
23
  ```
213
24
 
214
- ### Step 7: Configure OIDC Trusted Publishing (Optional)
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
- ### Why Granular Tokens?
27
+ Add to your Claude Code MCP config:
232
28
 
233
- As of December 2024, npm has revoked all classic tokens. You must use **granular access tokens** for CI/CD publishing.
234
-
235
- ### Token Requirements
236
-
237
- | Setting | Value | Why |
238
- |---------|-------|-----|
239
- | Type | Granular Access Token | Classic tokens no longer work |
240
- | Packages | All packages (for new) or specific | Allows publishing |
241
- | Permissions | Read and write | Required to publish |
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
- ## Project Structure
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
- ## Configuration
44
+ Generate or refresh the PROJECT_INDEX.json file for a repository. Run this first to enable token-efficient symbol lookup.
318
45
 
319
- ### Biome
46
+ ### kit_find
320
47
 
321
- Configured in `biome.json`:
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
- ### TypeScript
50
+ ### kit_references
328
51
 
329
- - Strict mode enabled
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
- ### Changesets
54
+ ### kit_semantic
334
55
 
335
- - GitHub changelog format
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
- ## Branch Protection
58
+ ### kit_ast_search
340
59
 
341
- The setup script automatically configures branch protection for `main`:
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
- - Require pull request before merging
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
- If you need to manually configure it:
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
- 1. Go to Settings → Branches → Add rule
352
- 2. Branch name pattern: `main`
353
- 3. Enable the settings above
66
+ ### kit_chunk
354
67
 
355
- ## Troubleshooting
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
- ### Setup script hangs
72
+ ## CLI
358
73
 
359
- If running in a non-TTY environment (like some CI systems), use CLI flags:
74
+ The package also includes a CLI for direct terminal usage:
360
75
 
361
76
  ```bash
362
- bun run setup -- --name "my-lib" --description "desc" --author "name" --yes
363
- ```
77
+ # Generate index
78
+ side-quest-kit prime [path]
364
79
 
365
- ### CI can't create PRs
80
+ # Find symbols
81
+ side-quest-kit find <symbol> [--format json|markdown]
366
82
 
367
- The setup script enables this automatically. If you need to do it manually:
83
+ # Search semantically
84
+ side-quest-kit search <query> [--top-k 10]
368
85
 
369
- ```bash
370
- gh api repos/OWNER/REPO/actions/permissions/workflow \
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
- ### Version PR checks don't run
377
-
378
- Bot-created PRs don't trigger workflows. Push an empty commit:
90
+ ## Development
379
91
 
380
92
  ```bash
381
- git fetch origin
382
- git checkout changeset-release/main
383
- git commit --allow-empty -m "chore: trigger CI"
384
- git push
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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * @side-quest/kit
3
+ *
4
+ * Kit CLI integration for intelligent code search - MCP server with 7 tools
5
+ * for token-efficient codebase navigation.
6
+ */
7
+ export * from './lib/index.js';
8
+ //# sourceMappingURL=index.d.ts.map