@opencodehub/cli 0.2.2 → 0.2.3

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 (52) hide show
  1. package/dist/commands/ci-templates/github-nightly.yml +35 -0
  2. package/dist/commands/ci-templates/github-rescan.yml +52 -0
  3. package/dist/commands/ci-templates/github-verdict.yml +24 -0
  4. package/dist/commands/ci-templates/github-weekly.yml +49 -0
  5. package/dist/commands/ci-templates/gitlab-ci.yml +56 -0
  6. package/dist/index.js +9 -1
  7. package/dist/index.js.map +1 -1
  8. package/dist/plugin-assets/agents/code-analyst.md +18 -0
  9. package/dist/plugin-assets/commands/audit-deps.md +29 -0
  10. package/dist/plugin-assets/commands/owners.md +20 -0
  11. package/dist/plugin-assets/commands/probe.md +21 -0
  12. package/dist/plugin-assets/commands/rename.md +20 -0
  13. package/dist/plugin-assets/commands/verdict.md +18 -0
  14. package/dist/plugin-assets/hooks/augment.sh +128 -0
  15. package/dist/plugin-assets/hooks/docs-staleness.sh +45 -0
  16. package/dist/plugin-assets/hooks.json +34 -0
  17. package/dist/plugin-assets/skills/codehub-code-pack/SKILL.md +181 -0
  18. package/dist/plugin-assets/skills/codehub-code-pack/references/determinism-contract.md +150 -0
  19. package/dist/plugin-assets/skills/codehub-contract-map/SKILL.md +144 -0
  20. package/dist/plugin-assets/skills/codehub-document/SKILL.md +152 -0
  21. package/dist/plugin-assets/skills/codehub-document/references/cross-reference-spec.md +142 -0
  22. package/dist/plugin-assets/skills/codehub-document/references/data-source-map.md +139 -0
  23. package/dist/plugin-assets/skills/codehub-document/references/document-templates.md +347 -0
  24. package/dist/plugin-assets/skills/codehub-document/references/mermaid-patterns.md +181 -0
  25. package/dist/plugin-assets/skills/codehub-document/templates/agents/README.md +64 -0
  26. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-dead-code.md +104 -0
  27. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-ownership.md +101 -0
  28. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md +105 -0
  29. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-data-flow.md +103 -0
  30. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-module-map.md +102 -0
  31. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-system-overview.md +100 -0
  32. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-behavior-processes.md +103 -0
  33. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-behavior-state-machines.md +101 -0
  34. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md +104 -0
  35. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md +111 -0
  36. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md +106 -0
  37. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-components.md +99 -0
  38. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-dependency-graph.md +104 -0
  39. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-diagrams-sequences.md +103 -0
  40. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-cli.md +110 -0
  41. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md +100 -0
  42. package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-reference-public-api.md +111 -0
  43. package/dist/plugin-assets/skills/codehub-document/templates/orchestrator-prompt.md +110 -0
  44. package/dist/plugin-assets/skills/codehub-onboarding/SKILL.md +111 -0
  45. package/dist/plugin-assets/skills/codehub-pr-description/SKILL.md +122 -0
  46. package/dist/plugin-assets/skills/opencodehub-debugging/SKILL.md +144 -0
  47. package/dist/plugin-assets/skills/opencodehub-exploring/SKILL.md +120 -0
  48. package/dist/plugin-assets/skills/opencodehub-guide/SKILL.md +180 -0
  49. package/dist/plugin-assets/skills/opencodehub-impact-analysis/SKILL.md +151 -0
  50. package/dist/plugin-assets/skills/opencodehub-pr-review/SKILL.md +246 -0
  51. package/dist/plugin-assets/skills/opencodehub-refactoring/SKILL.md +180 -0
  52. package/package.json +11 -9
@@ -0,0 +1,151 @@
1
+ ---
2
+ name: opencodehub-impact-analysis
3
+ description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing or merging code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\", \"Blast radius for this change\"."
4
+ ---
5
+
6
+ # Impact Analysis with OpenCodeHub
7
+
8
+ ## When to Use
9
+
10
+ - "Is it safe to change this function?"
11
+ - "What will break if I modify X?"
12
+ - "Show me the blast radius."
13
+ - "Who uses this code?"
14
+ - Before committing or merging a non-trivial change.
15
+
16
+ ## Decision Tree
17
+
18
+ ```
19
+ Is the target a symbol (function, class, method, property)?
20
+ └─ yes → mcp__opencodehub__impact
21
+ Is the target an HTTP route or API endpoint?
22
+ └─ yes → mcp__opencodehub__api_impact + mcp__opencodehub__route_map
23
+ Is the change a response-shape edit on a route?
24
+ └─ yes → mcp__opencodehub__shape_check (find consumer key-access mismatches)
25
+ Is the target a dependency version bump?
26
+ └─ yes → mcp__opencodehub__dependencies + mcp__opencodehub__license_audit
27
+ Want to see what the working tree currently touches?
28
+ └─ yes → mcp__opencodehub__detect_changes
29
+ ```
30
+
31
+ ## Workflow
32
+
33
+ ```
34
+ 1. mcp__opencodehub__impact({ name, direction: "upstream", repo }) → Dependents of the target
35
+ 2. Read confidenceBreakdown → Trust the confirmed count
36
+ 3. If HTTP-adjacent: mcp__opencodehub__api_impact + shape_check → Route + shape mismatches
37
+ 4. mcp__opencodehub__detect_changes → Map the current diff to flows
38
+ 5. Assess risk tier and write the summary
39
+ ```
40
+
41
+ > If the context envelope warns the index is stale, run `codehub analyze` first — stale impact results are worse than no impact results.
42
+
43
+ ## Checklist
44
+
45
+ ```
46
+ - [ ] mcp__opencodehub__impact({ name, direction: "upstream", repo })
47
+ - [ ] Review byDepth.d1 first — these WILL BREAK
48
+ - [ ] Read confidenceBreakdown; demand confirmed >= heuristic for destructive calls
49
+ - [ ] Filter to confidence >= 0.9 if the target is load-bearing (auth, payments, data integrity)
50
+ - [ ] If target is a Route: mcp__opencodehub__api_impact + mcp__opencodehub__shape_check
51
+ - [ ] mcp__opencodehub__detect_changes to map the current diff to affected processes
52
+ - [ ] Produce a risk tier and a one-paragraph summary
53
+ ```
54
+
55
+ ## Understanding impact output
56
+
57
+ Risk levels map to blast-radius tiers:
58
+
59
+ | Depth | Risk Level | Meaning |
60
+ | ----- | ---------------- | -------------------------------------- |
61
+ | d=1 | WILL BREAK | Direct callers / importers / overrides |
62
+ | d=2 | LIKELY AFFECTED | One hop through d=1 |
63
+ | d=3 | MAY NEED TESTING | Two hops — transitive effects |
64
+
65
+ `confidenceBreakdown` on the impact response categorises the edges the tool actually traversed:
66
+
67
+ - `confirmed` — a SCIP indexer (scip-typescript, scip-python, scip-go, rust-analyzer, scip-java) confirmed the edge at confidence ≥ 0.95. Trust these for refactor/impact decisions.
68
+ - `heuristic` — tree-sitter or tier-1/tier-2 inference; no SCIP indexer covers this triple. Treat as a signal, not a ground truth.
69
+ - `unknown` — confidence ≤ 0.2. The demote phase flagged the edge (`+scip-unconfirmed`). Do not act on these alone.
70
+
71
+ ## Risk Tier Guide
72
+
73
+ | Signal | Risk |
74
+ | ---------------------------------------------- | -------- |
75
+ | < 5 symbols, ≤ 1 process, all confirmed | LOW |
76
+ | 5–15 symbols, 2–5 processes | MEDIUM |
77
+ | > 15 symbols OR many processes OR many heuristic edges | HIGH |
78
+ | Critical path (auth, payments, data integrity) | CRITICAL |
79
+
80
+ ## Tools
81
+
82
+ ### `mcp__opencodehub__impact` — symbol blast radius
83
+
84
+ ```
85
+ mcp__opencodehub__impact({
86
+ name: "validateUser",
87
+ direction: "upstream",
88
+ depth: 3,
89
+ repo: "my-app"
90
+ })
91
+
92
+ → target: {uid, kind, filePath}
93
+ → byDepth: {d1: [...], d2: [...], d3: [...]}
94
+ → affected_processes: [CheckoutFlow, LoginFlow]
95
+ → confidenceBreakdown: {confirmed, heuristic, unknown}
96
+ → risk: LOW | MEDIUM | HIGH | CRITICAL
97
+ ```
98
+
99
+ Disambiguation: if the name is ambiguous, `impact` returns a ranked candidate list; pass `uid` (preferred) or `{name, file_path, kind}` to pick one.
100
+
101
+ ### `mcp__opencodehub__api_impact` — route blast radius
102
+
103
+ ```
104
+ mcp__opencodehub__api_impact({ method: "POST", path: "/api/payments", repo })
105
+
106
+ → consumers: FETCHES callers across this repo (and across repos when a group is defined)
107
+ → middleware: applied handlers
108
+ → mismatches: producer/consumer shape mismatches
109
+ → affected_processes: flows that pass through this route
110
+ ```
111
+
112
+ ### `mcp__opencodehub__shape_check` — response-shape sanity
113
+
114
+ ```
115
+ mcp__opencodehub__shape_check({ repo })
116
+
117
+ → mismatches: [{route, producer_keys, consumer_access, consumer_file}]
118
+ ```
119
+
120
+ Run it when a PR changes a response payload. Any new entry in `mismatches` is a bug surface.
121
+
122
+ ### `mcp__opencodehub__detect_changes` — map the current diff to flows
123
+
124
+ ```
125
+ mcp__opencodehub__detect_changes({ scope: "staged", repo })
126
+
127
+ → changed_symbols: [{uid, name, kind, filePath, change}]
128
+ → affected_processes: [...]
129
+ → risk_level: LOW | MEDIUM | HIGH | CRITICAL
130
+ ```
131
+
132
+ Scopes: `unstaged`, `staged`, `all`, `compare` (requires `base_ref`).
133
+
134
+ ## Example: "What breaks if I change `validateUser`?"
135
+
136
+ ```
137
+ 1. mcp__opencodehub__impact({ name: "validateUser", direction: "upstream", depth: 3, repo: "my-app" })
138
+ → byDepth.d1: loginHandler, apiMiddleware (WILL BREAK)
139
+ → byDepth.d2: authRouter, sessionManager (LIKELY AFFECTED)
140
+ → affected_processes: [LoginFlow, TokenRefresh]
141
+ → confidenceBreakdown: {confirmed: 4, heuristic: 0, unknown: 0}
142
+ → risk: MEDIUM
143
+
144
+ 2. Every d=1 edge is LSP-confirmed — high trust. Two processes touch the target.
145
+
146
+ 3. mcp__opencodehub__detect_changes({ scope: "unstaged", repo: "my-app" })
147
+ → changed_symbols: [validateUser]
148
+ → affected_processes: [LoginFlow, TokenRefresh]
149
+
150
+ 4. Verdict: MEDIUM risk. LoginFlow and TokenRefresh need regression tests before merging.
151
+ ```
@@ -0,0 +1,246 @@
1
+ ---
2
+ name: opencodehub-pr-review
3
+ description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\", \"Audit the dependencies in this PR\"."
4
+ ---
5
+
6
+ # PR Review with OpenCodeHub
7
+
8
+ ## When to Use
9
+
10
+ - "Review this PR."
11
+ - "What does PR #42 change?"
12
+ - "Is this safe to merge?"
13
+ - "What's the blast radius of this PR?"
14
+ - "Are there missing tests for this PR?"
15
+ - "Did this PR introduce a copyleft / unknown license?"
16
+ - Reviewing someone else's code changes before merge.
17
+
18
+ ## The Golden Workflow
19
+
20
+ ```
21
+ 1. mcp__opencodehub__verdict({ base, head }) → 5-tier merge decision
22
+ 2. mcp__opencodehub__list_findings_delta({ base }) → New / fixed / unchanged / updated findings
23
+ 3. mcp__opencodehub__detect_changes({ scope: "compare", base_ref }) → Changed symbols + affected flows
24
+ 4. For each non-trivial changed symbol:
25
+ mcp__opencodehub__impact({ name, direction: "upstream" }) → Blast radius + confidenceBreakdown
26
+ 5. mcp__opencodehub__license_audit → Copyleft / unknown / proprietary tiers
27
+ 6. mcp__opencodehub__scan (opt-in) → Fresh scanner run — spawns processes
28
+ 7. Write the review using the output template below
29
+ ```
30
+
31
+ > If the context envelope warns the index is stale, run `codehub analyze` before starting — stale graphs produce stale verdicts.
32
+
33
+ ## Checklist
34
+
35
+ ```
36
+ - [ ] Fetch the PR diff (gh pr diff <n> or git diff <base>...<head>)
37
+ - [ ] mcp__opencodehub__verdict — start here; it aggregates the review signal
38
+ - [ ] Capture the verdict tier, top drivers, and blockers
39
+ - [ ] mcp__opencodehub__list_findings_delta — new findings since the baseline
40
+ - [ ] mcp__opencodehub__detect_changes — map the diff to affected processes
41
+ - [ ] mcp__opencodehub__impact on each non-trivial changed symbol
42
+ - [ ] Inspect confidenceBreakdown per impact — prefer confirmed edges for breakage claims
43
+ - [ ] mcp__opencodehub__license_audit — flag copyleft or unknown license changes
44
+ - [ ] (optional) mcp__opencodehub__scan to re-run scanners if the baseline is stale
45
+ - [ ] Write the review in the output template below
46
+ ```
47
+
48
+ ## Tools
49
+
50
+ ### `mcp__opencodehub__verdict` — the starting point
51
+
52
+ ```
53
+ mcp__opencodehub__verdict({ base: "main", head: "HEAD", repo: "my-app" })
54
+
55
+ → tier: "auto_merge" | "single_review" | "dual_review" | "expert_review" | "block"
56
+ → drivers: [{ signal, weight, evidence }] // top reasons the tier was chosen
57
+ → blockers: [...] // non-empty only for tier=block
58
+ → next_action: "merge" | "request review from X" | "add tests for Y" | "fix finding Z"
59
+ → exit_code: 0 | 1 | 2
60
+ ```
61
+
62
+ Always lead your review with the tier. If it is `block`, do not recommend merge. If it is `auto_merge`, the rest of the review is confirmation, not discovery.
63
+
64
+ ### `mcp__opencodehub__list_findings_delta` — what changed since baseline
65
+
66
+ ```
67
+ mcp__opencodehub__list_findings_delta({
68
+ repo: "my-app",
69
+ base: "main" // compare current scan output to the baseline frozen at base
70
+ })
71
+
72
+ → new: [{rule, severity, file, line, message}] // introduced by this PR — the scariest bucket
73
+ → fixed: [...] // removed by this PR — give credit
74
+ → unchanged: [...] // still present, not touched
75
+ → updated: [...] // same rule hit at a shifted location
76
+ ```
77
+
78
+ The `new` bucket is the first thing to surface — it is the PR author's new debt.
79
+
80
+ ### `mcp__opencodehub__detect_changes` — diff → flows
81
+
82
+ ```
83
+ mcp__opencodehub__detect_changes({ scope: "compare", base_ref: "main", repo: "my-app" })
84
+
85
+ → changed_symbols: [{uid, name, kind, filePath, change}]
86
+ → affected_processes: [CheckoutFlow, RefundFlow]
87
+ → risk_level: LOW | MEDIUM | HIGH | CRITICAL
88
+ ```
89
+
90
+ ### `mcp__opencodehub__impact` — blast radius per changed symbol
91
+
92
+ ```
93
+ mcp__opencodehub__impact({
94
+ name: "validatePayment",
95
+ direction: "upstream",
96
+ depth: 2,
97
+ repo: "my-app"
98
+ })
99
+
100
+ → byDepth.d1: processCheckout, webhookHandler // WILL BREAK if signature changed
101
+ → byDepth.d2: checkoutRouter // LIKELY AFFECTED
102
+ → affected_processes: [CheckoutFlow]
103
+ → confidenceBreakdown: {confirmed, heuristic, unknown}
104
+ → risk: MEDIUM
105
+ ```
106
+
107
+ If any d=1 caller is NOT in the PR diff, flag it as a potential breakage in your review.
108
+
109
+ ### `mcp__opencodehub__license_audit` — dependency license tiers
110
+
111
+ ```
112
+ mcp__opencodehub__license_audit({ repo: "my-app" })
113
+
114
+ → by_tier: {
115
+ copyleft: [{ name, ecosystem, version, license, manifest }],
116
+ unknown: [...],
117
+ proprietary: [...],
118
+ permissive: [...]
119
+ }
120
+ → warnings: [...] // e.g. "package `foo` has no license field in manifest"
121
+ ```
122
+
123
+ If the PR diff touches `package.json`, `pyproject.toml`, `go.mod`, or `Cargo.toml`, run this and compare tiers against the pre-PR baseline. A new `copyleft` or `unknown` entry is a review finding.
124
+
125
+ ### `mcp__opencodehub__scan` — re-run scanners
126
+
127
+ Only run this when the baseline is obviously stale. `scan` has `openWorldHint: true` and spawns child processes, so use it deliberately.
128
+
129
+ ```
130
+ mcp__opencodehub__scan({ repo: "my-app" })
131
+ ```
132
+
133
+ ### `mcp__opencodehub__risk_trends` — context on the area being changed
134
+
135
+ ```
136
+ mcp__opencodehub__risk_trends({ repo: "my-app" })
137
+
138
+ → communities: [{ name, risk_score, trend, projection_30d }]
139
+ ```
140
+
141
+ Useful when a PR lands inside a community whose risk is already trending up — call that out in the review.
142
+
143
+ ### `mcp__opencodehub__owners` — who should review?
144
+
145
+ ```
146
+ mcp__opencodehub__owners({ repo: "my-app", path: "src/payments" })
147
+
148
+ → [{ owner, source: "codeowners" | "git-blame", files, recent_edits }]
149
+ ```
150
+
151
+ ## Review Dimensions
152
+
153
+ | Dimension | OpenCodeHub surface |
154
+ | -------------------- | ------------------------------------------------------------------------- |
155
+ | **Correctness** | `context` shows callers — are they all compatible with the change? |
156
+ | **Blast radius** | `impact.byDepth` — anything at d=1 not in the diff is a potential miss |
157
+ | **Completeness** | `detect_changes.affected_processes` — are they all handled? |
158
+ | **Confidence** | `confidenceBreakdown.confirmed` vs `heuristic` — LSP-backed claims win |
159
+ | **Net new bugs** | `list_findings_delta.new` — introduced by this PR |
160
+ | **Tests** | `impact` filtered to `kind = 'Function'` inside test files |
161
+ | **License hygiene** | `license_audit` before/after diff |
162
+ | **Ownership** | `owners` — right reviewers requested? |
163
+ | **Trend** | `risk_trends` — is this area already hot? |
164
+
165
+ ## Risk Tier Guide
166
+
167
+ | Signal | Risk |
168
+ | ------------------------------------------------------- | -------- |
169
+ | < 3 symbols touched, 0–1 processes, no new findings | LOW |
170
+ | 3–10 symbols, 2–5 processes, ≤ 1 new finding | MEDIUM |
171
+ | > 10 symbols OR many processes OR several new findings | HIGH |
172
+ | Touches auth, payments, data integrity, or new copyleft | CRITICAL |
173
+ | d=1 callers exist outside the PR diff | Flag it |
174
+
175
+ ## Example: "Review PR #42"
176
+
177
+ ```
178
+ 1. gh pr diff 42 > /tmp/pr42.diff
179
+ → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
180
+
181
+ 2. mcp__opencodehub__verdict({ base: "main", head: "HEAD", repo: "my-app" })
182
+ → tier: "dual_review"
183
+ → drivers: [
184
+ {signal: "high-impact symbol changed", weight: 0.4, evidence: "validatePayment"},
185
+ {signal: "new scanner finding", weight: 0.3, evidence: "security/no-eval"},
186
+ {signal: "missing test coverage on CheckoutFlow", weight: 0.3}
187
+ ]
188
+ → next_action: "request review from @payments-team"
189
+
190
+ 3. mcp__opencodehub__list_findings_delta({ repo: "my-app", base: "main" })
191
+ → new: [{rule: "security/no-eval", severity: "error", file: "src/utils/format.ts", line: 44}]
192
+ → fixed: []
193
+
194
+ 4. mcp__opencodehub__detect_changes({ scope: "compare", base_ref: "main", repo: "my-app" })
195
+ → changed_symbols: [validatePayment, PaymentInput, formatAmount]
196
+ → affected_processes: [CheckoutFlow, RefundFlow]
197
+ → risk_level: MEDIUM
198
+
199
+ 5. mcp__opencodehub__impact({ name: "validatePayment", direction: "upstream", repo: "my-app" })
200
+ → byDepth.d1: processCheckout, webhookHandler
201
+ → webhookHandler is NOT in the PR diff — flag as potential breakage.
202
+ → confidenceBreakdown: {confirmed: 2, heuristic: 0, unknown: 0}
203
+
204
+ 6. mcp__opencodehub__impact({ name: "PaymentInput", direction: "upstream", repo: "my-app" })
205
+ → byDepth.d1: validatePayment (in PR), createPayment (NOT in PR)
206
+ → createPayment uses the old PaymentInput shape — breaking change.
207
+
208
+ 7. mcp__opencodehub__license_audit({ repo: "my-app" })
209
+ → No tier changes vs. main — clean.
210
+
211
+ 8. Compose the review (template below).
212
+ ```
213
+
214
+ ## Review Output Template
215
+
216
+ ```markdown
217
+ ## PR Review: <title>
218
+
219
+ **Tier: dual_review** **Risk: MEDIUM**
220
+
221
+ ### Verdict drivers
222
+ - validatePayment blast radius crosses the PR boundary
223
+ - 1 new scanner finding: security/no-eval at src/utils/format.ts:44
224
+ - CheckoutFlow has no test coverage for the new branch
225
+
226
+ ### Changes
227
+ - 3 symbols changed across 4 files
228
+ - 2 execution flows affected: CheckoutFlow, RefundFlow
229
+
230
+ ### Findings
231
+ 1. **[blocker]** `webhookHandler` (src/webhooks.ts:15) calls `validatePayment`
232
+ but is NOT updated in this PR. New signature will throw at runtime.
233
+ 2. **[blocker]** `createPayment` (src/payments/create.ts:22) uses the old
234
+ `PaymentInput` shape. This change is breaking.
235
+ 3. **[error]** New scanner finding: security/no-eval at src/utils/format.ts:44.
236
+ `eval(userInput)` is unsafe.
237
+ 4. **[ok]** `formatAmount` added optional param — backwards compatible.
238
+
239
+ ### Missing coverage
240
+ - CheckoutFlow has no integration test for the new branch.
241
+ - No webhook test exercises validatePayment.
242
+
243
+ ### Recommendation
244
+ REQUEST CHANGES — resolve the three blockers and add a CheckoutFlow
245
+ integration test before re-review.
246
+ ```
@@ -0,0 +1,180 @@
1
+ ---
2
+ name: opencodehub-refactoring
3
+ description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\"."
4
+ ---
5
+
6
+ # Refactoring with OpenCodeHub
7
+
8
+ ## When to Use
9
+
10
+ - "Rename this function safely."
11
+ - "Extract this into a module."
12
+ - "Split this service."
13
+ - "Move this to a new file."
14
+ - Any task involving renaming, extracting, splitting, or restructuring code.
15
+
16
+ ## Workflow
17
+
18
+ ```
19
+ 1. mcp__opencodehub__impact({ name: target, direction: "upstream" }) → All dependents
20
+ 2. mcp__opencodehub__context({ name: target }) → Incoming / outgoing / processes
21
+ 3. mcp__opencodehub__rename({ ..., dry_run: true }) → Preview every edit
22
+ 4. Review confidence tags on each edit (graph vs. text-search)
23
+ 5. mcp__opencodehub__rename({ ..., dry_run: false }) → Apply
24
+ 6. mcp__opencodehub__detect_changes → Verify the diff matches the plan
25
+ 7. Run tests for the affected processes
26
+ ```
27
+
28
+ > If the context envelope warns the index is stale, run `codehub analyze` first — a stale graph produces incomplete rename plans.
29
+
30
+ ## Checklists
31
+
32
+ ### Rename a symbol
33
+
34
+ ```
35
+ - [ ] mcp__opencodehub__impact({ name, direction: "upstream" }) — enumerate all dependents
36
+ - [ ] mcp__opencodehub__rename({ name, new_name, dry_run: true })
37
+ (pass `file_path` and/or `kind` to disambiguate when the name is ambiguous)
38
+ - [ ] Review edits: graph edges (high confidence, LSP-backed where available)
39
+ vs. text_search edits (review line-by-line — config files, docs, tests)
40
+ - [ ] Cross-check the dry-run edit count against impact's d=1 count —
41
+ gaps mean a dynamic reference the rename missed
42
+ - [ ] mcp__opencodehub__rename({ ..., dry_run: false }) — apply
43
+ - [ ] mcp__opencodehub__detect_changes({ scope: "unstaged" }) — confirm scope
44
+ - [ ] Run tests for every affected process
45
+ ```
46
+
47
+ ### Extract a module
48
+
49
+ ```
50
+ - [ ] mcp__opencodehub__context({ name: target }) — see every external ref
51
+ - [ ] mcp__opencodehub__impact({ name: target, direction: "upstream" }) — callers outside the new module
52
+ - [ ] Define the new public surface (exports only what external callers use)
53
+ - [ ] Move code; update imports
54
+ - [ ] mcp__opencodehub__detect_changes — verify scope
55
+ - [ ] Run tests for the affected processes
56
+ - [ ] Re-run codehub analyze so the next agent sees the new module boundary
57
+ ```
58
+
59
+ ### Split a function or service
60
+
61
+ ```
62
+ - [ ] mcp__opencodehub__context({ name: target }) — understand outgoing calls
63
+ - [ ] Group outgoing calls by responsibility (the seams for the split)
64
+ - [ ] mcp__opencodehub__impact({ name: target, direction: "upstream" }) — map callers to update
65
+ - [ ] Create the new functions / services
66
+ - [ ] Update callers
67
+ - [ ] mcp__opencodehub__detect_changes — verify scope
68
+ - [ ] Run tests
69
+ ```
70
+
71
+ ## Tools
72
+
73
+ ### `mcp__opencodehub__rename` — multi-file coordinated rename
74
+
75
+ ```
76
+ mcp__opencodehub__rename({
77
+ name: "validateUser",
78
+ new_name: "authenticateUser",
79
+ repo: "my-app",
80
+ dry_run: true // default: true
81
+ })
82
+
83
+ → edits: [{
84
+ file_path,
85
+ line,
86
+ old_text,
87
+ new_text,
88
+ confidence, // 0.95+ = graph-backed (ideally LSP-confirmed); lower = text_search
89
+ source // "graph" | "text_search"
90
+ }]
91
+ → summary: {total, by_source: {graph, text_search}}
92
+ ```
93
+
94
+ **Rule**: always review `text_search` edits line-by-line. They are the ones that hit dynamic references (config JSON, doc comments, test fixtures) where a rename may or may not be correct. Graph-backed edits on LSP-confirmed edges are safe to apply in bulk.
95
+
96
+ Disambiguation: when `name` matches more than one symbol, pass `file_path` and optionally `kind` to pick the target. A future wave will add `symbol_uid` for a direct UID-only path.
97
+
98
+ ### `mcp__opencodehub__impact` — enumerate dependents before renaming
99
+
100
+ ```
101
+ mcp__opencodehub__impact({
102
+ name: "validateUser",
103
+ direction: "upstream",
104
+ depth: 2,
105
+ repo: "my-app"
106
+ })
107
+
108
+ → byDepth.d1: direct callers — every one needs updating
109
+ → confidenceBreakdown: {confirmed, heuristic, unknown}
110
+ ```
111
+
112
+ If `unknown > 0`, the demote phase contradicted a heuristic edge. That edge may not be a real call — inspect before updating.
113
+
114
+ ### `mcp__opencodehub__detect_changes` — verify the post-refactor diff
115
+
116
+ ```
117
+ mcp__opencodehub__detect_changes({ scope: "unstaged", repo: "my-app" })
118
+
119
+ → changed_symbols: [...]
120
+ → affected_processes: [...]
121
+ → risk_level: LOW | MEDIUM | HIGH | CRITICAL
122
+ ```
123
+
124
+ Always run this **after** applying the rename. Any symbol you did not expect to change is a miss.
125
+
126
+ ### `mcp__opencodehub__sql` — custom reference query
127
+
128
+ All files referencing a symbol (useful when rename misses dynamic refs):
129
+
130
+ ```sql
131
+ SELECT DISTINCT caller.file_path
132
+ FROM relations r
133
+ JOIN nodes caller ON caller.id = r.from_id
134
+ JOIN nodes target ON target.id = r.to_id
135
+ WHERE r.type IN ('CALLS', 'REFERENCES', 'IMPORTS')
136
+ AND target.name = 'validateUser'
137
+ ORDER BY caller.file_path;
138
+ ```
139
+
140
+ ## Risk Rules
141
+
142
+ | Risk factor | Mitigation |
143
+ | --------------------------------- | ----------------------------------------------------------------------- |
144
+ | Many callers (> 5) | Let `rename` do the mechanical work — do not hand-edit |
145
+ | Cross-module references | Run `detect_changes` after applying; watch for missed imports |
146
+ | String / dynamic references | Use `sql` with `type = 'REFERENCES'` + text_search edits |
147
+ | Public / exported API | Version and deprecate; mirror symbol names in a transition layer |
148
+ | Heuristic edges (confirmed = 0) | Cross-check by reading source; LSP did not weigh in |
149
+
150
+ ## Example: Rename `validateUser` to `authenticateUser`
151
+
152
+ ```
153
+ 1. mcp__opencodehub__impact({ name: "validateUser", direction: "upstream", repo: "my-app" })
154
+ → d=1: loginHandler, apiMiddleware, tests/auth.test.ts
155
+ → affected_processes: [LoginFlow, TokenRefresh]
156
+ → confidenceBreakdown: {confirmed: 3, heuristic: 0, unknown: 0}
157
+
158
+ 2. mcp__opencodehub__rename({
159
+ name: "validateUser", new_name: "authenticateUser",
160
+ repo: "my-app", dry_run: true
161
+ })
162
+ → 12 edits across 8 files
163
+ → summary: {graph: 10, text_search: 2}
164
+ → text_search edits: config/routes.json (line 14), docs/auth.md (line 33)
165
+
166
+ 3. Review text_search edits: config/routes.json references validateUser by
167
+ string name — apply the rename manually, the JSON schema allows it.
168
+ docs/auth.md is prose, safe to rewrite.
169
+
170
+ 4. mcp__opencodehub__rename({ ..., dry_run: false })
171
+ → Applied 12 edits across 8 files.
172
+
173
+ 5. mcp__opencodehub__detect_changes({ scope: "unstaged", repo: "my-app" })
174
+ → changed_symbols: [authenticateUser, loginHandler, apiMiddleware, ...]
175
+ → affected_processes: [LoginFlow, TokenRefresh]
176
+ → risk_level: MEDIUM
177
+
178
+ 6. Run LoginFlow + TokenRefresh integration tests. Re-run codehub analyze
179
+ so the graph picks up the new name.
180
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opencodehub/cli",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "OpenCodeHub — codehub CLI (analyze, setup, mcp, list, status, clean, query, context, impact, sql)",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -26,7 +26,9 @@
26
26
  "dist/**/*.js.map",
27
27
  "!dist/**/*.test.js.map",
28
28
  "dist/**/*.d.ts.map",
29
- "!dist/**/*.test.d.ts.map"
29
+ "!dist/**/*.test.d.ts.map",
30
+ "dist/plugin-assets/**",
31
+ "dist/commands/ci-templates/**"
30
32
  ],
31
33
  "dependencies": {
32
34
  "@iarna/toml": "2.2.5",
@@ -37,17 +39,17 @@
37
39
  "write-file-atomic": "8.0.0",
38
40
  "yaml": "2.8.4",
39
41
  "@opencodehub/analysis": "0.1.2",
40
- "@opencodehub/ingestion": "0.3.1",
41
- "@opencodehub/embedder": "0.1.2",
42
- "@opencodehub/mcp": "0.3.0",
43
- "@opencodehub/pack": "0.1.2",
44
42
  "@opencodehub/core-types": "0.3.0",
45
- "@opencodehub/scanners": "0.1.2",
43
+ "@opencodehub/embedder": "0.1.2",
44
+ "@opencodehub/policy": "0.1.1",
45
+ "@opencodehub/pack": "0.1.3",
46
46
  "@opencodehub/sarif": "0.1.2",
47
+ "@opencodehub/mcp": "0.3.1",
48
+ "@opencodehub/scanners": "0.1.2",
47
49
  "@opencodehub/search": "0.1.2",
48
- "@opencodehub/storage": "0.1.2",
50
+ "@opencodehub/ingestion": "0.3.2",
49
51
  "@opencodehub/wiki": "0.1.1",
50
- "@opencodehub/policy": "0.1.1"
52
+ "@opencodehub/storage": "0.1.2"
51
53
  },
52
54
  "devDependencies": {
53
55
  "@types/node": "25.6.2",