argustack 0.1.6 → 0.1.8
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/README.md +58 -385
- package/dist/adapters/git/mapper.d.ts +1 -1
- package/dist/adapters/git/mapper.js +1 -1
- package/dist/adapters/github/mapper.d.ts +1 -1
- package/dist/adapters/github/mapper.js +1 -1
- package/dist/cli/init/generators.d.ts +6 -0
- package/dist/cli/init/generators.d.ts.map +1 -0
- package/dist/cli/init/generators.js +153 -0
- package/dist/cli/init/generators.js.map +1 -0
- package/dist/cli/init/index.d.ts +4 -0
- package/dist/cli/init/index.d.ts.map +1 -0
- package/dist/cli/init/index.js +254 -0
- package/dist/cli/init/index.js.map +1 -0
- package/dist/cli/init/setup-csv.d.ts +4 -0
- package/dist/cli/init/setup-csv.d.ts.map +1 -0
- package/dist/cli/init/setup-csv.js +52 -0
- package/dist/cli/init/setup-csv.js.map +1 -0
- package/dist/cli/init/setup-db.d.ts +4 -0
- package/dist/cli/init/setup-db.d.ts.map +1 -0
- package/dist/cli/init/setup-db.js +33 -0
- package/dist/cli/init/setup-db.js.map +1 -0
- package/dist/cli/init/setup-git.d.ts +4 -0
- package/dist/cli/init/setup-git.d.ts.map +1 -0
- package/dist/cli/init/setup-git.js +244 -0
- package/dist/cli/init/setup-git.js.map +1 -0
- package/dist/cli/init/setup-github.d.ts +4 -0
- package/dist/cli/init/setup-github.d.ts.map +1 -0
- package/dist/cli/init/setup-github.js +102 -0
- package/dist/cli/init/setup-github.js.map +1 -0
- package/dist/cli/init/setup-jira.d.ts +4 -0
- package/dist/cli/init/setup-jira.d.ts.map +1 -0
- package/dist/cli/init/setup-jira.js +124 -0
- package/dist/cli/init/setup-jira.js.map +1 -0
- package/dist/cli/init/types.d.ts +59 -0
- package/dist/cli/init/types.d.ts.map +1 -0
- package/dist/cli/init/types.js +31 -0
- package/dist/cli/init/types.js.map +1 -0
- package/dist/core/types/config.js +1 -1
- package/dist/core/types/config.js.map +1 -1
- package/dist/mcp/helpers.d.ts +24 -0
- package/dist/mcp/helpers.d.ts.map +1 -0
- package/dist/mcp/helpers.js +73 -0
- package/dist/mcp/helpers.js.map +1 -0
- package/dist/mcp/server.d.ts +2 -3
- package/dist/mcp/server.d.ts.map +1 -1
- package/dist/mcp/server.js +12 -1579
- package/dist/mcp/server.js.map +1 -1
- package/dist/mcp/tools/estimate.d.ts +3 -0
- package/dist/mcp/tools/estimate.d.ts.map +1 -0
- package/dist/mcp/tools/estimate.js +478 -0
- package/dist/mcp/tools/estimate.js.map +1 -0
- package/dist/mcp/tools/issue.d.ts +3 -0
- package/dist/mcp/tools/issue.d.ts.map +1 -0
- package/dist/mcp/tools/issue.js +468 -0
- package/dist/mcp/tools/issue.js.map +1 -0
- package/dist/mcp/tools/query.d.ts +3 -0
- package/dist/mcp/tools/query.d.ts.map +1 -0
- package/dist/mcp/tools/query.js +319 -0
- package/dist/mcp/tools/query.js.map +1 -0
- package/dist/mcp/tools/search.d.ts +3 -0
- package/dist/mcp/tools/search.d.ts.map +1 -0
- package/dist/mcp/tools/search.js +61 -0
- package/dist/mcp/tools/search.js.map +1 -0
- package/dist/mcp/tools/workspace.d.ts +3 -0
- package/dist/mcp/tools/workspace.d.ts.map +1 -0
- package/dist/mcp/tools/workspace.js +86 -0
- package/dist/mcp/tools/workspace.js.map +1 -0
- package/dist/mcp/types.d.ts +157 -0
- package/dist/mcp/types.d.ts.map +1 -0
- package/dist/mcp/types.js +2 -0
- package/dist/mcp/types.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,432 +1,105 @@
|
|
|
1
1
|
# Argustack
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/argustack)
|
|
4
|
+
[](https://www.npmjs.com/package/argustack)
|
|
5
|
+
[](LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
**Ask AI about your Jira, Git, and GitHub — powered by local data, not cloud APIs.**
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
2. **Augmentation** — inject relevant context into the AI prompt
|
|
9
|
-
3. **Generation** — LLM generates answers grounded in your actual Jira tickets, code, and databases
|
|
9
|
+
Argustack downloads your project data into local PostgreSQL, cross-references everything, and gives Claude direct access via 15 MCP tools. All data stays on your machine.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
> *Was ticket PROJ-123 implemented as described?*
|
|
12
|
+
> *Who reviewed the PR and what was the feedback?*
|
|
13
|
+
> *How long will it take Sarah to fix this bug?*
|
|
12
14
|
|
|
13
|
-
|
|
14
|
-
YOUR SOURCES YOUR MACHINE
|
|
15
|
-
┌──────────────────────┐ ┌─────────────────────────────────────┐
|
|
16
|
-
│ Jira Cloud / Server │ │ │
|
|
17
|
-
│ (issues, comments, │ pull │ PostgreSQL (Docker, localhost) │
|
|
18
|
-
│ changelogs, etc.) │ ──────►│ ├── issues (all fields) │
|
|
19
|
-
└──────────────────────┘ │ ├── issue_comments (discussions) │
|
|
20
|
-
│ ├── issue_changelogs (history) │
|
|
21
|
-
┌──────────────────────┐ │ ├── issue_worklogs (time logs) │
|
|
22
|
-
│ Git repository │ pull │ ├── issue_links (relations) │
|
|
23
|
-
│ (commits, files, │ ──────►│ ├── commits (history) │
|
|
24
|
-
│ diffs, authors) │ │ ├── commit_files (per-file Δ) │
|
|
25
|
-
└──────────────────────┘ │ ├── commit_issue_refs (cross-ref)│
|
|
26
|
-
│ │ │
|
|
27
|
-
┌──────────────────────┐ │ │ GitHub (optional, via token) │
|
|
28
|
-
│ GitHub API │ pull │ ├── pull_requests (PRs + meta) │
|
|
29
|
-
│ (PRs, reviews, │ ──────►│ ├── pr_reviews (approvals) │
|
|
30
|
-
│ releases) │ │ ├── pr_comments (discussions) │
|
|
31
|
-
└──────────────────────┘ │ ├── pr_issue_refs (PR↔Jira) │
|
|
32
|
-
│ └── releases (tags) │
|
|
33
|
-
┌──────────────────────┐ │ │
|
|
34
|
-
│ Database (planned) │ │ MCP Server (localhost, stdio) │
|
|
35
|
-
└──────────────────────┘ │ └── queries DB ──► Claude / LLM │
|
|
36
|
-
│ │
|
|
37
|
-
│ .env (credentials — never leaves) │
|
|
38
|
-
└─────────────────────────────────────┘
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
> *Is this bug still relevant or already fixed in code?*
|
|
42
|
-
> *Was the feature implemented as described in the ticket?*
|
|
43
|
-
> *Who worked on this module and what changed last month?*
|
|
44
|
-
> *Which commits and PRs reference ticket PAP-123?*
|
|
45
|
-
> *Who approved the PR and what was the review feedback?*
|
|
46
|
-
|
|
47
|
-
## How it works
|
|
15
|
+
## Features
|
|
48
16
|
|
|
49
|
-
**
|
|
50
|
-
|
|
51
|
-
**
|
|
52
|
-
|
|
53
|
-
**
|
|
17
|
+
- **Jira** — issues, comments, changelogs, worklogs, links, all custom fields
|
|
18
|
+
- **Git** — commits, per-file diffs, automatic issue cross-references
|
|
19
|
+
- **GitHub** — PRs, reviews, comments, releases, automatic issue cross-references
|
|
20
|
+
- **CSV import** — Jira CSV export for teams without API access
|
|
21
|
+
- **Cross-source timeline** — Jira + Git + GitHub events in chronological order
|
|
22
|
+
- **Semantic search** — find issues by meaning, not just keywords (pgvector)
|
|
23
|
+
- **Task estimation** — predict duration per developer based on actual history
|
|
24
|
+
- **15 MCP tools** — Claude queries your data directly via SQL
|
|
25
|
+
- **100% local** — no cloud, no accounts, no telemetry
|
|
54
26
|
|
|
55
27
|
## Quick Start
|
|
56
28
|
|
|
57
|
-
### Prerequisites
|
|
58
|
-
|
|
59
|
-
- [Node.js](https://nodejs.org/) >= 20
|
|
60
|
-
- [Docker](https://www.docker.com/) (or [OrbStack](https://orbstack.dev/) / Podman)
|
|
61
|
-
|
|
62
|
-
### Install & setup
|
|
63
|
-
|
|
64
29
|
```bash
|
|
65
30
|
npm i -g argustack
|
|
66
|
-
argustack init
|
|
31
|
+
argustack init # interactive setup — sources, credentials, Docker
|
|
32
|
+
argustack sync # pull all data
|
|
33
|
+
argustack mcp install # connect to Claude Desktop
|
|
67
34
|
```
|
|
68
35
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
#### Interactive mode (default)
|
|
72
|
-
|
|
73
|
-
Run `argustack init` and follow the prompts:
|
|
74
|
-
|
|
75
|
-
```
|
|
76
|
-
? Workspace directory: ~/projects/my-team
|
|
77
|
-
? Sources: ✔ Jira — issues, comments, changelogs
|
|
78
|
-
✔ Git — commits, diffs, authors
|
|
79
|
-
✔ GitHub — PRs, reviews, releases
|
|
80
|
-
? Jira URL: https://your-team.atlassian.net
|
|
81
|
-
? Email: you@company.com
|
|
82
|
-
? API Token: ****
|
|
36
|
+
That's it. Ask Claude about your project.
|
|
83
37
|
|
|
84
|
-
|
|
38
|
+
### Non-interactive mode
|
|
85
39
|
|
|
86
|
-
|
|
87
|
-
? Where is your Git repository?
|
|
88
|
-
● Clone from GitHub — select repos using your token
|
|
89
|
-
? GitHub token (PAT): ****
|
|
90
|
-
|
|
91
|
-
Fetching repositories... Found 12 repos.
|
|
92
|
-
|
|
93
|
-
? Repositories to clone: ✔ your-org/frontend ✔ your-org/backend
|
|
94
|
-
? GitHub source: Auto-configured from clone step
|
|
95
|
-
|
|
96
|
-
? Start database and sync now? Yes
|
|
97
|
-
|
|
98
|
-
✔ Database running!
|
|
99
|
-
✔ Jira sync complete!
|
|
100
|
-
MKT: 506 issues (150/506 ████░░░░ 30% → 506/506 done)
|
|
101
|
-
✔ Git sync complete!
|
|
102
|
-
your-org/frontend: 735 commits (400/735 ██████░░ 54% → 735/735 done)
|
|
103
|
-
✔ GitHub sync complete!
|
|
104
|
-
66 PRs (30/66 ██████░░ 45% → 66/66 done), 124 reviews, 3 releases
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
The interactive setup will:
|
|
108
|
-
|
|
109
|
-
1. Ask which sources you have (Jira, Git, GitHub, Database)
|
|
110
|
-
2. Collect credentials and test connections
|
|
111
|
-
3. For Git — choose local path, clone from GitHub (multi-select repos), or clone from URL
|
|
112
|
-
4. For GitHub — auto-configured if you cloned from GitHub in the previous step, or enter a Personal Access Token (see [GitHub token setup](#github-token-setup))
|
|
113
|
-
5. Create a workspace with Docker config
|
|
114
|
-
6. Start PostgreSQL + pgweb automatically
|
|
115
|
-
7. Pull all your data
|
|
116
|
-
|
|
117
|
-
#### Non-interactive mode (for AI agents and CI/CD)
|
|
118
|
-
|
|
119
|
-
Pass `--no-interactive` with all values as CLI flags — no prompts, no terminal needed:
|
|
40
|
+
For AI agents and CI/CD — pass everything as flags:
|
|
120
41
|
|
|
121
42
|
```bash
|
|
122
|
-
argustack init \
|
|
123
|
-
--no-interactive \
|
|
124
|
-
--dir ~/projects/my-team \
|
|
43
|
+
argustack init --no-interactive \
|
|
125
44
|
--source jira,git,github \
|
|
126
45
|
--jira-url "https://your-team.atlassian.net" \
|
|
127
46
|
--jira-email "you@company.com" \
|
|
128
47
|
--jira-token "ATATT3x..." \
|
|
129
|
-
--jira-projects
|
|
130
|
-
--git-repo /path/to/
|
|
48
|
+
--jira-projects PROJ,MKT \
|
|
49
|
+
--git-repo /path/to/repo \
|
|
131
50
|
--github-token "github_pat_..." \
|
|
132
51
|
--github-owner your-org \
|
|
133
52
|
--github-repo your-repo
|
|
134
53
|
```
|
|
135
54
|
|
|
136
|
-
Then start the database and sync:
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
cd ~/projects/my-team
|
|
140
|
-
docker compose up -d
|
|
141
|
-
argustack sync
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
All available flags:
|
|
145
|
-
|
|
146
|
-
| Flag | Description |
|
|
147
|
-
|------|-------------|
|
|
148
|
-
| `--no-interactive` | Run without prompts — all values from flags |
|
|
149
|
-
| `-d, --dir <path>` | Workspace directory (default: current) |
|
|
150
|
-
| `-s, --source <list>` | Comma-separated: `jira,git,github,csv,db` |
|
|
151
|
-
| `--jira-url <url>` | Jira instance URL |
|
|
152
|
-
| `--jira-email <email>` | Jira user email |
|
|
153
|
-
| `--jira-token <token>` | Jira API token |
|
|
154
|
-
| `--jira-projects <keys>` | Comma-separated project keys, or `all` |
|
|
155
|
-
| `--git-repo <paths>` | Git repo paths, comma-separated |
|
|
156
|
-
| `--github-token <token>` | GitHub Personal Access Token |
|
|
157
|
-
| `--github-owner <owner>` | GitHub repo owner |
|
|
158
|
-
| `--github-repo <repo>` | GitHub repo name |
|
|
159
|
-
| `--csv-file <path>` | Path to Jira CSV export file |
|
|
160
|
-
| `--db-port <port>` | Argustack PostgreSQL port (default: `5434`) |
|
|
161
|
-
| `--pgweb-port <port>` | pgweb UI port (default: `8086`) |
|
|
162
|
-
|
|
163
|
-
This mode is ideal for:
|
|
164
|
-
- **AI agents** — a project manager tells their AI agent "set up argustack" and it runs everything autonomously
|
|
165
|
-
- **CI/CD pipelines** — automated workspace provisioning
|
|
166
|
-
- **Scripted setups** — reproducible environment creation
|
|
167
|
-
|
|
168
|
-
Browse your data at [localhost:8086](http://localhost:8086) — pgweb UI for running SQL queries and exploring tables in your browser.
|
|
169
|
-
|
|
170
|
-
### Connect to Claude
|
|
171
|
-
|
|
172
|
-
```bash
|
|
173
|
-
argustack mcp install
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
Adds Argustack as an MCP server to Claude Desktop. Now you can ask Claude questions about your project data directly.
|
|
177
|
-
|
|
178
55
|
## Commands
|
|
179
56
|
|
|
180
57
|
```bash
|
|
181
|
-
argustack init # create workspace
|
|
182
|
-
argustack
|
|
183
|
-
argustack sync
|
|
184
|
-
argustack sync
|
|
185
|
-
argustack
|
|
186
|
-
argustack
|
|
187
|
-
argustack sync csv # import from Jira CSV export
|
|
188
|
-
argustack sync csv -f /path/to.csv # import specific CSV file
|
|
189
|
-
argustack sync -p PROJ # pull specific Jira project
|
|
190
|
-
argustack sync --since 2025-01-01 # incremental pull (only new/updated)
|
|
58
|
+
argustack init # create workspace
|
|
59
|
+
argustack sync # pull all sources
|
|
60
|
+
argustack sync jira|git|github|csv # pull specific source
|
|
61
|
+
argustack sync --since 2025-01-01 # incremental pull
|
|
62
|
+
argustack embed # generate embeddings (requires OpenAI key)
|
|
63
|
+
argustack mcp install # connect to Claude Desktop
|
|
191
64
|
argustack sources # list configured sources
|
|
192
65
|
argustack status # workspace info
|
|
193
|
-
argustack embed # generate embeddings for semantic search
|
|
194
|
-
argustack mcp install # connect to Claude Desktop
|
|
195
66
|
```
|
|
196
67
|
|
|
197
|
-
## What gets stored
|
|
198
|
-
|
|
199
|
-
All data goes into local PostgreSQL in Docker on your machine (nothing leaves `localhost`):
|
|
200
|
-
|
|
201
|
-
### Jira tables
|
|
202
|
-
|
|
203
|
-
| Table | Content |
|
|
204
|
-
|-------|---------|
|
|
205
|
-
| `issues` | All issues — typed columns + `custom_fields` JSONB + full `raw_json` |
|
|
206
|
-
| `issue_comments` | Comments with authors and timestamps |
|
|
207
|
-
| `issue_changelogs` | Every field change in history |
|
|
208
|
-
| `issue_worklogs` | Time tracking entries |
|
|
209
|
-
| `issue_links` | Issue-to-issue relationships |
|
|
210
|
-
|
|
211
|
-
Every custom field is preserved exactly as Jira returns it. 500 custom fields? All stored. Zero filtering, zero data loss.
|
|
212
|
-
|
|
213
|
-
### Git tables
|
|
214
|
-
|
|
215
|
-
| Table | Content |
|
|
216
|
-
|-------|---------|
|
|
217
|
-
| `commits` | Commit hash, message, author, email, date, full-text search |
|
|
218
|
-
| `commit_files` | Per-file changes — path, status, additions, deletions |
|
|
219
|
-
| `commit_issue_refs` | Cross-reference: commit ↔ Jira issue (extracted from commit messages) |
|
|
220
|
-
|
|
221
|
-
Commit messages mentioning issue keys like `PAP-123` or `PROJ-45` are automatically linked to Jira issues.
|
|
222
|
-
|
|
223
|
-
### GitHub tables
|
|
224
|
-
|
|
225
|
-
Select "GitHub" during `argustack init` or add later with `argustack source add github`:
|
|
226
|
-
|
|
227
|
-
| Table | Content |
|
|
228
|
-
|-------|---------|
|
|
229
|
-
| `pull_requests` | PRs — state, author, reviewers, additions/deletions, merge info, full-text search |
|
|
230
|
-
| `pr_reviews` | Review approvals and change requests |
|
|
231
|
-
| `pr_comments` | Inline review comments with file paths and line numbers |
|
|
232
|
-
| `pr_files` | Per-file changes in each PR |
|
|
233
|
-
| `pr_issue_refs` | Cross-reference: PR ↔ Jira issue (extracted from PR title and body) |
|
|
234
|
-
| `releases` | GitHub releases with tags, notes, and full-text search |
|
|
235
|
-
|
|
236
|
-
PR titles and bodies mentioning issue keys like `PAP-123` are automatically linked to Jira issues — just like commits.
|
|
237
|
-
|
|
238
68
|
## MCP Tools
|
|
239
69
|
|
|
240
|
-
|
|
70
|
+
After sync, Claude queries your data through these tools:
|
|
241
71
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
|
245
|
-
|
|
246
|
-
| `
|
|
247
|
-
| `get_issue` | Full issue details with comments, changelogs, custom fields |
|
|
248
|
-
| `issue_stats` | Aggregate stats — by status, type, assignee, project |
|
|
72
|
+
| Tool | Purpose |
|
|
73
|
+
|------|---------|
|
|
74
|
+
| `query_issues` | Search issues — full-text, filters, raw SQL |
|
|
75
|
+
| `get_issue` | Full issue details with comments and changelogs |
|
|
76
|
+
| `issue_stats` | Aggregates by status, type, assignee |
|
|
249
77
|
| `pull_jira` | Sync latest data from Jira |
|
|
250
|
-
| `list_projects` |
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
|
255
|
-
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
|
|
260
|
-
### GitHub tools
|
|
261
|
-
|
|
262
|
-
| Tool | What it does |
|
|
263
|
-
|------|-------------|
|
|
264
|
-
| `query_prs` | Search PRs — full-text, state, author, base branch, or raw SQL |
|
|
265
|
-
| `issue_prs` | Cross-reference: find all PRs mentioning a Jira issue key with reviews |
|
|
266
|
-
| `query_releases` | List releases with full-text search |
|
|
267
|
-
|
|
268
|
-
### Cross-source tools
|
|
269
|
-
|
|
270
|
-
| Tool | What it does |
|
|
271
|
-
|------|-------------|
|
|
272
|
-
| `issue_timeline` | Chronological timeline — changelogs + commits + PRs for one issue |
|
|
273
|
-
| `semantic_search` | Find similar issues by meaning (pgvector embeddings) |
|
|
274
|
-
| `estimate` | Predict how long a task will take for a specific developer — "without bugs" (pure dev time) and "with bugs" (real cost), personal coefficient from full history |
|
|
275
|
-
|
|
276
|
-
### System tools
|
|
277
|
-
|
|
278
|
-
| Tool | What it does |
|
|
279
|
-
|------|-------------|
|
|
78
|
+
| `list_projects` | Available Jira projects |
|
|
79
|
+
| `query_commits` | Search commits by text, author, date, file |
|
|
80
|
+
| `issue_commits` | All commits mentioning a Jira issue key |
|
|
81
|
+
| `commit_stats` | Top authors, most changed files |
|
|
82
|
+
| `query_prs` | Search PRs by text, state, author |
|
|
83
|
+
| `issue_prs` | All PRs mentioning a Jira issue key |
|
|
84
|
+
| `query_releases` | List releases with search |
|
|
85
|
+
| `issue_timeline` | Full chronological timeline: Jira + Git + GitHub |
|
|
86
|
+
| `semantic_search` | Find similar issues by meaning (pgvector) |
|
|
87
|
+
| `estimate` | Predict task duration per developer |
|
|
280
88
|
| `workspace_info` | Current workspace configuration |
|
|
281
89
|
|
|
282
|
-
##
|
|
283
|
-
|
|
284
|
-
**Embeddings** turn issue text into numerical vectors that capture meaning. Two issues about "login not working" and "SSO authentication fails" will have similar vectors — even though they share zero keywords.
|
|
285
|
-
|
|
286
|
-
How it works:
|
|
287
|
-
|
|
288
|
-
1. `argustack embed` sends each issue's `summary + description` to OpenAI API (`text-embedding-3-small` model)
|
|
289
|
-
2. Returns a 1536-dimensional vector per issue, stored in PostgreSQL via pgvector
|
|
290
|
-
3. `semantic_search` MCP tool embeds your question, then finds issues with the closest vectors using cosine similarity
|
|
291
|
-
|
|
292
|
-
```bash
|
|
293
|
-
# Generate embeddings for all issues (requires OPENAI_API_KEY in .env)
|
|
294
|
-
argustack embed
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
After embedding, ask Claude: *"Find issues similar to payment timeout errors"* — it will search by meaning, not keywords.
|
|
298
|
-
|
|
299
|
-
**Costs:** text-embedding-3-small costs ~$0.02 per 1M tokens. 10,000 issues ≈ $0.05-0.10.
|
|
300
|
-
|
|
301
|
-
**Optional:** Embeddings require an OpenAI API key. All other features work without it.
|
|
302
|
-
|
|
303
|
-
## GitHub token setup
|
|
304
|
-
|
|
305
|
-
Argustack only reads data from GitHub — it never writes anything. You need a **fine-grained Personal Access Token** with read-only permissions.
|
|
306
|
-
|
|
307
|
-
1. Go to [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
|
|
308
|
-
2. **Token name** — anything (e.g. `argustack`)
|
|
309
|
-
3. **Description** — optional, can leave empty
|
|
310
|
-
4. **Resource owner** — your account, or the organization that owns the repo
|
|
311
|
-
5. **Expiration** — "No expiration" recommended. Token is read-only and stays in your local `.env`
|
|
312
|
-
6. **Repository access** — pick one:
|
|
313
|
-
- **Only select repositories** (recommended) — pick specific repos, max 50
|
|
314
|
-
- **All repositories** — all your current and future repos
|
|
315
|
-
- **Public repositories** — read-only access to public repos only
|
|
316
|
-
5. **Permissions** → Repository permissions (3 total):
|
|
317
|
-
|
|
318
|
-
| Permission | Access | Why |
|
|
319
|
-
|---|---|---|
|
|
320
|
-
| **Contents** | Read-only | Releases, downloads, tags |
|
|
321
|
-
| **Metadata** | Read-only | Repository info (auto-selected, required) |
|
|
322
|
-
| **Pull requests** | Read-only | PRs, reviews, comments, files |
|
|
323
|
-
|
|
324
|
-
7. Click "Generate token" and copy it
|
|
325
|
-
|
|
326
|
-
During `argustack init`, select "GitHub" as a source and paste the token when asked. Or add to `.env` manually:
|
|
327
|
-
|
|
328
|
-
```bash
|
|
329
|
-
GITHUB_TOKEN=github_pat_...
|
|
330
|
-
GITHUB_OWNER=your-org
|
|
331
|
-
GITHUB_REPO=your-repo
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
Then run `argustack source add github` and `argustack sync github`.
|
|
335
|
-
|
|
336
|
-
## Multiple workspaces
|
|
337
|
-
|
|
338
|
-
Each data source = separate workspace (like git repos):
|
|
339
|
-
|
|
340
|
-
```
|
|
341
|
-
~/projects/
|
|
342
|
-
├── client-alpha/ # argustack init → Alpha's Jira + Git
|
|
343
|
-
│ ├── .argustack/
|
|
344
|
-
│ ├── .env # Alpha credentials
|
|
345
|
-
│ └── docker-compose.yml
|
|
346
|
-
│
|
|
347
|
-
├── client-beta/ # argustack init → Beta's Jira + Git
|
|
348
|
-
│ ├── .argustack/
|
|
349
|
-
│ ├── .env # Beta credentials
|
|
350
|
-
│ └── docker-compose.yml
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
## Security & Credentials
|
|
354
|
-
|
|
355
|
-
**Argustack is a CLI tool. It has no backend, no cloud, no accounts.** Everything runs on your machine.
|
|
356
|
-
|
|
357
|
-
When you run `argustack init`, it creates a `.env` file in your workspace with your credentials:
|
|
358
|
-
|
|
359
|
-
```bash
|
|
360
|
-
# .env — YOUR file, on YOUR machine, never uploaded anywhere
|
|
361
|
-
|
|
362
|
-
# === Jira ===
|
|
363
|
-
JIRA_URL=https://your-team.atlassian.net
|
|
364
|
-
JIRA_EMAIL=you@company.com
|
|
365
|
-
JIRA_API_TOKEN=your-api-token-here
|
|
366
|
-
JIRA_PROJECTS=PROJ,OTHER
|
|
367
|
-
|
|
368
|
-
# === Git ===
|
|
369
|
-
GIT_REPO_PATHS=/path/to/repo1,/path/to/repo2
|
|
370
|
-
|
|
371
|
-
# === GitHub ===
|
|
372
|
-
GITHUB_TOKEN=github_pat_...
|
|
373
|
-
GITHUB_OWNER=your-org
|
|
374
|
-
GITHUB_REPO=your-repo
|
|
375
|
-
|
|
376
|
-
# === Argustack internal PostgreSQL (match docker-compose.yml) ===
|
|
377
|
-
DB_HOST=localhost
|
|
378
|
-
DB_PORT=5434
|
|
379
|
-
DB_USER=argustack
|
|
380
|
-
DB_PASSWORD=argustack_local
|
|
381
|
-
DB_NAME=argustack
|
|
382
|
-
|
|
383
|
-
# === OpenAI embeddings (optional, for semantic search) ===
|
|
384
|
-
# OPENAI_API_KEY=sk-...
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
**Where credentials go:**
|
|
388
|
-
|
|
389
|
-
| What | Where | Who can see |
|
|
390
|
-
|------|-------|-------------|
|
|
391
|
-
| Jira token | `.env` on your disk | Only you |
|
|
392
|
-
| GitHub token | `.env` on your disk | Only you |
|
|
393
|
-
| Jira data | PostgreSQL in Docker on `localhost:5434` | Only you |
|
|
394
|
-
| Git + GitHub data | PostgreSQL in Docker on `localhost:5434` | Only you |
|
|
395
|
-
| Database password | `.env` on your disk | Only you |
|
|
396
|
-
| Source code (this repo) | GitHub | Everyone — **no secrets here** |
|
|
397
|
-
|
|
398
|
-
**What Argustack does NOT do:**
|
|
399
|
-
- Does not send your data to any external server
|
|
400
|
-
- Does not have analytics, telemetry, or tracking
|
|
401
|
-
- Does not store credentials anywhere except your local `.env`
|
|
402
|
-
- Does not require registration or accounts
|
|
403
|
-
|
|
404
|
-
**`.env` is in `.gitignore`** — if you accidentally run `git add .`, your credentials won't be committed.
|
|
90
|
+
## Security
|
|
405
91
|
|
|
406
|
-
|
|
92
|
+
Argustack is a CLI tool with no backend, no cloud, no accounts. Credentials stay in `.env` on your machine. Data stays in PostgreSQL on `localhost`. Nothing is uploaded anywhere.
|
|
407
93
|
|
|
408
|
-
|
|
409
|
-
- Commander.js — CLI
|
|
410
|
-
- jira.js — Jira REST API
|
|
411
|
-
- Octokit — GitHub REST API (PRs, reviews, releases)
|
|
412
|
-
- es-git — native Git bindings (N-API, powered by libgit2)
|
|
413
|
-
- PostgreSQL 16 + pgvector — storage + vector search
|
|
414
|
-
- MCP SDK — Claude integration
|
|
415
|
-
- Docker — database infrastructure
|
|
94
|
+
## Documentation
|
|
416
95
|
|
|
417
|
-
|
|
96
|
+
Full documentation available at **[Argustack DataRoom](https://app.paperlink.online/s/0aa7d2d6/argustack)**:
|
|
418
97
|
|
|
419
|
-
-
|
|
420
|
-
-
|
|
421
|
-
-
|
|
422
|
-
-
|
|
423
|
-
-
|
|
424
|
-
- [x] Cross-source timeline (issue_timeline: changelogs + commits + PRs)
|
|
425
|
-
- [x] Multi-repo Git support (multiple repos per workspace, `GIT_REPO_PATHS`)
|
|
426
|
-
- [x] Progress indicators during sync (e.g. `150/506 issues (30%)`)
|
|
427
|
-
- [ ] Database adapter (schema, sample data)
|
|
428
|
-
- [ ] Cross-source analysis (Jira ticket vs actual code vs DB state)
|
|
429
|
-
- [x] CSV import (Jira export without API token)
|
|
98
|
+
- **Quick Start Guide** — from zero to first query in 5 minutes
|
|
99
|
+
- **Use Cases & Examples** — real scenarios for PMs, team leads, developers, CTOs
|
|
100
|
+
- **MCP Tools Reference** — all 15 tools with parameters and examples
|
|
101
|
+
- **Estimate Tool Deep Dive** — algorithm, scoring, data sources
|
|
102
|
+
- **Architecture Guide** — hexagonal architecture, directory structure, extending
|
|
430
103
|
|
|
431
104
|
## License
|
|
432
105
|
|
|
@@ -4,7 +4,7 @@ export declare function mapCommit(esCommit: EsGitCommit, repoPath: string): Comm
|
|
|
4
4
|
export declare function mapDiffDelta(delta: DiffDelta, commitHash: string, additions: number, deletions: number): CommitFile;
|
|
5
5
|
/**
|
|
6
6
|
* Extract issue references from a commit message.
|
|
7
|
-
* Matches patterns like:
|
|
7
|
+
* Matches patterns like: PROJ-123, PROJ-45, ABC-1
|
|
8
8
|
* Returns unique keys, uppercased.
|
|
9
9
|
*/
|
|
10
10
|
export declare function extractIssueRefs(commitHash: string, message: string): CommitIssueRef[];
|
|
@@ -28,7 +28,7 @@ export function mapDiffDelta(delta, commitHash, additions, deletions) {
|
|
|
28
28
|
}
|
|
29
29
|
/**
|
|
30
30
|
* Extract issue references from a commit message.
|
|
31
|
-
* Matches patterns like:
|
|
31
|
+
* Matches patterns like: PROJ-123, PROJ-45, ABC-1
|
|
32
32
|
* Returns unique keys, uppercased.
|
|
33
33
|
*/
|
|
34
34
|
export function extractIssueRefs(commitHash, message) {
|
|
@@ -6,7 +6,7 @@ export declare function mapPrFile(raw: Record<string, unknown>, prNumber: number
|
|
|
6
6
|
export declare function mapRelease(raw: Record<string, unknown>, repoFullName: string): Release;
|
|
7
7
|
/**
|
|
8
8
|
* Extract issue references from PR title and body.
|
|
9
|
-
* Matches Jira-style keys:
|
|
9
|
+
* Matches Jira-style keys: PROJ-123, PROJ-45
|
|
10
10
|
*/
|
|
11
11
|
export declare function extractPrIssueRefs(prNumber: number, repoFullName: string, title: string, body: string | null): PullRequestIssueRef[];
|
|
12
12
|
//# sourceMappingURL=mapper.d.ts.map
|
|
@@ -98,7 +98,7 @@ export function mapRelease(raw, repoFullName) {
|
|
|
98
98
|
}
|
|
99
99
|
/**
|
|
100
100
|
* Extract issue references from PR title and body.
|
|
101
|
-
* Matches Jira-style keys:
|
|
101
|
+
* Matches Jira-style keys: PROJ-123, PROJ-45
|
|
102
102
|
*/
|
|
103
103
|
export function extractPrIssueRefs(prNumber, repoFullName, title, body) {
|
|
104
104
|
const pattern = /\b([A-Z][A-Z0-9]+-\d+)\b/g;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { JiraSetupResult, GitSetupResult, GitHubSetupResult, CsvSetupResult, DbSetupResult } from './types.js';
|
|
2
|
+
export declare function generateEnv(jira: JiraSetupResult | null, git: GitSetupResult | null, github: GitHubSetupResult | null, csv: CsvSetupResult | null, db: DbSetupResult | null, argustackDbPort: number): string;
|
|
3
|
+
export declare function generateDockerCompose(dbPort: number, pgwebPort: number): string;
|
|
4
|
+
export declare function createWorkspaceFiles(workspaceDir: string, jira: JiraSetupResult | null, git: GitSetupResult | null, github: GitHubSetupResult | null, csv: CsvSetupResult | null, db: DbSetupResult | null, dbPort: number, pgwebPort: number): void;
|
|
5
|
+
export declare function printSummary(workspaceDir: string, jira: JiraSetupResult | null, git: GitSetupResult | null, github: GitHubSetupResult | null, csv: CsvSetupResult | null, db: DbSetupResult | null, pgwebPort: number, willAutoStart: boolean): void;
|
|
6
|
+
//# sourceMappingURL=generators.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../../src/cli/init/generators.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,aAAa,EACd,MAAM,YAAY,CAAC;AAYpB,wBAAgB,WAAW,CACzB,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,MAAM,EAAE,iBAAiB,GAAG,IAAI,EAChC,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,EAAE,EAAE,aAAa,GAAG,IAAI,EACxB,eAAe,EAAE,MAAM,GACtB,MAAM,CAiER;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmC/E;AAED,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,MAAM,EAAE,iBAAiB,GAAG,IAAI,EAChC,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,EAAE,EAAE,aAAa,GAAG,IAAI,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,IAAI,CAiDN;AAED,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,MAAM,EAAE,iBAAiB,GAAG,IAAI,EAChC,GAAG,EAAE,cAAc,GAAG,IAAI,EAC1B,EAAE,EAAE,aAAa,GAAG,IAAI,EACxB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,OAAO,GACrB,IAAI,CA4CN"}
|