@constellationdev/cli 0.1.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/LICENSE +662 -0
- package/README.md +287 -0
- package/dist/index.js +152 -0
- package/package.json +101 -0
package/README.md
ADDED
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
# Constellation CLI
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@constellationdev/cli) [](https://github.com/ShiftinBits/constellation-mcp)   [](LICENSE)
|
|
4
|
+
|
|
5
|
+
[Installation](#installation) •
|
|
6
|
+
[Quick Start](#quick-start) •
|
|
7
|
+
[Commands](#commands) •
|
|
8
|
+
[Configuration](#configuration)
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
The Constellation CLI parses your source code locally using Tree-sitter and uploads Abstract Syntax Tree (AST) metadata to the Constellation service. This creates a shared code intelligence graph that powers AI development tools via the Constellation MCP server.
|
|
13
|
+
|
|
14
|
+
**What it does**: Keeps a centralized code intelligence graph up-to-date so your team's AI assistants (like Claude) can access instant, consistent codebase understanding without local indexing overhead.
|
|
15
|
+
|
|
16
|
+
**Key benefits**:
|
|
17
|
+
|
|
18
|
+
- **Privacy-First**: Parse locally, transmit only AST metadata—never your source code
|
|
19
|
+
- **Team-Wide Intelligence**: One shared graph serves all developers' AI tools
|
|
20
|
+
- **Always Current**: Incremental indexing keeps intelligence synchronized with your codebase
|
|
21
|
+
- **Zero Local Overhead**: AI assistants get instant context via MCP without indexing delays
|
|
22
|
+
|
|
23
|
+
## Features
|
|
24
|
+
|
|
25
|
+
### Smart Indexing
|
|
26
|
+
|
|
27
|
+
- **Incremental Updates**: Only processes files changed since last index
|
|
28
|
+
- **Full Re-indexing**: Force complete project re-analysis when needed
|
|
29
|
+
- **Git-Aware**: Automatically tracks changes using Git history
|
|
30
|
+
- **CI/CD Ready**: Integrate into pipelines to keep intelligence current
|
|
31
|
+
|
|
32
|
+
### Multi-Language Support
|
|
33
|
+
|
|
34
|
+
Currently supports:
|
|
35
|
+
|
|
36
|
+
- **JavaScript**
|
|
37
|
+
- **TypeScript**
|
|
38
|
+
|
|
39
|
+
_Additional languages (C, C++, C#, Go, Java, JSON, PHP, Python, Ruby, Shell) coming soon_
|
|
40
|
+
|
|
41
|
+
### Security
|
|
42
|
+
|
|
43
|
+
- Local parsing of source code, never transmitted
|
|
44
|
+
- Only code metadata sent (compressed with gzip)
|
|
45
|
+
- API key based authentication
|
|
46
|
+
- Respects `.gitignore` and Git configuration
|
|
47
|
+
|
|
48
|
+
## Installation
|
|
49
|
+
|
|
50
|
+
### Globally Install NPM Package
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npm install -g @constellationdev/cli@latest
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Requirements
|
|
57
|
+
|
|
58
|
+
- Node.js 24.0.0 or higher
|
|
59
|
+
- Git installed and available in PATH
|
|
60
|
+
- Git repository
|
|
61
|
+
|
|
62
|
+
## Quick Start
|
|
63
|
+
|
|
64
|
+
### 1. Initialize Your Project
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
constellation init
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Creates `constellation.json` configuration file with interactive prompts:
|
|
71
|
+
|
|
72
|
+
- Project ID (from your Constellation web dashboard)
|
|
73
|
+
- Branch to track
|
|
74
|
+
- Programming languages used
|
|
75
|
+
|
|
76
|
+
### 2. Configure Authentication
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
constellation auth
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Stores your Constellation access key in environment variables.
|
|
83
|
+
|
|
84
|
+
**Alternative**: Set manually:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
export CONSTELLATION_ACCESS_KEY="your-access-key"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 3. Index Your Project
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
# Smart indexing (incremental if possible)
|
|
94
|
+
constellation index
|
|
95
|
+
|
|
96
|
+
# Force complete re-index
|
|
97
|
+
constellation index --full
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Commands
|
|
101
|
+
|
|
102
|
+
### `constellation init`
|
|
103
|
+
|
|
104
|
+
Initialize project configuration.
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
constellation init
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Creates**: `constellation.json` file in current directory
|
|
111
|
+
**Requires**: Git repository
|
|
112
|
+
**Interactive**: Prompts for project ID, branch, and languages
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
### `constellation auth`
|
|
117
|
+
|
|
118
|
+
Configure authentication credentials.
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
constellation auth
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Stores**: Access key in `CONSTELLATION_ACCESS_KEY` environment variable
|
|
125
|
+
**Interactive**: Prompts for Constellation access key
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
### `constellation index`
|
|
130
|
+
|
|
131
|
+
Parse codebase and upload intelligence to Constellation service.
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
constellation index [options]
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
**Options**:
|
|
138
|
+
|
|
139
|
+
- `--full`: Force complete re-index
|
|
140
|
+
- `--incremental`: Explicitly request incremental (default when previous index exists)
|
|
141
|
+
|
|
142
|
+
**Process**:
|
|
143
|
+
|
|
144
|
+
1. Validates Git branch and status
|
|
145
|
+
2. Pulls latest changes from remote
|
|
146
|
+
3. Determines index scope (full vs incremental)
|
|
147
|
+
4. Scans and parses relevant files
|
|
148
|
+
5. Compresses and uploads AST data
|
|
149
|
+
|
|
150
|
+
**What gets indexed**:
|
|
151
|
+
|
|
152
|
+
- Files matching configured language extensions
|
|
153
|
+
- Git-tracked files only (respects `.gitignore`)
|
|
154
|
+
- Files from configured branch
|
|
155
|
+
|
|
156
|
+
## Configuration
|
|
157
|
+
|
|
158
|
+
The `constellation.json` file controls indexing:
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"projectId": "project-identifier",
|
|
163
|
+
"branch": "main",
|
|
164
|
+
"languages": {
|
|
165
|
+
"typescript": {
|
|
166
|
+
"fileExtensions": [".ts", ".tsx"]
|
|
167
|
+
},
|
|
168
|
+
"javascript": {
|
|
169
|
+
"fileExtensions": [".js", ".jsx"]
|
|
170
|
+
}
|
|
171
|
+
},
|
|
172
|
+
"exclude": ["**/node_modules/**", "**/dist/**"]
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Fields**:
|
|
177
|
+
|
|
178
|
+
- **`projectId`** (required): Unique project identifier (from your Constellation web dashboard)
|
|
179
|
+
- **`branch`** (required): Git branch to track
|
|
180
|
+
- **`languages`** (required): Language config with file extensions
|
|
181
|
+
- **`exclude`** (optional): Glob patterns to exclude
|
|
182
|
+
|
|
183
|
+
### Supported Languages
|
|
184
|
+
|
|
185
|
+
| Language | Identifier | Default Extensions |
|
|
186
|
+
| ---------- | ------------ | ----------------------------- |
|
|
187
|
+
| JavaScript | `javascript` | `.js`, `.jsx`, `.mjs`, `.cjs` |
|
|
188
|
+
| TypeScript | `typescript` | `.ts`, `.tsx` |
|
|
189
|
+
|
|
190
|
+
**Coming Soon**: C, C++, C#, Go, Java, JSON, PHP, Python, Ruby, Shell, and more!
|
|
191
|
+
|
|
192
|
+
## 🔧 Advanced Usage
|
|
193
|
+
|
|
194
|
+
### Environment Variables
|
|
195
|
+
|
|
196
|
+
- **`CONSTELLATION_ACCESS_KEY`**: API authentication key
|
|
197
|
+
|
|
198
|
+
### CI/CD Integration (Highly Recommended)
|
|
199
|
+
|
|
200
|
+
**We strongly recommend setting up Constellation indexing in your CI/CD pipeline.** This enables "set it and forget it" automation, whenever code is pushed or merged into your configured branch, the index automatically updates. Your team's AI development tools stay current without any manual intervention or developer overhead.
|
|
201
|
+
|
|
202
|
+
**Benefits of CI/CD Automation:**
|
|
203
|
+
|
|
204
|
+
- **Zero Developer Overhead**: Indexing triggers automatically
|
|
205
|
+
- **Always Up-to-Date**: Intelligence graph stays synchronized with your codebase
|
|
206
|
+
- **Team Confidence**: Developers trust their AI assistants to have current context
|
|
207
|
+
- **Autopilot Mode**: Configure once, never worry about indexing again
|
|
208
|
+
|
|
209
|
+
#### GitHub Actions Example
|
|
210
|
+
|
|
211
|
+
```yaml
|
|
212
|
+
name: Constellation Auto-Index
|
|
213
|
+
on:
|
|
214
|
+
push:
|
|
215
|
+
branches: [main] # Match your configured branch
|
|
216
|
+
pull_request:
|
|
217
|
+
branches: [main]
|
|
218
|
+
types: [closed]
|
|
219
|
+
|
|
220
|
+
jobs:
|
|
221
|
+
index:
|
|
222
|
+
# Only run on merged PRs or direct pushes
|
|
223
|
+
if: github.event_name == 'push' || github.event.pull_request.merged == true
|
|
224
|
+
runs-on: ubuntu-latest
|
|
225
|
+
steps:
|
|
226
|
+
- uses: actions/checkout@v3
|
|
227
|
+
- uses: actions/setup-node@v3
|
|
228
|
+
with:
|
|
229
|
+
node-version: '24'
|
|
230
|
+
- name: Install Constellation CLI
|
|
231
|
+
run: npm install -g @constellationdev/cli
|
|
232
|
+
- name: Run Incremental Index
|
|
233
|
+
run: constellation index --incremental
|
|
234
|
+
env:
|
|
235
|
+
CONSTELLATION_ACCESS_KEY: ${{ secrets.CONSTELLATION_ACCESS_KEY }}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
**Setup Steps:**
|
|
239
|
+
|
|
240
|
+
1. Add `CONSTELLATION_ACCESS_KEY` to your CI/CD secrets/environment variables
|
|
241
|
+
2. Configure pipeline to run on pushes/merges to your configured branch
|
|
242
|
+
3. Install CLI and run `constellation index --incremental`
|
|
243
|
+
4. Let automation handle the rest, keeping your code intelligence data current
|
|
244
|
+
|
|
245
|
+
### Incremental vs Full Indexing
|
|
246
|
+
|
|
247
|
+
**Incremental** (default when previous index exists):
|
|
248
|
+
|
|
249
|
+
- Processes only changed files since last index
|
|
250
|
+
- Faster for regular updates
|
|
251
|
+
- Tracks added, modified, renamed, and deleted files
|
|
252
|
+
|
|
253
|
+
**Full** (triggered with `--full` or no previous index):
|
|
254
|
+
|
|
255
|
+
- Processes all project files
|
|
256
|
+
- Use after significant configuration changes or first-time setup
|
|
257
|
+
|
|
258
|
+
## Troubleshooting
|
|
259
|
+
|
|
260
|
+
| Issue | Solution |
|
|
261
|
+
| ------------------------------ | ------------------------------------------------------------------ |
|
|
262
|
+
| "Could not find git client" | Install Git from [git-scm.com](https://git-scm.com/downloads) |
|
|
263
|
+
| "Not a git repository" | Run from within a Git repository or `git init` |
|
|
264
|
+
| "Branch not configured" | Switch branches or update `branch` in `constellation.json` |
|
|
265
|
+
| "Outstanding changes detected" | Commit or stash changes: `git add . && git commit` or `git stash` |
|
|
266
|
+
| "Access key not found" | Run `constellation auth` or set `CONSTELLATION_ACCESS_KEY` |
|
|
267
|
+
| Parse errors | Some files may have syntax errors; CLI continues processing others |
|
|
268
|
+
|
|
269
|
+
**Get Help**:
|
|
270
|
+
|
|
271
|
+
- Documentation: `constellation --help`
|
|
272
|
+
- Issues: [GitHub Issues](https://github.com/ShiftinBits/constellation-cli/issues)
|
|
273
|
+
- Documentation: [docs.constellationdev.io](https://docs.constellationdev.io/docs/cli)
|
|
274
|
+
|
|
275
|
+
## License
|
|
276
|
+
|
|
277
|
+
GNU Affero General Public License v3.0 (AGPL-3.0)
|
|
278
|
+
|
|
279
|
+
Copyright © 2026 ShiftinBits Inc.
|
|
280
|
+
|
|
281
|
+
See [LICENSE](LICENSE) file for details.
|
|
282
|
+
|
|
283
|
+
## Acknowledgments
|
|
284
|
+
|
|
285
|
+
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) for fast, reliable parsing
|
|
286
|
+
- [Commander.js](https://github.com/tj/commander.js) for CLI framework
|
|
287
|
+
- [simple-git](https://github.com/steveukx/git-js) for Git operations
|