@dennisrepa/elevate 1.2.0 โ 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +227 -214
- package/dist/cli.js +3148 -1277
- package/dist/cli.js.map +1 -1
- package/docs/de.md +438 -305
- package/docs/en.md +442 -309
- package/package.json +88 -73
- package/docs/plans/transactional-updates.md +0 -142
package/docs/en.md
CHANGED
|
@@ -1,309 +1,442 @@
|
|
|
1
|
-
# ๐ชถ Elevate โ English Documentation
|
|
2
|
-
|
|
3
|
-
> **Interactive Polyglot Terminal Dashboard (TUI) for safe, selective, and transparent dependency management across monorepos and multi-project repositories.**
|
|
4
|
-
> *Developed and maintained by **Dennis Rรฉpa**.*
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## ๐ Overview
|
|
9
|
-
|
|
10
|
-
**Elevate** is an interactive terminal dashboard (TUI) for safe, selective, and transparent dependency management across **polyglot monorepos** (Node/npm & Java/Maven) and single-package projects.
|
|
11
|
-
|
|
12
|
-
* **Feather Identity (`๐ชถ`) & Orange Brand (`#FF8800`):** Clean, modern, and readable in any terminal.
|
|
13
|
-
* **Polyglot Architecture:** Seamlessly manages frontend workspaces (`package.json` with npm workspaces) and backend modules (`pom.xml` with Maven).
|
|
14
|
-
* **Release Channels:** Filters out pre-releases (Alpha, Beta, RC, Milestone, Snapshot) by default, suggesting only battle-tested production releases.
|
|
15
|
-
* **Animated Companion ("Pip" ๐ฃ):** A delightful chicken mascot that reacts to actions and keeps you company in the terminal.
|
|
16
|
-
* **Bilingual i18n:** Toggle on the fly between English and German with the **`[L]`** key.
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## โจ Features & Highlights
|
|
21
|
-
|
|
22
|
-
1. **๐ Polyglot Monorepo Support (npm & Maven):**
|
|
23
|
-
* **Node / npm:**
|
|
24
|
-
* **Java / Maven:**
|
|
25
|
-
* **Runtime Switch:** Press **`[E]`** anytime to switch between frontend and backend modules.
|
|
26
|
-
|
|
27
|
-
2. **๐ Pick a Specific Version (`[V]`):**
|
|
28
|
-
* You aren't restricted to upgrading only to `latest`: pressing **`[V]`** opens an interactive modal to browse and select any published version for the focused package.
|
|
29
|
-
* Fetches the entire version history directly from the npm or Maven registry.
|
|
30
|
-
* Real-time search/filtering as you type (e.g. `3.2` or `25`), arrow key navigation, and instant selection via `Enter`.
|
|
31
|
-
* Manually chosen versions are marked with a `[MANUAL]` badge in the dashboard.
|
|
32
|
-
|
|
33
|
-
3. **๐ฆ Release Channels (`stable` vs. `all`):**
|
|
34
|
-
* **`channel: "stable"` (Default):** Prevents accidental upgrades to pre-releases (`-alpha`, `-beta`, `-rc`, `-m1`, `-snapshot`).
|
|
35
|
-
* **`channel: "all"`:** Displays all versions and highlights pre-releases with prominent magenta badges (`[BETA]`, `[RC]`, `[ALPHA]`).
|
|
36
|
-
|
|
37
|
-
4.
|
|
38
|
-
*
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
* *
|
|
46
|
-
* *
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
```bash
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
```
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
1
|
+
# ๐ชถ Elevate โ English Documentation
|
|
2
|
+
|
|
3
|
+
> **Interactive Polyglot Terminal Dashboard (TUI) for safe, selective, and transparent dependency management across monorepos and multi-project repositories.**
|
|
4
|
+
> *Developed and maintained by **Dennis Rรฉpa**.*
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## ๐ Overview
|
|
9
|
+
|
|
10
|
+
**Elevate** is an interactive terminal dashboard (TUI) for safe, selective, and transparent dependency management across **polyglot monorepos** (Node/npm & Java/Maven) and single-package projects.
|
|
11
|
+
|
|
12
|
+
* **Feather Identity (`๐ชถ`) & Orange Brand (`#FF8800`):** Clean, modern, and readable in any terminal.
|
|
13
|
+
* **Polyglot Architecture:** Seamlessly manages frontend workspaces (`package.json` with npm workspaces) and backend modules (`pom.xml` with Maven).
|
|
14
|
+
* **Release Channels:** Filters out pre-releases (Alpha, Beta, RC, Milestone, Snapshot) by default, suggesting only battle-tested production releases.
|
|
15
|
+
* **Animated Companion ("Pip" ๐ฃ):** A delightful chicken mascot that reacts to actions and keeps you company in the terminal.
|
|
16
|
+
* **Bilingual i18n:** Toggle on the fly between English and German with the **`[L]`** key.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## โจ Features & Highlights
|
|
21
|
+
|
|
22
|
+
1. **๐ Polyglot Monorepo Support (npm, pnpm & Maven):**
|
|
23
|
+
* **Node / npm:** Resolves workspaces exactly like npm (glob patterns such as `packages/**` included), calculates SemVer diffs, updates `package.json` (`dependencies`, `devDependencies`, `optionalDependencies`), runs `npm install` and checks the lockfile. **Node / pnpm** (9 โ 12) works the same way for pnpm repositories: workspaces from `pnpm-workspace.yaml`, the `workspace:` protocol, `catalog:` entries, `pnpm install` and a lockfile check. Repositories managed by Yarn or Bun are refused.
|
|
24
|
+
* **Java / Maven:** Finds every `pom.xml` (including the root POM), lets Maven compute the effective POM, looks up newer versions through the build's own repositories (mirrors, Nexus/Artifactory, credentials from `settings.xml`) and verifies the affected modules with `mvn test-compile`.
|
|
25
|
+
* **Runtime Switch:** Press **`[E]`** anytime to switch between frontend and backend modules.
|
|
26
|
+
|
|
27
|
+
2. **๐ Pick a Specific Version (`[V]`):**
|
|
28
|
+
* You aren't restricted to upgrading only to `latest`: pressing **`[V]`** opens an interactive modal to browse and select any published version for the focused package.
|
|
29
|
+
* Fetches the entire version history directly from the npm or Maven registry.
|
|
30
|
+
* Real-time search/filtering as you type (e.g. `3.2` or `25`), arrow key navigation, and instant selection via `Enter`.
|
|
31
|
+
* Manually chosen versions are marked with a `[MANUAL]` badge in the dashboard.
|
|
32
|
+
|
|
33
|
+
3. **๐ฆ Release Channels (`stable` vs. `all`):**
|
|
34
|
+
* **`channel: "stable"` (Default):** Prevents accidental upgrades to pre-releases (`-alpha`, `-beta`, `-rc`, `-m1`, `-snapshot`).
|
|
35
|
+
* **`channel: "all"`:** Displays all versions and highlights pre-releases with prominent magenta badges (`[BETA]`, `[RC]`, `[ALPHA]`).
|
|
36
|
+
|
|
37
|
+
4. **๐ข Internal Dependencies (Workspace Modules & Private Registries):**
|
|
38
|
+
* Workspace modules that depend on each other are kept in line with their local versions (`[Align]`).
|
|
39
|
+
* Internal packages (`internalScopes`, e.g. `@my-org/*`, `com.mycompany.*`) are looked up only in private registries โ never on a public one.
|
|
40
|
+
* See [Internal Dependencies & Safety](#-internal-dependencies--safety) below.
|
|
41
|
+
|
|
42
|
+
5. **๐ฃ Animated Mascot ("Pip"):**
|
|
43
|
+
* Positioned neatly in the bottom right corner of the dashboard.
|
|
44
|
+
* State-reactive behavior:
|
|
45
|
+
* *Idle:* Blinks gently or sips coffee in Java mode (`*sipping coffee* โ`).
|
|
46
|
+
* *Scanning:* Inspects dependencies with a magnifying glass (`( หำฉห )๐`).
|
|
47
|
+
* *Building:* Rolls up its sleeves (`(เธ โขำฉโข )เธ`).
|
|
48
|
+
* *Success:* Celebrates with confetti (`\( แตำฉแต )/ ๐`).
|
|
49
|
+
|
|
50
|
+
6. **๐ Initial Splash Screen:**
|
|
51
|
+
* A stylish intro screen with an animated progress bar (~3.2 seconds).
|
|
52
|
+
* Can be skipped immediately at any time by pressing `[Space]` or `[Enter]`.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## ๐ข Internal Dependencies & Safety
|
|
57
|
+
|
|
58
|
+
Every dependency is classified by **origin** before any registry is contacted:
|
|
59
|
+
|
|
60
|
+
| Origin | Recognised by | Version source | Action |
|
|
61
|
+
| :--- | :--- | :--- | :--- |
|
|
62
|
+
| `workspace` | A module discovered in this repository | The module's **local** version | `align` |
|
|
63
|
+
| `private` | `internalScopes`, or an explicit `@scope:registry` mapping in `.npmrc` | The private registry configured for it | `update` |
|
|
64
|
+
| `public` | Everything else | The configured registry | `update` |
|
|
65
|
+
|
|
66
|
+
The registry URL alone is deliberately **not** used to decide the origin: in most companies every request โ public packages included โ goes through one Artifactory or Nexus proxy.
|
|
67
|
+
|
|
68
|
+
### Aligning workspace modules
|
|
69
|
+
|
|
70
|
+
* **npm:** If a dependency's range does not include the local version of a workspace package, npm does **not** link the workspace โ it installs a package with the same name from the registry. Elevate offers to align the range (e.g. `^1.0.0` โ `^2.0.0`). After `npm install` it checks `package-lock.json`: every aligned dependency must be `"link": true`, otherwise the update is rolled back. Ranges that npm always links (`*`, `file:`, `workspace:`) are left alone.
|
|
71
|
+
* **pnpm:** pnpm links a workspace package only when the dependency is written with the `workspace:` protocol; a plain range such as `^1.0.0` is resolved from the registry, even if the local version satisfies it. Elevate therefore aligns `workspace:^1.2.0` โ `workspace:^2.0.0` (the protocol and the prefix are kept; `workspace:*`, `workspace:^`, `workspace:~` and `workspace:../lib` need nothing) and lists a plain range on a module as *not linked* without ever looking the name up in a registry or rewriting it. After `pnpm install` it reads the `importers` section of `pnpm-lock.yaml` (`lockfileVersion` 9.x): every aligned dependency must have a `version` starting with `link:`, otherwise the update is rolled back.
|
|
72
|
+
* **Maven:** If a module depends on a module of the *same reactor* with a different version (e.g. `1.0.0` while the module is at `1.1.0-SNAPSHOT`), Elevate offers to align it. `${project.version}` references need no alignment.
|
|
73
|
+
* The release channel does not apply to alignment: the local version โ including `-SNAPSHOT` โ is the target, because modules of one repository are built and tested together.
|
|
74
|
+
|
|
75
|
+
### Private registries & dependency confusion
|
|
76
|
+
|
|
77
|
+
* Internal packages are never looked up on a public registry. If the registry for an internal npm package resolves to `registry.npmjs.org`, it is listed as *not offered* with the reason, instead of being queried โ asking a public registry about an internal name is exactly what a dependency-confusion attack exploits.
|
|
78
|
+
* npm lookups use your npm configuration (`npm config`), Maven lookups use Maven itself โ mirrors, private repositories and credentials apply without any Elevate-specific configuration, and Elevate never handles credentials.
|
|
79
|
+
|
|
80
|
+
### Where Maven versions are written
|
|
81
|
+
|
|
82
|
+
Maven's effective POM tells which version applies, not where it is written. Elevate locates the declaring literal โ a dependency `<version>`, a `<dependencyManagement>` entry, a property (possibly in a parent POM) or an external `<parent>` โ and edits exactly that text, preserving formatting and comments. Before editing, the literal is cross-checked against the effective version; if they differ (active profiles, command-line properties) or the version comes from an external parent/BOM, the dependency is listed as *not offered* with the reason. Artifacts sharing one version property are marked, and conflicting targets for a shared property are rejected.
|
|
83
|
+
|
|
84
|
+
### Rollback
|
|
85
|
+
|
|
86
|
+
Every update runs as one workflow: **snapshot โ write & install โ integrity check โ verification**. If installation, the integrity check or verification fails, every touched file (manifests, lockfile, parent POMs) is restored and `node_modules` is reinstalled. `--keep-on-failure` (CLI) or `keepOnFailure` (MCP) keeps the changes of a failed *verification* for investigation. Verification also runs once *before* the update: if it already fails there, a failure afterwards is reported as pre-existing and the update is kept instead of rolled back. A crashing verifier counts as a failed verification.
|
|
87
|
+
|
|
88
|
+
### Verification
|
|
89
|
+
|
|
90
|
+
* **npm:** `npm ls` at the repository root (missing, invalid or unmet dependencies across all workspaces), unless `postUpdateScript` is set.
|
|
91
|
+
* **Maven:** `mvn test-compile -pl <changed modules> -amd` in the reactor โ the changed modules *and every module depending on them*. A change to the aggregator POM rebuilds the whole reactor.
|
|
92
|
+
|
|
93
|
+
### Requirements for Maven
|
|
94
|
+
|
|
95
|
+
Elevate uses the project's Maven Wrapper (`mvnw` / `mvnw.cmd`) when present, otherwise `mvn` on the `PATH`. Without either, Maven scans fail with a clear message instead of guessing. Plugin versions are pinned for reproducible results (`maven-help-plugin` 3.5.2, `versions-maven-plugin` 2.22.0) and can be replaced per repository with `mavenPlugins` in `elevate.config.json` (see [Maven plugin versions](#maven-plugin-versions)). Scans write temporary files only to `target/.elevate-*` and remove them afterwards.
|
|
96
|
+
|
|
97
|
+
### Repository root
|
|
98
|
+
|
|
99
|
+
Elevate works the same wherever in the repository it is started. The root is found as follows:
|
|
100
|
+
|
|
101
|
+
1. The nearest directory (from the start directory upwards) with an `elevate.config.json` is the root.
|
|
102
|
+
2. Otherwise npm proposes the nearest directory whose `package.json` declares `workspaces`, and Maven proposes the top of the connected POM chain (a `<parent>` found through `<relativePath>` and any aggregator that lists the project in `<modules>`). The outermost proposal wins.
|
|
103
|
+
3. Without any marker the start directory is the root.
|
|
104
|
+
|
|
105
|
+
The search never leaves the version-control checkout: it stops at the nearest directory that contains a `.git` entry, so a stray `package.json` or `pom.xml` somewhere above the repository is never mistaken for its root. Manifests that cannot be parsed are skipped.
|
|
106
|
+
|
|
107
|
+
### Package manager guard (Yarn and Bun)
|
|
108
|
+
|
|
109
|
+
Elevate's Node.js support drives npm and pnpm. In a repository managed by Yarn or Bun it refuses to scan or change the modules, because either tool would create a second lockfile and a `node_modules` layout the project does not use. The package manager is recognised from the repository root, in this order: the `packageManager` field of `package.json` (`npm@`, `pnpm@`, `yarn@`, `bun@`), then `package-lock.json` / `npm-shrinkwrap.json`, `pnpm-lock.yaml` / `pnpm-workspace.yaml`, `yarn.lock` / `.yarnrc.yml`, `bun.lock` / `bun.lockb`; without any of them the repository is treated as npm. If Elevate is started inside a workspace package, the search continues in the parent directories up to the checkout (the nearest directory with a `.git` entry); without a checkout only the directory itself is examined. The refusal names the manager and the file that decided. Maven modules in the same repository, read-only version queries (`elevate versions`) and a custom `postUpdateScript` are not affected.
|
|
110
|
+
|
|
111
|
+
### pnpm workspaces and catalogs
|
|
112
|
+
|
|
113
|
+
* **Workspace file.** In a pnpm repository the `packages` list of `pnpm-workspace.yaml` (not the `workspaces` field of `package.json`) defines the modules; `*`, `**` and `!` patterns work as for npm, the root is always a module and `node_modules` never contains modules. A `pnpm-workspace.yaml` also marks the repository root, even without a `packages` list. A file that is not valid YAML counts as absent.
|
|
114
|
+
* **Catalogs.** A `catalog:` / `catalog:default` / `catalog:<name>` dependency is offered with the range from the catalog and the new range is written to that entry of `pnpm-workspace.yaml` (comments, quotes, notation and line endings stay; the module's `package.json` is not rewritten). A reference that cannot be resolved is listed as `catalog-unresolved`. The JSON output says where the version is declared: `"declaredIn": {"file": "pnpm-workspace.yaml", "kind": "catalog", "catalog": "default"}`.
|
|
115
|
+
* **Overrides** (`pnpm.overrides`, `overrides` in `pnpm-workspace.yaml`, `resolutions`) and `peerDependencies` are never changed.
|
|
116
|
+
|
|
117
|
+
### Commands Elevate runs for pnpm
|
|
118
|
+
|
|
119
|
+
All in the repository root; Elevate uses the `pnpm` on the `PATH` (the `packageManager` field and Corepack decide the version). `pnpm --version` runs first and, if it fails, the operation stops with an explanation before anything is touched.
|
|
120
|
+
|
|
121
|
+
| Purpose | Command | Timeout |
|
|
122
|
+
| :--- | :--- | :--- |
|
|
123
|
+
| Is pnpm usable? | `pnpm --version` | 15 s |
|
|
124
|
+
| Install after writing the ranges | `pnpm install --no-frozen-lockfile` | 10 min |
|
|
125
|
+
| Restore after a rollback | `pnpm install --frozen-lockfile` | 10 min |
|
|
126
|
+
| Default verification (lockfile consistency, replaces `npm ls`) | `pnpm install --frozen-lockfile --lockfile-only` | 10 min |
|
|
127
|
+
| Vulnerability summary | `pnpm audit --json` | 60 s |
|
|
128
|
+
| Versions of a package | `pnpm view <name> <field> --json` | 15 s |
|
|
129
|
+
| Registry configuration | `pnpm config list --json` | 15 s |
|
|
130
|
+
|
|
131
|
+
`--no-frozen-lockfile` is passed explicitly because with `CI` set `pnpm install` is implicitly frozen and would fail on the manifest Elevate just changed. `pnpm ls` is not used for verification: it exits with 0 for missing dependencies. The vulnerability summary comes from `pnpm audit --json` (`pnpm install` prints none); an audit without a result is a warning, never a reason to roll back. Elevate does not read pnpm settings such as `minimumReleaseAge` or build-script approval; if pnpm refuses because of them, the update is rolled back with pnpm's own message.
|
|
132
|
+
|
|
133
|
+
### Dependency sections (npm)
|
|
134
|
+
|
|
135
|
+
| Section | Scanned | Written |
|
|
136
|
+
| :--- | :---: | :---: |
|
|
137
|
+
| `dependencies`, `devDependencies`, `optionalDependencies` | yes | yes |
|
|
138
|
+
| `peerDependencies`, `overrides`, `bundleDependencies` | no | never |
|
|
139
|
+
|
|
140
|
+
A peer range tells consumers which versions a package works with; raising it because a newer version exists would be a breaking change nobody decided. A name declared in several scanned sections receives the new range in every one of them; for display, `optionalDependencies` take precedence over `dependencies` (as in npm), and a name that is also a development dependency is shown as one.
|
|
141
|
+
|
|
142
|
+
### Reactor-scoped alignment (Maven)
|
|
143
|
+
|
|
144
|
+
A dependency on another module is aligned to that module's local version only when both modules are built by the same outermost aggregator (the same reactor). Outside a reactor Maven resolves the dependency from a repository like any other artifact, even if a project with the same coordinates lies somewhere in the checkout (a sample, a fixture, an old copy), so such a dependency is looked up and offered as an ordinary update โ `private` when it matches `internalScopes`, otherwise `public`. POM files below a project's `src` directory (test fixtures, `maven-invoker-plugin` projects, archetype templates) and below `node_modules`, `target`, `build`, `dist`, `out` or hidden directories are not modules, unless a `<modules>` section names them.
|
|
145
|
+
|
|
146
|
+
### Maven plugin versions
|
|
147
|
+
|
|
148
|
+
Elevate runs two Maven plugins: `maven-help-plugin` (reads the effective POM, default `3.5.2`) and `versions-maven-plugin` (looks up newer versions, default `2.22.0`). If your repository manager does not offer these versions, set others with `mavenPlugins` in `elevate.config.json`. A value must start with a digit and contain only letters, digits, `.` and `-` (at most 64 characters); anything else is replaced by the default and reported as a warning. When Maven cannot download a plugin, Elevate says so, names the plugin and the setting that replaces its version, and appends Maven's own error lines.
|
|
149
|
+
|
|
150
|
+
### Windows paths
|
|
151
|
+
|
|
152
|
+
On Windows `npm`, `mvn` and the Maven Wrapper are batch files that run through `cmd.exe`, which interprets `" % ! ^ & | < >` even inside quotes; Elevate refuses to put an argument containing one of them on a command line. The directory the repository lives in is handed to the process as its working directory and project files are named relative to it, so a path such as `C:\R&D\shop` works. Names *inside* the repository that end up on a command line (for example a module directory passed to `-pl`) must still avoid these characters; the error message names the argument and how to fix it.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## ๐๏ธ Domain-Driven Clean Architecture
|
|
157
|
+
|
|
158
|
+
Elevate follows **Domain-Driven Design (DDD)** and **Hexagonal Architecture (Ports & Adapters)**. The UI and hooks never depend directly on a package manager:
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
src/
|
|
162
|
+
โโโ domain/ # ๐ง DOMAIN CORE (Pure domain logic, zero I/O)
|
|
163
|
+
โ โโโ models.ts # Entities & Value Objects (ProjectModule, UpdateCandidate, DependencyOrigin, โฆ)
|
|
164
|
+
โ โโโ origin.ts # Origin classification (workspace / private / public)
|
|
165
|
+
โ โโโ versions.ts # Pre-release detection & version helpers
|
|
166
|
+
โ โโโ ports.ts # Domain Ports (ModuleDiscoveryPort, RegistryPort, etc.)
|
|
167
|
+
โ โโโ ecosystem-strategy.ts # Strategy Pattern: Platform-agnostic interface
|
|
168
|
+
โ โโโ ecosystem-factory.ts # Factory Pattern: Resolves npm or Maven strategy
|
|
169
|
+
โ
|
|
170
|
+
โโโ adapters/ # ๐ ADAPTERS (Concrete port implementations)
|
|
171
|
+
โ โโโ shared/ # ๐งฐ XML (position-aware), processes, snapshots, pooling
|
|
172
|
+
โ โ
|
|
173
|
+
โ โโโ npm/ # ๐ฆ Node / npm Adapters
|
|
174
|
+
โ โ โโโ npm-config.ts # Effective npm config (registries per scope)
|
|
175
|
+
โ โ โโโ npm-discovery.ts # Workspaces via @npmcli/map-workspaces
|
|
176
|
+
โ โ โโโ npm-registry.ts # npm view queries & dist-tags
|
|
177
|
+
โ โ โโโ npm-scanner.ts # Origins, alignment, SemVer diffs
|
|
178
|
+
โ โ โโโ npm-lockfile.ts # Workspace link check in package-lock.json
|
|
179
|
+
โ โ โโโ npm-package-manager.ts # Package manager detection, guard & pnpm check
|
|
180
|
+
โ โ โโโ npm-commands.ts # Commands per package manager (npm / pnpm)
|
|
181
|
+
โ โ โโโ npm-protocols.ts # workspace: / catalog: range protocols
|
|
182
|
+
โ โ โโโ pnpm-workspace.ts # pnpm-workspace.yaml: packages, catalogs, in-place edit
|
|
183
|
+
โ โ โโโ pnpm-lockfile.ts # Workspace link check in pnpm-lock.yaml
|
|
184
|
+
โ โ โโโ pnpm-audit.ts # pnpm audit --json summary
|
|
185
|
+
โ โ โโโ npm-updater.ts # Updates package.json & runs npm install
|
|
186
|
+
โ โ โโโ npm-verifier.ts # npm ls / custom verification
|
|
187
|
+
โ โ โโโ npm-strategy.ts # NpmEcosystemStrategy
|
|
188
|
+
โ โ
|
|
189
|
+
โ โโโ maven/ # โ Java / Maven Adapters
|
|
190
|
+
โ โโโ maven-command.ts # Maven Wrapper / mvn invocation
|
|
191
|
+
โ โโโ maven-pom.ts # Raw POM model with editable element ranges
|
|
192
|
+
โ โโโ maven-project.ts # All POMs of the repo, parent chains, reactors
|
|
193
|
+
โ โโโ maven-discovery.ts # Modules incl. root POM, versions, aggregator
|
|
194
|
+
โ โโโ maven-resolution.ts # Effective POM & versions-maven-plugin report
|
|
195
|
+
โ โโโ maven-locator.ts # Finds where a version is declared
|
|
196
|
+
โ โโโ maven-scanner.ts # Origins, alignment, update candidates
|
|
197
|
+
โ โโโ maven-registry.ts # `elevate versions` via Maven (any Nexus/Artifactory)
|
|
198
|
+
โ โโโ maven-updater.ts # Formatting-preserving POM edits
|
|
199
|
+
โ โโโ maven-verifier.ts # mvn test-compile -pl โฆ -amd
|
|
200
|
+
โ โโโ maven-strategy.ts # MavenEcosystemStrategy
|
|
201
|
+
โ
|
|
202
|
+
โโโ application/ # ๐งญ USE CASES shared by TUI, CLI and MCP
|
|
203
|
+
โ โโโ scan.ts # Scan context, module lookup, JSON output
|
|
204
|
+
โ โโโ update-selection.ts # Guardrails for requested updates
|
|
205
|
+
โ โโโ update-workflow.ts # Snapshot โ install โ integrity โ verify โ rollback
|
|
206
|
+
โ โโโ version-lookup.ts # Version history without public lookups of internal names
|
|
207
|
+
โ
|
|
208
|
+
โโโ hooks/ # ๐ฃ APPLICATION HOOKS (Consume only domain ports)
|
|
209
|
+
โ โโโ use-workspaces.ts # Module management via ModuleDiscoveryPort
|
|
210
|
+
โ โโโ use-packages.ts # Scanning & filtering via DependencyReaderPort
|
|
211
|
+
โ โโโ use-updater.ts # Runs the shared update workflow
|
|
212
|
+
โ
|
|
213
|
+
โโโ components/ # ๐จ PRESENTATIONAL UI (Pure rendering with Ink)
|
|
214
|
+
โ โโโ header.tsx # Ecosystem [E], Channel [stable], Language [L], Author
|
|
215
|
+
โ โโโ workspace-bar.tsx # Active module with static protection notice
|
|
216
|
+
โ โโโ mascot.tsx # ๐ฃ Animated companion ("Pip")
|
|
217
|
+
โ โโโ status-bar.tsx # Rock-solid status bar with counts & mascot
|
|
218
|
+
โ โโโ tab-bar.tsx # Ecosystem-specific tabs
|
|
219
|
+
โ โโโ package-list.tsx # Scrollable list with orange accents
|
|
220
|
+
โ โโโ package-row.tsx # Row with badges ([Patch], [Minor], [MAJOR], [BETA])
|
|
221
|
+
โ โโโ controls-bar.tsx # Keyboard shortcuts
|
|
222
|
+
โ โโโ workspace-modal.tsx # Modal selector for modules
|
|
223
|
+
โ โโโ version-modal.tsx # ๐ Modal version search & picker
|
|
224
|
+
โ โโโ splash-screen.tsx # Initial startup screen
|
|
225
|
+
โ โโโ updating-view.tsx # Update progress display
|
|
226
|
+
โ โโโ summary-view.tsx # Final report summary
|
|
227
|
+
โ
|
|
228
|
+
โโโ cli/ # ๐ป HEADLESS CLI SUBCOMMANDS (for CI/CD & Shell-Agents)
|
|
229
|
+
โ โโโ parser.ts # Zero-dependency CLI argument parser
|
|
230
|
+
โ โโโ command-modules.ts # `elevate modules`
|
|
231
|
+
โ โโโ command-scan.ts # `elevate scan`
|
|
232
|
+
โ โโโ command-versions.ts # `elevate versions`
|
|
233
|
+
โ โโโ command-update.ts # `elevate update`
|
|
234
|
+
โ
|
|
235
|
+
โโโ mcp/ # ๐ค MODEL CONTEXT PROTOCOL (MCP Server)
|
|
236
|
+
โ โโโ mcp-server.ts # Standard stdio MCP server exposing 5 tools
|
|
237
|
+
โ
|
|
238
|
+
โโโ i18n/ # ๐ Localization dictionaries (de.ts / en.ts)
|
|
239
|
+
โโโ config.ts # โ๏ธ Configuration loader
|
|
240
|
+
โโโ theme.ts # ๐จ Color tokens & icons
|
|
241
|
+
โโโ app.tsx # ๐ฑ App Shell (Container)
|
|
242
|
+
โโโ index.tsx # ๐ Universal entry point (TUI / CLI / MCP)
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## ๐ค Agentic & CI/CD Support (Headless CLI & MCP)
|
|
248
|
+
|
|
249
|
+
Elevate is built from the ground up for agentic execution by AI coding assistants (Claude Code, Antigravity, Cursor, Copilot CLI) and automated CI/CD runners.
|
|
250
|
+
|
|
251
|
+
### 1. Headless CLI Subcommands (`--json`)
|
|
252
|
+
|
|
253
|
+
Any command line agent or pipeline can run Elevate without starting the interactive TUI:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
# Discover modules in monorepo
|
|
257
|
+
node tools/updater/elevate/index.mjs modules --json
|
|
258
|
+
|
|
259
|
+
# Scan dependencies across all modules
|
|
260
|
+
# (exit code 0 = up to date, 1 = updates available, 3 = a module could not be scanned)
|
|
261
|
+
node tools/updater/elevate/index.mjs scan --channel=stable --all-modules --json
|
|
262
|
+
|
|
263
|
+
# Query complete version history for a package
|
|
264
|
+
node tools/updater/elevate/index.mjs versions chalk --json
|
|
265
|
+
|
|
266
|
+
# Apply updates with safety guardrails (simulation via --dry-run)
|
|
267
|
+
node tools/updater/elevate/index.mjs update --module=apps/e2e-cockpit --packages=chalk@5.6.2 --dry-run --json
|
|
268
|
+
|
|
269
|
+
# Apply major updates (explicit permission required)
|
|
270
|
+
node tools/updater/elevate/index.mjs update --module=apps/e2e-cockpit --packages=pinia@4.0.3 --allow-major --json
|
|
271
|
+
|
|
272
|
+
# Keep the changes if verification fails (default: roll back)
|
|
273
|
+
node tools/updater/elevate/index.mjs update --module=apps/web --all --keep-on-failure
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
`scan --json` lists, per module, the `updates` (with `action`, `origin` and โ for Maven โ `declaredIn`) and the `skipped` dependencies with their `reason`. `update` exits with `2` when the update failed and was rolled back.
|
|
277
|
+
|
|
278
|
+
### 2. Model Context Protocol (MCP) Server
|
|
279
|
+
|
|
280
|
+
Elevate provides a native, stdio-based MCP Server:
|
|
281
|
+
```bash
|
|
282
|
+
node tools/updater/elevate/index.mjs mcp
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Register it in your agent's MCP settings (e.g., `claude_desktop_config.json` or Antigravity MCP config):
|
|
286
|
+
```json
|
|
287
|
+
{
|
|
288
|
+
"mcpServers": {
|
|
289
|
+
"elevate": {
|
|
290
|
+
"command": "npx",
|
|
291
|
+
"args": ["-y", "@dennisrepa/elevate", "mcp"]
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
#### Available MCP Tools for LLMs:
|
|
298
|
+
| Tool | Purpose |
|
|
299
|
+
| :--- | :--- |
|
|
300
|
+
| `elevate_discover_modules` | Discovers all repository modules and workspaces for npm or Maven |
|
|
301
|
+
| `elevate_scan` | Scans a module (or all modules) for updates and internal dependencies to align; lists skipped dependencies with reasons |
|
|
302
|
+
| `elevate_get_versions` | Fetches complete published version history from registry (refuses public lookups of internal packages) |
|
|
303
|
+
| `elevate_apply_updates` | Applies targeted updates with verification, major guardrails and rollback (`keepOnFailure` optional) |
|
|
304
|
+
| `elevate_verify` | Runs module-specific build and test verification checks |
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## โจ๏ธ Keyboard Shortcuts (Interactive TUI)
|
|
309
|
+
|
|
310
|
+
| Key | Action |
|
|
311
|
+
| :--- | :--- |
|
|
312
|
+
| **`E`** | **Switch Ecosystem (๐ฆ Node/npm โ โ Java/Maven)** |
|
|
313
|
+
| **`W`** | Open module / workspace selector |
|
|
314
|
+
| **`V`** | **Pick specific version (Interactive search & filter modal)** |
|
|
315
|
+
| **`L`** | Toggle language (English โ German) |
|
|
316
|
+
| **`โ` / `โ`** *(or `k`/`j`)* | Navigate list items |
|
|
317
|
+
| **`Space`** | Toggle selection of focused item |
|
|
318
|
+
| **`A`** | Toggle all visible items in the active tab |
|
|
319
|
+
| **`Tab`** *(or `1`, `2`, `3`)* | Switch between tabs |
|
|
320
|
+
| **`U`** | Start update for all selected items |
|
|
321
|
+
| **`R`** | Re-scan the active module |
|
|
322
|
+
| **`Q`** | Quit Elevate |
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
## โ๏ธ Configuration (`elevate.config.json`)
|
|
327
|
+
|
|
328
|
+
You can place an optional `elevate.config.json` file in your repository root:
|
|
329
|
+
|
|
330
|
+
```json
|
|
331
|
+
{
|
|
332
|
+
"author": "Dennis Rรฉpa",
|
|
333
|
+
"channel": "stable",
|
|
334
|
+
"locale": "en",
|
|
335
|
+
"internalScopes": ["@my-org", "com.mycompany"],
|
|
336
|
+
"mavenPlugins": { "help": "3.5.2", "versions": "2.22.0" },
|
|
337
|
+
"postUpdateScript": "npm test",
|
|
338
|
+
"postUpdateLabel": "Run test suite"
|
|
339
|
+
}
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
* **`author`:** Optional name displayed in the top-right header.
|
|
343
|
+
* **`channel`:** `"stable"` (default, excludes betas/RCs) or `"all"` (includes pre-releases).
|
|
344
|
+
* **`locale`:** `"en"` (English), `"de"` (German), or `"auto"` (system detection).
|
|
345
|
+
* **`internalScopes`:** Internal npm scopes and Maven groupId prefixes. `@my-org` matches `@my-org/*`; `com.mycompany` matches `com.mycompany` and `com.mycompany.*` (not `com.mycompanyx`). Matching packages are looked up only in private registries. *Formerly `excludeScopes`, which is still read and reported as deprecated.*
|
|
346
|
+
* **`mavenPlugins`:** Optional versions of the Maven plugins Elevate runs: `help` (`maven-help-plugin`, default `3.5.2`) and `versions` (`versions-maven-plugin`, default `2.22.0`). Use it when your repository manager does not offer the defaults. Invalid values fall back to the default with a warning.
|
|
347
|
+
* **`postUpdateScript`:** Optional command that replaces the default verification (`npm ls` / `mvn test-compile`). Runs in the repository root (npm) or the module directory (Maven).
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## ๐ฆ Installation & Setup
|
|
352
|
+
|
|
353
|
+
Elevate offers multiple flexible options for any developer workflow or environment:
|
|
354
|
+
|
|
355
|
+
### 1. โก Zero-Install Instant Run via `npx` (Recommended)
|
|
356
|
+
Run Elevate immediately without cloning or installing anything:
|
|
357
|
+
```bash
|
|
358
|
+
npx @dennisrepa/elevate
|
|
359
|
+
```
|
|
360
|
+
> **For Autonomous AI Agents (Claude Code, Cursor, Antigravity):**
|
|
361
|
+
> Register Elevate directly in your agent's MCP settings:
|
|
362
|
+
> ```json
|
|
363
|
+
> {
|
|
364
|
+
> "mcpServers": {
|
|
365
|
+
> "elevate": {
|
|
366
|
+
> "command": "npx",
|
|
367
|
+
> "args": ["-y", "@dennisrepa/elevate", "mcp"]
|
|
368
|
+
> }
|
|
369
|
+
> }
|
|
370
|
+
> }
|
|
371
|
+
> ```
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
### 2. ๐ช Standalone Executable (Zero Node.js Required)
|
|
376
|
+
For Java/Backend developers, system administrators, or CI environments without Node.js:
|
|
377
|
+
1. Download `elevate.exe` (Windows) or `elevate-linux` from the **[GitHub Releases](https://github.com/dennisrepa/elevate/releases)**.
|
|
378
|
+
2. Run directly in your terminal:
|
|
379
|
+
```powershell
|
|
380
|
+
.\elevate.exe
|
|
381
|
+
```
|
|
382
|
+
*(Or double-click `elevate.exe` in Windows Explorer).*
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
### 3. ๐ Global System Installation
|
|
387
|
+
Install Elevate globally to have the `elevate` command available in every terminal:
|
|
388
|
+
```bash
|
|
389
|
+
npm install -g @dennisrepa/elevate
|
|
390
|
+
```
|
|
391
|
+
Then launch anywhere:
|
|
392
|
+
```bash
|
|
393
|
+
elevate
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
---
|
|
397
|
+
|
|
398
|
+
### 4. ๐ข Monorepo & Project Integration
|
|
399
|
+
Add Elevate as a devDependency to your project or monorepo:
|
|
400
|
+
```bash
|
|
401
|
+
npm install -D @dennisrepa/elevate
|
|
402
|
+
```
|
|
403
|
+
Add an `elevate` script to your root `package.json`:
|
|
404
|
+
```json
|
|
405
|
+
{
|
|
406
|
+
"scripts": {
|
|
407
|
+
"elevate": "elevate"
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
```
|
|
411
|
+
Now every team member can launch the dashboard using:
|
|
412
|
+
```bash
|
|
413
|
+
npm run elevate
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
### 5. ๐ ๏ธ Local Development & Contributing (Inside this Repo)
|
|
419
|
+
If you are developing or customizing Elevate locally:
|
|
420
|
+
```bash
|
|
421
|
+
cd tools/updater/elevate
|
|
422
|
+
npm run build
|
|
423
|
+
npm link
|
|
424
|
+
```
|
|
425
|
+
Run directly from repo root:
|
|
426
|
+
```powershell
|
|
427
|
+
.\elevate.exe
|
|
428
|
+
# or
|
|
429
|
+
node tools/updater/elevate/dist/cli.js
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
---
|
|
433
|
+
|
|
434
|
+
## โ Support & Funding
|
|
435
|
+
|
|
436
|
+
Elevate is free, open-source software maintained to make dependency updates safe, fast, and transparent across multi-language monorepos. If Elevate saves you or your team valuable development time, you can support its creator and future feature development:
|
|
437
|
+
|
|
438
|
+
[](https://ko-fi.com/dennisrepa)
|
|
439
|
+
|
|
440
|
+
* โ **[Buy Dennis a coffee on Ko-fi](https://ko-fi.com/dennisrepa)**
|
|
441
|
+
* ๐ป Or run: `npm fund @dennisrepa/elevate`
|
|
442
|
+
|