ai-spector 0.8.7 → 0.8.15

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 (3) hide show
  1. package/README.md +142 -33
  2. package/README.vi.md +216 -0
  3. package/package.json +5 -2
package/README.md CHANGED
@@ -1,57 +1,139 @@
1
1
  # AI Spector
2
2
 
3
- Documentation workflow in **Cursor**: traceability graph, SRS / basic / detail design. **Describe what you need in chat** — skills route the agent, which runs `ai-spector` CLI. You usually do not run CLI yourself.
3
+ Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS / basic / detail design. **Describe what you need in chat** — skills route the agent, which runs `ai-spector` CLI or MCP tools. You usually do not run CLI yourself.
4
4
 
5
- **Needs:** Node 20+, [Cursor](https://cursor.com), [uv](https://docs.astral.sh/uv/) (Graphify MCP after `init`).
5
+ **Needs:** Node 20+, Git, [Cursor](https://cursor.com) and/or [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(optional — CocoIndex semantic search)*.
6
+
7
+ Full setup reference: [docs/setup-guide.md](docs/setup-guide.md)
8
+
9
+ **Tiếng Việt:** [README.vi.md](README.vi.md)
10
+
11
+ ---
6
12
 
7
13
  ## Setup (once)
8
14
 
9
- **In Cursor:** ask **"setup ai-spector project"** (agent runs the setup skill).
15
+ ### Prerequisites
16
+
17
+ | Requirement | Check |
18
+ |-------------|-------|
19
+ | Node.js ≥ 20 | `node --version` |
20
+ | Git repository | `git status` |
21
+ | Cursor and/or Claude Code | IDE open in project root |
22
+ | Python ≥ 3.11 *(optional)* | only for CocoIndex semantic search |
23
+
24
+ ---
10
25
 
11
- **CLI:**
26
+ ### Step 1 — Scaffold *(only CLI step)*
27
+
28
+ Run once at your project root. On the **first** run, pass `--registry` so `npx` can download the package from the internal Verdaccio registry (`http://10.101.0.239:4873`). No `npm login` required.
12
29
 
13
30
  ```bash
14
- npm install -D ai-spector
15
- npx ai-spector setup # guided wizard
16
- npx ai-spector setup -y -l en,jp # non-interactive
17
- npx ai-spector setup --check # audit checklist
31
+ npx ai-spector@latest init --registry http://10.101.0.239:4873
18
32
  ```
19
33
 
20
- 1. Open the project in Cursor → reload **MCP** → enable **all** skills under `.cursor/skills/`.
21
- 2. Put source material in `docs/data-source/`.
34
+ The wizard prompts for editor (Cursor, Claude Code, or both), languages, git hook, and optional CocoIndex.
22
35
 
23
- Re-init scaffold: `npx ai-spector init --force` or `npx ai-spector setup -y --force`. After upgrading: `npx ai-spector sync-cursor`.
36
+ This creates:
24
37
 
25
- ## Workflow
38
+ - `.ai-spector/` — config, graph, templates
39
+ - `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
40
+ - **Cursor:** `.cursor/` — skills, rules, `mcp.json`
41
+ - **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
42
+ - Pre-commit hook (when git is available)
26
43
 
27
- See `.cursor/WORKFLOW.md` after `init`. Enable all skills under `.cursor/skills/`.
44
+ ---
28
45
 
29
- ### First run (natural language)
46
+ ### Step 2 — Finish setup in chat
47
+
48
+ Open the project in **Cursor** or **Claude Code** and say:
30
49
 
31
50
  ```text
32
- “analyze the data source”
33
- “validate the graph”
34
- “generate the SRS”
35
- “refresh the index”
51
+ setup ai-spector project
36
52
  ```
37
53
 
38
- Then: “generate basic design” → “generate detail design” as needed.
54
+ The agent installs the npm dependency (if needed), verifies the checklist, offers CocoIndex, and reminds you what is left to do manually.
39
55
 
40
- HTML prototype:
56
+ ---
41
57
 
42
- ```bash
43
- npx ai-spector prototype themes
58
+ ### Step 3 — Enable the agent *(manual, one-time)*
59
+
60
+ **Cursor**
61
+
62
+ 1. **Settings → Rules → Agent Skills** — enable **all** folders under `.cursor/skills/` (see `.cursor/skills/README.md`)
63
+ 2. **Reload MCP** — `.cursor/mcp.json` registers the `ai-spector` MCP server
64
+
65
+ **Claude Code**
66
+
67
+ 1. Skills load automatically from `.claude/skills/` (see `CLAUDE.md`)
68
+ 2. **Reload MCP** — `.mcp.json` registers the `ai-spector` MCP server
69
+
70
+ ---
71
+
72
+ ### Step 4 — Add source material
73
+
74
+ Drop requirements docs, meeting notes, user stories, or any input into `docs/data-source/`. Supported formats: `.md`, `.txt`, `.pdf`.
75
+
76
+ ---
77
+
78
+ ### Step 5 — Start the pipeline
79
+
80
+ In chat:
81
+
82
+ ```text
83
+ analyze my data source
44
84
  ```
45
85
 
46
- Ask in chat: **“generate HTML prototype”** — if no theme is saved, the agent recommends 3 themes, opens previews in your browser, and waits for you to pick. Or name one upfront: “prototype with stripe theme”.
86
+ Then continue in chat as needed — see [Workflow](#workflow) below.
47
87
 
48
- ```bash
49
- npx ai-spector prototype auth --username demo --password '<secret>' # once per project
50
- npx ai-spector prototype preview stripe --open # optional: preview yourself
51
- npx ai-spector prototype setup --theme vercel # after you choose
88
+ ---
89
+
90
+ ### Optional — CocoIndex semantic search
91
+
92
+ Enables `docs_search` and `graph_query_fuzzy` MCP tools. Requires Python ≥ 3.11.
93
+
94
+ In chat:
95
+
96
+ ```text
97
+ enable CocoIndex for this project
52
98
  ```
53
99
 
54
- Then ask: “generate HTML prototype for all screens” → `npx ai-spector prototype manifest` → `prototype validate --strict`.
100
+ See [docs/setup-guide.md](docs/setup-guide.md) for Postgres / OpenAI embedding options.
101
+
102
+ ---
103
+
104
+ ### Add another editor later
105
+
106
+ In chat:
107
+
108
+ ```text
109
+ add Claude Code support to ai-spector
110
+ sync ai-spector cursor skills
111
+ ```
112
+
113
+ After upgrading ai-spector, say **"sync ai-spector cursor skills"** in chat.
114
+
115
+ ---
116
+
117
+ ## Workflow
118
+
119
+ See `.cursor/WORKFLOW.md` (Cursor) or `CLAUDE.md` (Claude Code) after `init`.
120
+
121
+ ### First run
122
+
123
+ Say in chat:
124
+
125
+ ```text
126
+ “analyze the data source”
127
+ “validate the graph”
128
+ “generate the SRS”
129
+ “refresh the index”
130
+ ```
131
+
132
+ Then: **“generate basic design”** → **“generate detail design”** as needed.
133
+
134
+ **HTML prototype** — say **“generate HTML prototype”**. If no theme is saved, the agent recommends 3 themes, opens previews in your browser, and waits for you to pick. Or name one upfront: **“prototype with stripe theme”**.
135
+
136
+ Then: **“generate HTML prototype for all screens”**.
55
137
 
56
138
  ### Day to day
57
139
 
@@ -75,21 +157,46 @@ docs/data-source/ → analyze → validate graph → generate SRS → in
75
157
  → prototype setup → generate HTML screens
76
158
  ```
77
159
 
160
+ ---
161
+
78
162
  ## CLI (optional)
79
163
 
80
- For scripts or debugging: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. See `npx ai-spector --help`.
164
+ For scripts or debugging only: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. See `npx ai-spector --help`.
165
+
166
+ ---
81
167
 
82
168
  ## If something breaks
83
169
 
84
170
  | Issue | Fix |
85
171
  |-------|-----|
86
- | Graphify / MCP | Install `uv`, reload MCP — `.cursor/commands/_cli-failures.md` |
87
- | Validate errors after edits | `/index` |
88
- | Old slash commands | `npx ai-spector sync-cursor` |
172
+ | MCP tools unavailable | Reload MCP; confirm `.cursor/mcp.json` or `.mcp.json` has `ai-spector` server |
173
+ | Setup incomplete | In chat: **“check ai-spector setup”** |
174
+ | Skills not routing (Cursor) | Re-enable all folders under `.cursor/skills/` in Settings → Rules |
175
+ | Validate errors after edits | In chat: **“re-index the graph”** |
176
+ | Pre-commit hook missing | In chat: **“install ai-spector git hook”** |
177
+ | Agent stuck on CLI error | `.cursor/skills/ai-spector/references/cli-failures.md` |
178
+
179
+ ---
180
+
181
+ ## Node SDK
182
+
183
+ For **scripts, CI, or custom backends** that call the same operations as the CLI and MCP server:
184
+
185
+ - **[SDK guide](docs/sdk.md)** — install, entry points, examples, API reference
186
+
187
+ ```bash
188
+ npm install ai-spector
189
+ ```
190
+
191
+ ```ts
192
+ import { runIndex, runGraphImpact, validateGraph } from "ai-spector";
193
+ ```
194
+
195
+ ---
89
196
 
90
197
  ## Web / graph SDK
91
198
 
92
- For **browser or custom dashboards** (not the Cursor CLI), use the read-only npm package **`ai-spector-graph`**. Your backend serves repo JSON; the frontend loads it into `ProjectSession`.
199
+ For **browser or custom dashboards** (not the Cursor/Claude CLI), use the read-only npm package **`ai-spector-graph`**. Your backend serves repo JSON; the frontend loads it into `ProjectSession`.
93
200
 
94
201
  - **[Integration guide](docs/ai-spector-graph-integration-guide.md)** — architecture, API examples, React, recipes
95
202
  - **[API reference](docs/ai-spector-graph.md)** — types and exports
@@ -98,6 +205,8 @@ For **browser or custom dashboards** (not the Cursor CLI), use the read-only npm
98
205
  npm install ai-spector-graph
99
206
  ```
100
207
 
208
+ ---
209
+
101
210
  ## Develop
102
211
 
103
212
  ```bash
package/README.vi.md ADDED
@@ -0,0 +1,216 @@
1
+ # AI Spector
2
+
3
+ Công cụ làm tài liệu phần mềm trên **Cursor** hoặc **Claude Code**: sơ đồ liên kết, SRS, basic design, detail design. **Bạn chỉ cần nói trong chat** — agent sẽ tự chạy lệnh `ai-spector` hoặc MCP. Thường bạn không cần gõ lệnh terminal.
4
+
5
+ **Cần có:** Node 20+, Git, [Cursor](https://cursor.com) và/hoặc [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(không bắt buộc — dùng cho tìm kiếm thông minh với CocoIndex)*.
6
+
7
+ Hướng dẫn chi tiết: [docs/setup-guide.md](docs/setup-guide.md)
8
+
9
+ **English:** [README.md](README.md)
10
+
11
+ ---
12
+
13
+ ## Cài đặt (làm một lần)
14
+
15
+ ### Cần chuẩn bị gì
16
+
17
+ | Cần có | Cách kiểm tra |
18
+ |--------|---------------|
19
+ | Node.js ≥ 20 | `node --version` |
20
+ | Git | `git status` |
21
+ | Cursor và/hoặc Claude Code | Mở IDE ở thư mục gốc project |
22
+ | Python ≥ 3.11 *(không bắt buộc)* | chỉ cần nếu bật CocoIndex |
23
+
24
+ ---
25
+
26
+ ### Bước 1 — Khởi tạo project *(bước duy nhất cần gõ lệnh)*
27
+
28
+ Chạy một lần ở thư mục gốc project. **Lần đầu** cần thêm `--registry` để `npx` tải gói từ registry nội bộ (`http://10.101.0.239:4873`). **Không cần** `npm login`.
29
+
30
+ ```bash
31
+ npx ai-spector@latest init --registry http://10.101.0.239:4873
32
+ ```
33
+
34
+ Lệnh sẽ hỏi: dùng Cursor, Claude Code hay cả hai; ngôn ngữ tài liệu; git hook; và có bật CocoIndex không.
35
+
36
+ Sau khi chạy xong sẽ có:
37
+
38
+ - `.ai-spector/` — cấu hình, sơ đồ, mẫu tài liệu
39
+ - `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
40
+ - **Cursor:** `.cursor/` — skills, rules, `mcp.json`
41
+ - **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
42
+ - Hook git trước khi commit *(nếu project có git)*
43
+
44
+ ---
45
+
46
+ ### Bước 2 — Hoàn tất setup trong chat
47
+
48
+ Mở project bằng **Cursor** hoặc **Claude Code**, rồi gõ:
49
+
50
+ ```text
51
+ setup ai-spector project
52
+ ```
53
+
54
+ Agent sẽ cài gói npm (nếu thiếu), kiểm tra xem còn thiếu gì, hỏi bạn có muốn bật CocoIndex không, và nhắc các bước còn lại.
55
+
56
+ ---
57
+
58
+ ### Bước 3 — Bật skills *(làm tay một lần)*
59
+
60
+ **Cursor**
61
+
62
+ 1. Vào **Settings → Rules → Agent Skills** — bật **hết** các thư mục trong `.cursor/skills/` (xem `.cursor/skills/README.md`)
63
+ 2. **Reload MCP** — file `.cursor/mcp.json` đã cấu hình sẵn server `ai-spector`
64
+
65
+ **Claude Code**
66
+
67
+ 1. Skills tự load từ `.claude/skills/` (xem `CLAUDE.md`)
68
+ 2. **Reload MCP** — file `.mcp.json` đã cấu hình sẵn server `ai-spector`
69
+
70
+ ---
71
+
72
+ ### Bước 4 — Thêm tài liệu đầu vào
73
+
74
+ Copy file yêu cầu, biên bản họp, user story… vào `docs/data-source/`. Hỗ trợ: `.md`, `.txt`, `.pdf`.
75
+
76
+ ---
77
+
78
+ ### Bước 5 — Bắt đầu làm việc
79
+
80
+ Trong chat, gõ:
81
+
82
+ ```text
83
+ analyze my data source
84
+ ```
85
+
86
+ Các bước tiếp theo cũng nói trong chat — xem [Quy trình làm việc](#quy-trình-làm-việc) bên dưới.
87
+
88
+ ---
89
+
90
+ ### Tùy chọn — Bật CocoIndex (tìm kiếm thông minh)
91
+
92
+ Giúp agent tìm tài liệu và sơ đồ theo nghĩa, không chỉ theo từ khóa. Cần Python ≥ 3.11.
93
+
94
+ Trong chat:
95
+
96
+ ```text
97
+ enable CocoIndex for this project
98
+ ```
99
+
100
+ Xem thêm [docs/setup-guide.md](docs/setup-guide.md) nếu muốn dùng Postgres hoặc OpenAI embedding.
101
+
102
+ ---
103
+
104
+ ### Thêm editor khác sau này
105
+
106
+ Trong chat:
107
+
108
+ ```text
109
+ add Claude Code support to ai-spector
110
+ sync ai-spector cursor skills
111
+ ```
112
+
113
+ Sau khi nâng cấp ai-spector, gõ **"sync ai-spector cursor skills"** trong chat.
114
+
115
+ ---
116
+
117
+ ## Quy trình làm việc
118
+
119
+ Sau khi `init`, xem thêm `.cursor/WORKFLOW.md` (Cursor) hoặc `CLAUDE.md` (Claude Code).
120
+
121
+ ### Lần đầu chạy
122
+
123
+ Gõ trong chat:
124
+
125
+ ```text
126
+ “analyze the data source”
127
+ “validate the graph”
128
+ “generate the SRS”
129
+ “refresh the index”
130
+ ```
131
+
132
+ Tiếp theo: **“generate basic design”** → **“generate detail design”** khi cần.
133
+
134
+ **Làm prototype HTML** — gõ **“generate HTML prototype”**. Nếu chưa chọn theme, agent gợi ý 3 theme, mở xem trên trình duyệt, rồi chờ bạn chọn. Hoặc nói luôn: **“prototype with stripe theme”**.
135
+
136
+ Sau đó: **“generate HTML prototype for all screens”**.
137
+
138
+ ### Dùng hàng ngày
139
+
140
+ | Khi nào | Gõ trong chat (ví dụ) |
141
+ |---------|------------------------|
142
+ | Có tài liệu nguồn mới hoặc sửa | “analyze data source” |
143
+ | Kiểm tra sơ đồ | “validate the graph” |
144
+ | Tạo lại tài liệu | “generate SRS”, “generate basic design”, … |
145
+ | Làm prototype HTML | “generate prototype with stripe theme” |
146
+ | Chọn theme | “help me pick a prototype theme”, “show me theme options” |
147
+ | Vừa sửa tài liệu xong | “re-index the graph” |
148
+ | Xem phần nào bị ảnh hưởng | “what’s the impact of my changes” |
149
+ | Xử lý comment | “resolve comments” |
150
+ | Xem sơ đồ trực quan | “visualize the graph” |
151
+
152
+ ### Quy trình thường gặp
153
+
154
+ ```text
155
+ docs/data-source/ → analyze → validate graph → generate SRS → index
156
+ → generate basic design → generate detail design
157
+ → prototype setup → generate HTML screens
158
+ ```
159
+
160
+ ---
161
+
162
+ ## CLI (nếu cần)
163
+
164
+ Chỉ dùng khi viết script hoặc debug: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. Gõ `npx ai-spector --help` để xem đầy đủ.
165
+
166
+ ---
167
+
168
+ ## Gặp lỗi thì làm gì
169
+
170
+ | Lỗi | Cách xử lý |
171
+ |-----|------------|
172
+ | MCP không chạy | Reload MCP; kiểm tra `.cursor/mcp.json` hoặc `.mcp.json` có server `ai-spector` |
173
+ | Setup chưa xong | Trong chat: **“check ai-spector setup”** |
174
+ | Agent không hiểu lệnh (Cursor) | Bật lại hết thư mục trong `.cursor/skills/` ở Settings → Rules |
175
+ | Validate báo lỗi sau khi sửa | Trong chat: **“re-index the graph”** |
176
+ | Thiếu hook git | Trong chat: **“install ai-spector git hook”** |
177
+ | Agent bị kẹt vì lỗi CLI | Xem `.cursor/skills/ai-spector/references/cli-failures.md` |
178
+
179
+ ---
180
+
181
+ ## Node SDK
182
+
183
+ Dùng khi bạn viết **script, CI, hoặc backend tùy chỉnh** — cùng các thao tác typed như CLI và MCP:
184
+
185
+ - **[Hướng dẫn SDK](docs/sdk.md)** — cài đặt, entry points, ví dụ, tham chiếu API
186
+
187
+ ```bash
188
+ npm install ai-spector
189
+ ```
190
+
191
+ ```ts
192
+ import { runIndex, runGraphImpact, validateGraph } from "ai-spector";
193
+ ```
194
+
195
+ ---
196
+
197
+ ## Web / graph SDK
198
+
199
+ Dùng khi bạn muốn **hiển thị sơ đồ trên web hoặc dashboard riêng** (không qua Cursor/Claude). Cài gói **`ai-spector-graph`**, backend trả JSON từ repo, frontend load vào `ProjectSession`.
200
+
201
+ - **[Hướng dẫn tích hợp](docs/ai-spector-graph-integration-guide.md)** — kiến trúc, ví dụ API, React
202
+ - **[Tham chiếu API](docs/ai-spector-graph.md)** — types và exports
203
+
204
+ ```bash
205
+ npm install ai-spector-graph
206
+ ```
207
+
208
+ ---
209
+
210
+ ## Phát triển (cho người đóng góp code)
211
+
212
+ ```bash
213
+ npm install && npm run build && npm test
214
+ ```
215
+
216
+ MIT — [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-spector",
3
- "version": "0.8.7",
3
+ "version": "0.8.15",
4
4
  "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -34,6 +34,7 @@
34
34
  "scaffold",
35
35
  "assets",
36
36
  "README.md",
37
+ "README.vi.md",
37
38
  "LICENSE"
38
39
  ],
39
40
  "exports": {
@@ -63,7 +64,9 @@
63
64
  "graph:visualize": "node dist/cli.js -r example graph visualize --open",
64
65
  "ai-spector": "node dist/cli.js",
65
66
  "themes:install-previews": "node dist/cli.js prototype install-previews",
66
- "themes:preview": "node dist/cli.js prototype preview"
67
+ "themes:preview": "node dist/cli.js prototype preview",
68
+ "deploy": "bash scripts/deploy.sh",
69
+ "deploy:npm": "bash scripts/deploy.sh --npm"
67
70
  },
68
71
  "dependencies": {
69
72
  "@modelcontextprotocol/sdk": "^1.29.0",