milens 0.6.3 → 0.6.5
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/.agents/skills/adapters/SKILL.md +51 -0
- package/.agents/skills/analyzer/SKILL.md +77 -0
- package/.agents/skills/apps/SKILL.md +66 -0
- package/.agents/skills/docs/SKILL.md +73 -0
- package/.agents/skills/milens/SKILL.md +198 -0
- package/.agents/skills/milens-architect/SKILL.md +128 -0
- package/.agents/skills/milens-code-review/SKILL.md +186 -0
- package/.agents/skills/milens-debugger/SKILL.md +141 -0
- package/.agents/skills/milens-eval/SKILL.md +221 -0
- package/.agents/skills/milens-plan/SKILL.md +227 -0
- package/.agents/skills/milens-refactor-clean/SKILL.md +209 -0
- package/.agents/skills/milens-security-review/SKILL.md +224 -0
- package/.agents/skills/milens-tdd/SKILL.md +156 -0
- package/.agents/skills/orchestrator/SKILL.md +59 -0
- package/.agents/skills/parser/SKILL.md +81 -0
- package/.agents/skills/root/SKILL.md +86 -0
- package/.agents/skills/scripts/SKILL.md +45 -0
- package/.agents/skills/security/SKILL.md +65 -0
- package/.agents/skills/server/SKILL.md +72 -0
- package/.agents/skills/store/SKILL.md +75 -0
- package/.agents/skills/test/SKILL.md +121 -0
- package/LICENSE +21 -75
- package/README.md +356 -453
- package/adapters/README.md +107 -0
- package/adapters/claude-code/.claude/mcp.json +9 -0
- package/adapters/claude-code/CLAUDE.md +58 -0
- package/adapters/codex/.codex/codex.md +52 -0
- package/adapters/copilot/.github/copilot-instructions.md +62 -0
- package/adapters/cursor/.cursorrules +9 -0
- package/adapters/gemini/.gemini/context.md +58 -0
- package/adapters/opencode/.opencode/config.json +9 -0
- package/adapters/opencode/AGENTS.md +58 -0
- package/adapters/zed/.zed/settings.json +8 -0
- package/dist/agents-md.d.ts +3 -0
- package/dist/agents-md.d.ts.map +1 -0
- package/dist/agents-md.js +114 -0
- package/dist/agents-md.js.map +1 -0
- package/dist/analyzer/engine.d.ts +1 -0
- package/dist/analyzer/engine.d.ts.map +1 -1
- package/dist/analyzer/engine.js +37 -7
- package/dist/analyzer/engine.js.map +1 -1
- package/dist/cli.js +1472 -406
- package/dist/cli.js.map +1 -1
- package/dist/metrics.d.ts +51 -0
- package/dist/metrics.d.ts.map +1 -0
- package/dist/metrics.js +64 -0
- package/dist/metrics.js.map +1 -0
- package/dist/orchestrator/orchestrator.d.ts +65 -0
- package/dist/orchestrator/orchestrator.d.ts.map +1 -0
- package/dist/orchestrator/orchestrator.js +178 -0
- package/dist/orchestrator/orchestrator.js.map +1 -0
- package/dist/orchestrator/reporter.d.ts +15 -0
- package/dist/orchestrator/reporter.d.ts.map +1 -0
- package/dist/orchestrator/reporter.js +38 -0
- package/dist/orchestrator/reporter.js.map +1 -0
- package/dist/parser/lang-go.js +47 -47
- package/dist/parser/lang-java.js +29 -29
- package/dist/parser/lang-js.js +105 -105
- package/dist/parser/lang-php.js +38 -38
- package/dist/parser/lang-py.js +34 -34
- package/dist/parser/lang-ruby.js +14 -14
- package/dist/parser/lang-rust.js +30 -30
- package/dist/parser/lang-ts.js +191 -191
- package/dist/security/deps.d.ts +38 -0
- package/dist/security/deps.d.ts.map +1 -0
- package/dist/security/deps.js +685 -0
- package/dist/security/deps.js.map +1 -0
- package/dist/security/rules.d.ts +42 -0
- package/dist/security/rules.d.ts.map +1 -0
- package/dist/security/rules.js +943 -0
- package/dist/security/rules.js.map +1 -0
- package/dist/server/hooks.d.ts +29 -0
- package/dist/server/hooks.d.ts.map +1 -0
- package/dist/server/hooks.js +332 -0
- package/dist/server/hooks.js.map +1 -0
- package/dist/server/mcp-prompts.d.ts +277 -0
- package/dist/server/mcp-prompts.d.ts.map +1 -0
- package/dist/server/mcp-prompts.js +627 -0
- package/dist/server/mcp-prompts.js.map +1 -0
- package/dist/server/mcp.d.ts.map +1 -1
- package/dist/server/mcp.js +1030 -652
- package/dist/server/mcp.js.map +1 -1
- package/dist/server/test-plan.d.ts +20 -0
- package/dist/server/test-plan.d.ts.map +1 -0
- package/dist/server/test-plan.js +100 -0
- package/dist/server/test-plan.js.map +1 -0
- package/dist/server/watcher.d.ts +39 -0
- package/dist/server/watcher.d.ts.map +1 -0
- package/dist/server/watcher.js +134 -0
- package/dist/server/watcher.js.map +1 -0
- package/dist/skills.js +197 -153
- package/dist/skills.js.map +1 -1
- package/dist/store/annotations.d.ts +41 -0
- package/dist/store/annotations.d.ts.map +1 -0
- package/dist/store/annotations.js +195 -0
- package/dist/store/annotations.js.map +1 -0
- package/dist/store/confidence.d.ts +28 -0
- package/dist/store/confidence.d.ts.map +1 -0
- package/dist/store/confidence.js +109 -0
- package/dist/store/confidence.js.map +1 -0
- package/dist/store/db.d.ts +53 -14
- package/dist/store/db.d.ts.map +1 -1
- package/dist/store/db.js +447 -240
- package/dist/store/db.js.map +1 -1
- package/dist/store/schema.sql +143 -116
- package/dist/store/vectors.js +2 -2
- package/dist/types.d.ts +101 -0
- package/dist/types.d.ts.map +1 -1
- package/docs/README.md +22 -0
- package/package.json +81 -66
- package/dist/gateway/analyzer.d.ts +0 -6
- package/dist/gateway/analyzer.d.ts.map +0 -1
- package/dist/gateway/analyzer.js +0 -218
- package/dist/gateway/analyzer.js.map +0 -1
- package/dist/gateway/cache.d.ts +0 -35
- package/dist/gateway/cache.d.ts.map +0 -1
- package/dist/gateway/cache.js +0 -175
- package/dist/gateway/cache.js.map +0 -1
- package/dist/gateway/config.d.ts +0 -10
- package/dist/gateway/config.d.ts.map +0 -1
- package/dist/gateway/config.js +0 -167
- package/dist/gateway/config.js.map +0 -1
- package/dist/gateway/context-memory.d.ts +0 -68
- package/dist/gateway/context-memory.d.ts.map +0 -1
- package/dist/gateway/context-memory.js +0 -157
- package/dist/gateway/context-memory.js.map +0 -1
- package/dist/gateway/observability.d.ts +0 -83
- package/dist/gateway/observability.d.ts.map +0 -1
- package/dist/gateway/observability.js +0 -152
- package/dist/gateway/observability.js.map +0 -1
- package/dist/gateway/privacy.d.ts +0 -27
- package/dist/gateway/privacy.d.ts.map +0 -1
- package/dist/gateway/privacy.js +0 -139
- package/dist/gateway/privacy.js.map +0 -1
- package/dist/gateway/providers.d.ts +0 -66
- package/dist/gateway/providers.d.ts.map +0 -1
- package/dist/gateway/providers.js +0 -377
- package/dist/gateway/providers.js.map +0 -1
- package/dist/gateway/router.d.ts +0 -18
- package/dist/gateway/router.d.ts.map +0 -1
- package/dist/gateway/router.js +0 -102
- package/dist/gateway/router.js.map +0 -1
- package/dist/gateway/server.d.ts +0 -20
- package/dist/gateway/server.d.ts.map +0 -1
- package/dist/gateway/server.js +0 -387
- package/dist/gateway/server.js.map +0 -1
- package/dist/gateway/translator.d.ts +0 -19
- package/dist/gateway/translator.d.ts.map +0 -1
- package/dist/gateway/translator.js +0 -340
- package/dist/gateway/translator.js.map +0 -1
- package/dist/gateway/types.d.ts +0 -215
- package/dist/gateway/types.d.ts.map +0 -1
- package/dist/gateway/types.js +0 -3
- package/dist/gateway/types.js.map +0 -1
- package/dist/store/gateway-schema.sql +0 -53
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: milens-plan
|
|
3
|
+
description: Implementation Planning — research codebase, analyze impact, plan tests, and produce a structured implementation plan
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# milens-plan — Implementation Planning
|
|
7
|
+
|
|
8
|
+
Research the codebase end-to-end before writing code: understand structure, trace execution, assess blast radius, plan tests, and produce a structured plan following the ECC Planner specification.
|
|
9
|
+
|
|
10
|
+
## Tools Required
|
|
11
|
+
|
|
12
|
+
| Tool | Purpose |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `mcp_milens_codebase_summary` | High-level project overview (languages, file count, domain count) |
|
|
15
|
+
| `mcp_milens_domains` | Module clusters showing logical groupings |
|
|
16
|
+
| `mcp_milens_routes` | API endpoints inventory with handler mappings |
|
|
17
|
+
| `mcp_milens_smart_context` | Intent-aware symbol analysis (edit intent) |
|
|
18
|
+
| `mcp_milens_edit_check` | Pre-edit safety: callers, export status, re-export chains, warnings |
|
|
19
|
+
| `mcp_milens_trace` | Execution flow from entrypoints to target |
|
|
20
|
+
| `mcp_milens_impact` | Blast radius: what breaks if target changes |
|
|
21
|
+
| `mcp_milens_test_plan` | Mock strategy + test scenarios for a symbol |
|
|
22
|
+
| `mcp_milens_test_coverage_gaps` | Related untested symbols |
|
|
23
|
+
|
|
24
|
+
> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
|
|
25
|
+
|
|
26
|
+
## Workflow
|
|
27
|
+
|
|
28
|
+
### Step 1: Project Overview
|
|
29
|
+
|
|
30
|
+
Understand the codebase at a high level.
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
mcp_milens_codebase_summary({repo: "<workspaceRoot>"})
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Captures: languages, file counts, total symbols, top-level domains, entry points.
|
|
37
|
+
|
|
38
|
+
### Step 2: Domain Structure
|
|
39
|
+
|
|
40
|
+
Map module clusters to understand logical groupings.
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
mcp_milens_domains({repo: "<workspaceRoot>"})
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Shows which files form cohesive modules based on the dependency graph. Helps identify:
|
|
47
|
+
- Where the target code lives
|
|
48
|
+
- Which domains interact with it
|
|
49
|
+
- Natural boundaries for the change
|
|
50
|
+
|
|
51
|
+
### Step 3: API Surface (optional)
|
|
52
|
+
|
|
53
|
+
If the project is a web service, inventory the endpoints.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
mcp_milens_routes({repo: "<workspaceRoot>"})
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Useful when the change touches:
|
|
60
|
+
- Route handlers
|
|
61
|
+
- Middleware
|
|
62
|
+
- Request/response types
|
|
63
|
+
- Authentication/authorization
|
|
64
|
+
|
|
65
|
+
### Step 4: Target Analysis
|
|
66
|
+
|
|
67
|
+
Zoom in on the specific symbol to change.
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
mcp_milens_smart_context({name: "<symbolName>", intent: "edit", repo: "<workspaceRoot>"})
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The `edit` intent returns: callers, export status, and immediate blast radius — only what matters for editing.
|
|
74
|
+
|
|
75
|
+
### Step 5: Pre-Edit Safety Check
|
|
76
|
+
|
|
77
|
+
Run `edit_check` for pre-edit warnings.
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
mcp_milens_edit_check({name: "<symbolName>", repo: "<workspaceRoot>"})
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
This returns:
|
|
84
|
+
- **Callers** — who calls this symbol
|
|
85
|
+
- **Export status** — whether it's public API
|
|
86
|
+
- **Re-export chains** — barrel file re-exports that extend blast radius
|
|
87
|
+
- **Warnings** — breaking change risks, high fan-in, etc.
|
|
88
|
+
|
|
89
|
+
### Step 6: Execution Flow
|
|
90
|
+
|
|
91
|
+
Trace how the target gets called at runtime.
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
mcp_milens_trace({name: "<symbolName>", direction: "to", repo: "<workspaceRoot>"})
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Shows the call chains from entrypoints down to this symbol. Critical for understanding:
|
|
98
|
+
- What triggers this code
|
|
99
|
+
- What data flows into it
|
|
100
|
+
- What side effects it may have
|
|
101
|
+
|
|
102
|
+
### Step 7: Blast Radius
|
|
103
|
+
|
|
104
|
+
Assess the full impact of the proposed change.
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
mcp_milens_impact({target: "<symbolName>", depth: 3, repo: "<workspaceRoot>"})
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Shows all symbols that break if the target changes, up to the specified depth.
|
|
111
|
+
- If depth-1 dependents > 5: **STOP and warn** before proceeding
|
|
112
|
+
- If depth-3 dependents > 20: **consider a facade or adapter pattern**
|
|
113
|
+
|
|
114
|
+
### Step 8: Test Strategy
|
|
115
|
+
|
|
116
|
+
Plan the testing approach.
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
mcp_milens_test_plan({name: "<symbolName>", repo: "<workspaceRoot>"})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Covers:
|
|
123
|
+
- Mock strategy (what to isolate)
|
|
124
|
+
- Test scenarios (happy path, edge cases, error handling)
|
|
125
|
+
- Affected test files
|
|
126
|
+
|
|
127
|
+
### Step 9: Coverage Gaps (optional)
|
|
128
|
+
|
|
129
|
+
Check for related symbols that lack test coverage.
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>", limit: 10})
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
If neighboring symbols are untested, consider adding tests as part of the change.
|
|
136
|
+
|
|
137
|
+
### Step 10: Produce Implementation Plan
|
|
138
|
+
|
|
139
|
+
Consolidate all findings into a structured plan:
|
|
140
|
+
|
|
141
|
+
1. **Executive Summary** — what changes, why, at what risk level
|
|
142
|
+
2. **Codebase Context** — domains, routes, and structure (from Steps 1-3)
|
|
143
|
+
3. **Symbol Analysis** — target details, callers, execution flow (from Steps 4-6)
|
|
144
|
+
4. **Impact Assessment** — blast radius, breaking change risks, dependents map (from Step 7)
|
|
145
|
+
5. **Test Strategy** — test plan, mock strategy, coverage gaps (from Steps 8-9)
|
|
146
|
+
6. **Implementation Steps** — ordered, actionable steps with file paths
|
|
147
|
+
7. **Risk Mitigation** — rollback plan, feature flags, phased deployment options
|
|
148
|
+
|
|
149
|
+
## Example Session
|
|
150
|
+
|
|
151
|
+
### Input
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
"plan a change to add rate limiting to the login handler"
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Tool Calls
|
|
158
|
+
|
|
159
|
+
**Step 1:**
|
|
160
|
+
```
|
|
161
|
+
mcp_milens_codebase_summary({repo: "/home/user/project"})
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**Output:** TypeScript project, 120 files, 850 symbols, 5 domains (auth, routes, db, utils, config).
|
|
165
|
+
|
|
166
|
+
**Step 2:**
|
|
167
|
+
```
|
|
168
|
+
mcp_milens_domains({repo: "/home/user/project"})
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
**Output:** `auth` domain contains login handler, token manager, session store.
|
|
172
|
+
|
|
173
|
+
**Step 4:**
|
|
174
|
+
```
|
|
175
|
+
mcp_milens_smart_context({name: "loginHandler", intent: "edit", repo: "/home/user/project"})
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**Output:** 3 callers (Express route, rate limiter middleware, integration test), no re-exports.
|
|
179
|
+
|
|
180
|
+
**Step 5:**
|
|
181
|
+
```
|
|
182
|
+
mcp_milens_edit_check({name: "loginHandler", repo: "/home/user/project"})
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**Output:** 3 callers, exported, no re-export chains, **WARNING: exported function — changing signature is a breaking change.**
|
|
186
|
+
|
|
187
|
+
**Step 6:**
|
|
188
|
+
```
|
|
189
|
+
mcp_milens_trace({name: "loginHandler", direction: "to", repo: "/home/user/project"})
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
**Output:** Chain: `Express router → authMiddleware → loginHandler → tokenService.sign()`
|
|
193
|
+
|
|
194
|
+
**Step 7:**
|
|
195
|
+
```
|
|
196
|
+
mcp_milens_impact({target: "loginHandler", depth: 3, repo: "/home/user/project"})
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
**Output:** Depth-1: 3 dependents (route, integration test, auth docs). Depth-2: 8 dependents. Depth-3: 14 dependents. **No STOP threshold breached.**
|
|
200
|
+
|
|
201
|
+
**Step 8:**
|
|
202
|
+
```
|
|
203
|
+
mcp_milens_test_plan({name: "loginHandler", repo: "/home/user/project"})
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
**Output:** Mock `tokenService`, `userStore`. 4 test scenarios: valid login, invalid password, rate limit exceeded, database failure.
|
|
207
|
+
|
|
208
|
+
**Step 10 — Plan produced** (see plan format above).
|
|
209
|
+
|
|
210
|
+
## Best Practices
|
|
211
|
+
|
|
212
|
+
1. **Never skip impact analysis.** Even a "small" change can ripple through re-export chains. `impact` catches what intuition misses.
|
|
213
|
+
2. **Use `edit` intent for `smart_context`** when planning edits — it omits irrelevant detail and focuses on callers and blast radius.
|
|
214
|
+
3. **Stop at depth-3 for impact.** Deeper assessment rarely changes the implementation strategy but adds noise.
|
|
215
|
+
4. **Trace before planning.** Understanding the execution path prevents "add rate limiter after JWT decode" mistakes where ordering matters.
|
|
216
|
+
5. **Write the plan before the code.** The structured plan from Step 10 is the deliverable. Implementation follows the plan — not the other way around.
|
|
217
|
+
|
|
218
|
+
## Quality Gate
|
|
219
|
+
|
|
220
|
+
| Criteria | Pass | Fail |
|
|
221
|
+
|---|---|---|
|
|
222
|
+
| Codebase overview | All 3 overview tools succeed (summary, domains, routes) | Any tool fails or returns empty |
|
|
223
|
+
| Target analysis | `smart_context` + `edit_check` both run | Either tool skipped for the target symbol |
|
|
224
|
+
| Impact assessment | `impact` at depth 3 completed, dependents counted | Impact not run or depth < 3 |
|
|
225
|
+
| Blast radius check | < 5 depth-1 dependents OR user warned and confirmed | > 5 depth-1 dependents without user confirmation |
|
|
226
|
+
| Test plan | `test_plan` covers happy path, edge cases, and errors | Less than 3 scenarios in the plan |
|
|
227
|
+
| Implementation plan | All 7 sections of the plan filled | Missing sections or incomplete analysis |
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: milens-refactor-clean
|
|
3
|
+
description: Safe Refactoring with Blast Radius Check — find dead code, verify impact, remove safely, and verify test coverage
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# milens-refactor-clean — Safe Refactoring with Blast Radius Check
|
|
7
|
+
|
|
8
|
+
Identify dead or unwanted code, verify it's truly unused via context and text search, assess blast radius, remove safely, and confirm only expected files changed.
|
|
9
|
+
|
|
10
|
+
## Tools Required
|
|
11
|
+
|
|
12
|
+
| Tool | Purpose |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `mcp_milens_find_dead_code` | Find exported symbols with zero incoming references |
|
|
15
|
+
| `mcp_milens_context` | Verify a symbol is truly unused (incoming refs check) |
|
|
16
|
+
| `mcp_milens_impact` | Blast radius assessment before removal |
|
|
17
|
+
| `mcp_milens_grep` | Text search for symbol name in configs, templates, docs |
|
|
18
|
+
| `mcp_milens_detect_changes` | Post-refactor verification of changed files |
|
|
19
|
+
| `mcp_milens_test_impact` | Identify affected test files to run |
|
|
20
|
+
|
|
21
|
+
> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
|
|
22
|
+
|
|
23
|
+
## Workflow
|
|
24
|
+
|
|
25
|
+
### Step 1: Find Candidates
|
|
26
|
+
|
|
27
|
+
Identify exported symbols with zero incoming code references.
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
mcp_milens_find_dead_code({repo: "<workspaceRoot>", limit: 30})
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The output lists symbols that the static analysis graph shows as unreferenced. These are removal candidates.
|
|
34
|
+
|
|
35
|
+
**Important caveats:**
|
|
36
|
+
- Symbols used only via reflection, `eval`, or dynamic imports won't show references
|
|
37
|
+
- Side-effect-only imports (e.g., `import "./init"`) may look unused
|
|
38
|
+
- Config-based routing (React Router, NestJS decorators) may not resolve to references
|
|
39
|
+
|
|
40
|
+
### Step 2: Verify Truly Unused
|
|
41
|
+
|
|
42
|
+
For each candidate, run context to confirm zero incoming references.
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Look at the **incoming references** count:
|
|
49
|
+
- **0 incoming refs** — likely safe to remove
|
|
50
|
+
- **1+ incoming refs** — the symbol is used via paths the dead code detector missed; do NOT remove without further investigation
|
|
51
|
+
|
|
52
|
+
### Step 3: Check Text References
|
|
53
|
+
|
|
54
|
+
Even if context shows 0 code references, the symbol may appear in non-code files.
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
mcp_milens_grep({pattern: "<symbolName>", repo: "<workspaceRoot>"})
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Check for matches in:
|
|
61
|
+
- **Config files** — `.json`, `.yaml`, `.toml`, `.env`
|
|
62
|
+
- **Template files** — `.html`, `.vue`, `.jsx`, `.tsx` (usage in markup)
|
|
63
|
+
- **Documentation** — `*.md`, `*.mdx`
|
|
64
|
+
- **Route definitions** — string-based routing (Express, FastAPI)
|
|
65
|
+
- **Package scripts** — `package.json` scripts referencing the symbol
|
|
66
|
+
|
|
67
|
+
### Step 4: Assess Blast Radius
|
|
68
|
+
|
|
69
|
+
Before deleting, understand what removing the symbol would affect (even if nothing references it now — for safety).
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
mcp_milens_impact({target: "<symbolName>", depth: 3, repo: "<workspaceRoot>"})
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Check:
|
|
76
|
+
- **Depth-1 dependents** — should be 0 for true dead code
|
|
77
|
+
- **Transitive dependents** — if > 0, something references this indirectly
|
|
78
|
+
|
|
79
|
+
### Step 5: Remove the Code
|
|
80
|
+
|
|
81
|
+
After verification, remove:
|
|
82
|
+
1. The symbol itself (function, class, interface, etc.)
|
|
83
|
+
2. Its imports if they're now unused
|
|
84
|
+
3. Related tests (now orphaned)
|
|
85
|
+
|
|
86
|
+
### Step 6: Verify Change Scope
|
|
87
|
+
|
|
88
|
+
Confirm only expected files changed.
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
mcp_milens_detect_changes({repo: "<workspaceRoot>"})
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Check that:
|
|
95
|
+
- Only the files you intended to modify appear
|
|
96
|
+
- No config files, lockfiles, or unrelated modules changed
|
|
97
|
+
- No accidental deletions
|
|
98
|
+
|
|
99
|
+
### Step 7: Run Affected Tests
|
|
100
|
+
|
|
101
|
+
Identify and run tests impacted by the removal.
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
mcp_milens_test_impact({repo: "<workspaceRoot>"})
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
This lists test files that reference the removed code or its dependents. Run all affected tests to ensure nothing is broken.
|
|
108
|
+
|
|
109
|
+
## Example Session
|
|
110
|
+
|
|
111
|
+
### Input
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
"remove unused utility functions from the helpers module"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Tool Calls
|
|
118
|
+
|
|
119
|
+
**Step 1 — Find candidates:**
|
|
120
|
+
```
|
|
121
|
+
mcp_milens_find_dead_code({repo: "/home/user/project", limit: 30})
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Output:**
|
|
125
|
+
```
|
|
126
|
+
1. formatDateLegacy [function] src/utils/helpers.ts:45
|
|
127
|
+
2. unusedValidator [function] src/utils/helpers.ts:78
|
|
128
|
+
3. OldUserType [interface] src/types/legacy.ts:12
|
|
129
|
+
4. debugLog [function] src/utils/helpers.ts:102
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**Step 2 — Verify context for each:**
|
|
133
|
+
```
|
|
134
|
+
mcp_milens_context({name: "formatDateLegacy", repo: "/home/user/project"})
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
**Output:** 0 incoming refs, 1 outgoing dep (calls `toISOString`). Safe to remove.
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
mcp_milens_context({name: "unusedValidator", repo: "/home/user/project"})
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Output:** 0 incoming refs. Safe to remove.
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
mcp_milens_context({name: "debugLog", repo: "/home/user/project"})
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
**Output:** 3 incoming refs — used in `server.ts`, `logger.ts`, `middleware.ts`. NOT dead code — skip.
|
|
150
|
+
|
|
151
|
+
**Step 3 — Text search for remaining candidates:**
|
|
152
|
+
```
|
|
153
|
+
mcp_milens_grep({pattern: "formatDateLegacy", repo: "/home/user/project"})
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
**Output:** 1 match in `docs/migration-guide.md` — documentation reference only, still safe to remove with a docs update.
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
mcp_milens_grep({pattern: "OldUserType", repo: "/home/user/project"})
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
**Output:** 0 matches across all files. Fully dead.
|
|
163
|
+
|
|
164
|
+
**Step 4 — Impact check:**
|
|
165
|
+
```
|
|
166
|
+
mcp_milens_impact({target: "formatDateLegacy", depth: 3, repo: "/home/user/project"})
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Output:** Depth-1: 0 dependents. No blast radius.
|
|
170
|
+
|
|
171
|
+
**Step 5 — Remove `formatDateLegacy` and `OldUserType`** in file editor
|
|
172
|
+
|
|
173
|
+
**Step 6 — Verify scope:**
|
|
174
|
+
```
|
|
175
|
+
mcp_milens_detect_changes({repo: "/home/user/project"})
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**Output:**
|
|
179
|
+
```
|
|
180
|
+
Changed files:
|
|
181
|
+
src/utils/helpers.ts [modified] — expected
|
|
182
|
+
src/types/legacy.ts [modified] — expected
|
|
183
|
+
docs/migration-guide.md [modified] — expected (updated reference)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**Step 7 — Test impact:**
|
|
187
|
+
```
|
|
188
|
+
mcp_milens_test_impact({repo: "/home/user/project"})
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**Output:** 2 affected test files — `src/__tests__/helpers.test.ts`, `src/__tests__/types.test.ts`. Both pass after updating.
|
|
192
|
+
|
|
193
|
+
## Best Practices
|
|
194
|
+
|
|
195
|
+
1. **Context beats dead-code detection.** A symbol tagged as "dead" by the detector may still be used via dynamic patterns. Always verify with `context` before deleting.
|
|
196
|
+
2. **Grep is the backstop.** `context` only catches code-level references. `grep` catches template usage, string-based routing, config files, and docs. Never skip Step 3.
|
|
197
|
+
3. **Remove in small batches.** Delete 1-3 symbols per commit. Large-scale deletion makes `detect_changes` harder to verify and `git bisect` harder to use.
|
|
198
|
+
4. **Update docs proactively.** If `grep` finds documentation references, update or remove them in the same commit. Stale docs referencing deleted symbols are worse than no docs.
|
|
199
|
+
5. **Test impact is not optional.** Removing code can break tests that import the symbol directly. Run `test_impact` and fix before committing.
|
|
200
|
+
|
|
201
|
+
## Quality Gate
|
|
202
|
+
|
|
203
|
+
| Criteria | Pass | Fail |
|
|
204
|
+
|---|---|---|
|
|
205
|
+
| Dead code identified | `find_dead_code` returns candidates | Tool fails or returns empty (with large codebase) |
|
|
206
|
+
| Verification complete | `context` + `grep` run for every candidate marked for removal | Any candidate removed without both checks |
|
|
207
|
+
| Blast radius safe | All removed symbols have 0 depth-1 dependents | Any symbol with dependents removed without justification |
|
|
208
|
+
| Change scope clean | `detect_changes` shows only expected files | Unexpected files in the diff |
|
|
209
|
+
| Tests pass | All `test_impact` files pass | Any affected test file fails |
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: milens-security-review
|
|
3
|
+
description: Security Audit — scan for secrets, hidden unicode, dangerous patterns, data leaks, and produce a security report
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# milens-security-review — Security Audit
|
|
7
|
+
|
|
8
|
+
Scan the codebase for security vulnerabilities: exposed secrets, hidden unicode (Trojan Source), dangerous code patterns, data leakage, and unexpected file changes.
|
|
9
|
+
|
|
10
|
+
## Tools Required
|
|
11
|
+
|
|
12
|
+
| Tool | Purpose |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `mcp_milens_review_pr` | Initial risk assessment of changed files and symbols |
|
|
15
|
+
| `mcp_milens_grep` | Pattern search for secrets, unicode, dangerous calls, data leaks |
|
|
16
|
+
| `mcp_milens_review_symbol` | Deep-dive risk analysis on high-risk symbols |
|
|
17
|
+
| `mcp_milens_detect_changes` | Verify only expected files changed |
|
|
18
|
+
|
|
19
|
+
> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
|
|
20
|
+
|
|
21
|
+
## Workflow
|
|
22
|
+
|
|
23
|
+
### Step 1: Initial Risk Assessment
|
|
24
|
+
|
|
25
|
+
Start with a PR-level overview to identify high-risk areas.
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
mcp_milens_review_pr({repo: "<workspaceRoot>"})
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Focus on:
|
|
32
|
+
- **New files** — highest risk for secrets or vulnerabilities
|
|
33
|
+
- **Modified config files** — `.env`, `config.*`, settings files
|
|
34
|
+
- **Auth/routing files** — middleware, guards, session handlers
|
|
35
|
+
- **CRITICAL-rated symbols** — these get deep-dived in Step 6
|
|
36
|
+
|
|
37
|
+
### Step 2: Secret Detection
|
|
38
|
+
|
|
39
|
+
Search for hardcoded secrets and credentials.
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
mcp_milens_grep({pattern: "password|secret|api_key|token|private_key|AUTH_TOKEN", scope: "code", repo: "<workspaceRoot>"})
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Key patterns to flag:
|
|
46
|
+
- **Assignments to secrets** — `const apiKey = "sk-..."` (critical)
|
|
47
|
+
- **Config values** — `password: "admin123"` (high)
|
|
48
|
+
- **Variable names only** — `const apiKey = process.env.KEY` (low — already env-var'd)
|
|
49
|
+
- **Test fixtures** — `const testPassword = "..."` (verify it's not a real password)
|
|
50
|
+
|
|
51
|
+
### Step 3: Hidden Unicode Detection (Trojan Source)
|
|
52
|
+
|
|
53
|
+
Search for invisible and bidirectional Unicode characters used in supply-chain attacks.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
mcp_milens_grep({pattern: "[\\u200B\\u200C\\u200D\\u2060\\uFEFF\\u202A-\\u202E]", scope: "code", isRegex: true, repo: "<workspaceRoot>"})
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
These characters can:
|
|
60
|
+
- Make code look like one thing but compile as another
|
|
61
|
+
- Hide backdoors in copy-pasted code
|
|
62
|
+
- Exploit bidirectional text in string literals and comments
|
|
63
|
+
|
|
64
|
+
**Any match is a CRITICAL finding** — flag for immediate removal.
|
|
65
|
+
|
|
66
|
+
### Step 4: Dangerous Code Patterns
|
|
67
|
+
|
|
68
|
+
Search for patterns that enable code injection or arbitrary execution.
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
mcp_milens_grep({pattern: "eval\\(|exec\\(|child_process|Function\\(", scope: "code", isRegex: true, repo: "<workspaceRoot>"})
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Severity guidance:
|
|
75
|
+
- `eval()` / `exec()` with user input — **CRITICAL**
|
|
76
|
+
- `child_process.exec()` with dynamic arguments — **CRITICAL**
|
|
77
|
+
- `new Function()` — **HIGH** (eval equivalent)
|
|
78
|
+
- `child_process.spawn()` with fixed arguments — **LOW** (safer than exec)
|
|
79
|
+
|
|
80
|
+
### Step 5: Data Leak Detection
|
|
81
|
+
|
|
82
|
+
Find logging statements that may expose sensitive data.
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
mcp_milens_grep({pattern: "console\\.(log|debug|info)\\(", scope: "code", isRegex: true, repo: "<workspaceRoot>"})
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Flag any `console.log` that logs:
|
|
89
|
+
- User data (emails, names, PII)
|
|
90
|
+
- Tokens, passwords, keys
|
|
91
|
+
- Request bodies or headers
|
|
92
|
+
- Database query results with user data
|
|
93
|
+
|
|
94
|
+
### Step 6: Deep-Dive on Critical Symbols
|
|
95
|
+
|
|
96
|
+
For any symbol flagged as CRITICAL in Step 1, run a deep-dive.
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
mcp_milens_review_symbol({name: "<symbolName>", repo: "<workspaceRoot>"})
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
This provides:
|
|
103
|
+
- **Role** — what the symbol does (auth, routing, data access)
|
|
104
|
+
- **Heat** — how frequently it changes (volatile code = higher risk)
|
|
105
|
+
- **Dependents** — blast radius if compromised
|
|
106
|
+
- **Test status** — whether its behavior is verified
|
|
107
|
+
|
|
108
|
+
### Step 7: Verify Change Scope
|
|
109
|
+
|
|
110
|
+
Confirm that only expected files were modified.
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
mcp_milens_detect_changes({repo: "<workspaceRoot>"})
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
This catches:
|
|
117
|
+
- Unintended file modifications (config drift)
|
|
118
|
+
- Stray files included in the commit
|
|
119
|
+
- Missing or extra changes vs. expectations
|
|
120
|
+
|
|
121
|
+
### Step 8: Produce Security Audit Report
|
|
122
|
+
|
|
123
|
+
Consolidate into a structured report:
|
|
124
|
+
|
|
125
|
+
1. **Executive Summary** — overall risk level, critical findings count
|
|
126
|
+
2. **Secret Scan Results** — each match with file, line, severity, and remediation
|
|
127
|
+
3. **Unicode Scan Results** — each match (any match is critical)
|
|
128
|
+
4. **Dangerous Patterns** — each `eval`/`exec`/`Function` usage with justification
|
|
129
|
+
5. **Data Leak Findings** — each `console.log` that logs sensitive data
|
|
130
|
+
6. **Symbol Risk Deep-Dives** — per CRITICAL symbol from Step 6
|
|
131
|
+
7. **Change Scope Verification** — expected vs. actual changed files
|
|
132
|
+
8. **Remediation Plan** — ordered by severity, with specific fix recommendations
|
|
133
|
+
9. **Verdict** — PASSED / NEEDS REMEDIATION / BLOCKED
|
|
134
|
+
|
|
135
|
+
## Example Session
|
|
136
|
+
|
|
137
|
+
### Input
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
"run a security audit before the release"
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Tool Calls
|
|
144
|
+
|
|
145
|
+
**Step 1 — PR overview:**
|
|
146
|
+
```
|
|
147
|
+
mcp_milens_review_pr({repo: "/home/user/project"})
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**Output:** 8 changed files, 2 CRITICAL symbols (`authHandler`, `paymentProcessor`).
|
|
151
|
+
|
|
152
|
+
**Step 2 — Secret detection:**
|
|
153
|
+
```
|
|
154
|
+
mcp_milens_grep({pattern: "password|secret|api_key|token|private_key|AUTH_TOKEN", scope: "code", repo: "/home/user/project"})
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
**Output:**
|
|
158
|
+
```
|
|
159
|
+
src/config.ts:12 apiKey: "sk-prod-abc123..." ← CRITICAL: hardcoded API key
|
|
160
|
+
src/auth/login.ts:34 const password = req.body.pass ← LOW: variable assignment
|
|
161
|
+
src/__tests__/helpers.ts:8 const testToken = "test" ← OK: test fixture
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**Step 3 — Unicode scan:**
|
|
165
|
+
```
|
|
166
|
+
mcp_milens_grep({pattern: "[\\u200B\\u200C\\u200D\\u2060\\uFEFF\\u202A-\\u202E]", scope: "code", isRegex: true, repo: "/home/user/project"})
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Output:** 0 matches. Clean.
|
|
170
|
+
|
|
171
|
+
**Step 4 — Dangerous patterns:**
|
|
172
|
+
```
|
|
173
|
+
mcp_milens_grep({pattern: "eval\\(|exec\\(|child_process|Function\\(", scope: "code", isRegex: true, repo: "/home/user/project"})
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Output:**
|
|
177
|
+
```
|
|
178
|
+
src/scripts/migrate.ts:22 exec(`pg_dump ${dbName}`) ← CRITICAL: dynamic args
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
**Step 5 — Data leak:**
|
|
182
|
+
```
|
|
183
|
+
mcp_milens_grep({pattern: "console\\.(log|debug|info)\\(", scope: "code", isRegex: true, repo: "/home/user/project"})
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**Output:**
|
|
187
|
+
```
|
|
188
|
+
src/auth/login.ts:28 console.log("User login:", email) ← HIGH: logs PII
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**Step 6 — Deep-dive:**
|
|
192
|
+
```
|
|
193
|
+
mcp_milens_review_symbol({name: "authHandler", repo: "/home/user/project"})
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
**Output:** Core auth entry point, 23 dependents, 0 tests — very high risk.
|
|
197
|
+
|
|
198
|
+
**Step 7 — Verify scope:**
|
|
199
|
+
```
|
|
200
|
+
mcp_milens_detect_changes({repo: "/home/user/project"})
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
**Output:** 8 files changed — matches expectations.
|
|
204
|
+
|
|
205
|
+
**Step 8 — Report produced** (see report format above). Verdict: **NEEDS REMEDIATION** (1 critical secret, 1 critical dangerous pattern, 1 high data leak).
|
|
206
|
+
|
|
207
|
+
## Best Practices
|
|
208
|
+
|
|
209
|
+
1. **Don't assume variable names are safe.** `const password = process.env.DB_PASS` is fine; `const password = "admin123"` is not. Read the value, not just the name.
|
|
210
|
+
2. **Unicode scan is non-negotiable.** Trojan Source attacks are invisible to human reviewers. Even a single zero-width character match is a blocking finding.
|
|
211
|
+
3. **Test fixtures get a pass — but verify.** `const testApiKey = "test-key"` is acceptable, but `const testApiKey = "sk-live-..."` is a leaked production key.
|
|
212
|
+
4. **Dynamic exec/Function is almost always wrong.** If `exec()` takes user-controlled input, it's remote code execution. The only acceptable pattern is fully-hardcoded command strings.
|
|
213
|
+
5. **Detect changes verifies the boundary.** If `detect_changes` shows files you didn't touch, something went wrong — config drift, lockfile churn, or accidental staging.
|
|
214
|
+
|
|
215
|
+
## Quality Gate
|
|
216
|
+
|
|
217
|
+
| Criteria | Pass | Fail |
|
|
218
|
+
|---|---|---|
|
|
219
|
+
| Secret scan | No hardcoded secrets found outside test fixtures | Any production secret in code |
|
|
220
|
+
| Unicode scan | Zero matches | Any hidden unicode character found |
|
|
221
|
+
| Dangerous patterns | No `eval`/`exec` with dynamic input | Any dynamic `exec()` or `Function()` call |
|
|
222
|
+
| Data leak | No PII/credentials in `console.log` | Sensitive data logged to console |
|
|
223
|
+
| Change scope | `detect_changes` matches expectations | Unexpected files in the diff |
|
|
224
|
+
| All scans completed | All 7 steps executed | Any tool call skipped or failed |
|