azure-pipelines-tui 0.5.0 → 0.5.2

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 (2) hide show
  1. package/README.md +72 -67
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,10 @@
1
1
  # Azure Pipelines TUI
2
2
 
3
- A terminal UI for live-following Azure DevOps pipeline runs, with streaming logs via SignalR.
3
+ A terminal UI for Azure DevOps pipelines. Two standout features:
4
+
5
+ ### Live pipeline run viewer
6
+
7
+ Follow a running or completed pipeline build in real time. A stage/job tree on the left streams log output on the right via SignalR — no browser required.
4
8
 
5
9
  ```
6
10
  ┌ Pipeline ──────────────┐┌ Logs — Initialize job ───────────────────────────────┐
@@ -12,103 +16,104 @@ A terminal UI for live-following Azure DevOps pipeline runs, with streaming logs
12
16
  └────────────────────────┘└──────────────────────────────────────────────────────┘
13
17
  ```
14
18
 
19
+ ### Stages dashboard for GitOps
20
+
21
+ Per-branch overview of Plan/Apply stage pairs across recent runs. Shows the current deployment state for every branch at a glance — and when a run failed, also shows the last successful result alongside it.
22
+
23
+ ```
24
+ Stage / Branch Plan Apply
25
+ ┌ Stages: Deploy-to-prod (48 runs) ────────────────────────────────────────────┐
26
+ │ Deploy │
27
+ │ main ✓ 5m ✓ 2h │
28
+ │ feature/PLAT-123 ✗ 30m (✓2d) - │
29
+ │ release/v1.2 ✓ 1h ✓ 3h │
30
+ │ │
31
+ │ Infra │
32
+ │ main ✓ 1h ✗ 3h (✓1d) │
33
+ │ feature/PLAT-456 ○ wait - │
34
+ └───────────────────────────────────────────────────────────────────────────────┘
35
+ ```
36
+
15
37
  ## Requirements
16
38
 
17
39
  - Node.js 18+
18
40
  - Azure CLI (`az`) signed in to the correct tenant
19
- - `npm install`
20
41
 
21
42
  ## Usage
22
43
 
23
- ### TUI — `index.ts`
24
-
25
44
  ```bash
26
- # Full build URL
27
- npx tsx index.ts https://dev.azure.com/ORG/PROJECT/_build/results?buildId=1234
28
-
29
- # URL + separate buildId
30
- npx tsx index.ts https://dev.azure.com/ORG/PROJECT 1234
31
-
32
- # org/project shorthand
33
- npx tsx index.ts ORG/PROJECT 1234
34
-
35
- # Separate arguments
36
- npx tsx index.ts ORG PROJECT 1234
37
-
38
- # Keep timestamps in log output
39
- npx tsx index.ts ORG/PROJECT 1234 --keep-timestamps
45
+ npx azure-pipelines-tui ORG/PROJECT # Pipelines overview (default)
46
+ npx azure-pipelines-tui ORG/PROJECT --envs # Environments overview
47
+ npx azure-pipelines-tui ORG/PROJECT --stages <id> # Stages dashboard
48
+ npx azure-pipelines-tui ORG/PROJECT --runs <id> # Pipeline runs list
49
+ npx azure-pipelines-tui ORG/PROJECT <buildId> # Single pipeline run
50
+ npx azure-pipelines-tui <build-url> # Single pipeline run (full URL)
40
51
  ```
41
52
 
42
- #### Key bindings
53
+ ### Key bindings
43
54
 
44
55
  | Key | Action |
45
56
  |-----|--------|
46
57
  | `↑` `↓` | Navigate tree / scroll logs |
47
58
  | `Enter` `→` | Expand / select step |
48
- | `←` `Esc` | Collapse / back to tree |
49
- | `Tab` | Switch focus between tree and log panel |
59
+ | `←` `Esc` | Collapse / back |
60
+ | `Tab` | Switch focus between panels |
50
61
  | `f` `End` | Follow mode — tail the log |
51
- | `r` | Retry/restart the selected stage |
62
+ | `r` | Retry/restart selected stage |
52
63
  | `q` `Ctrl+C` | Quit |
53
64
 
54
- ### Debug — `debugSignalR.ts`
55
-
56
- Dumps all raw SignalR frames to stdout. Useful for exploring the protocol.
57
-
58
- ```bash
59
- # Full build URL
60
- npx tsx debugSignalR.ts https://dev.azure.com/ORG/PROJECT/_build/results?buildId=1234
61
-
62
- # URL + separate buildId
63
- npx tsx debugSignalR.ts https://dev.azure.com/ORG/PROJECT 1234
65
+ ## Stages dashboard
64
66
 
65
- # org/project shorthand
66
- npx tsx debugSignalR.ts ORG/PROJECT 1234
67
- ```
67
+ Status icons:
68
68
 
69
- ## How it works
69
+ | Icon | Meaning |
70
+ |------|---------|
71
+ | `✓ 5m` | Succeeded, finished 5 minutes ago |
72
+ | `✗ 30m (✓2d)` | Failed, last success was 2 days ago |
73
+ | `▶ –` | In progress |
74
+ | `⚠ 5m` | Succeeded with warnings |
75
+ | `⊘ –` | Skipped / canceled, no prior run |
76
+ | `○ –` | Pending |
77
+ | `-` | Stage did not run |
70
78
 
71
- The TUI combines two data sources:
79
+ The `*` suffix (e.g. `✓ 2d *`) means the most recent run was skipped or canceled — the cell shows the last active run instead.
72
80
 
73
- 1. **REST polling** (every 500 ms) — fetches build status, timeline records, and log lines via the Azure DevOps REST API.
74
- 2. **SignalR** (ASP.NET SignalR 1.x over WebSocket) — receives live events as log lines are written.
81
+ ### Key bindings
75
82
 
76
- ### SignalR connection
83
+ | Key | Action |
84
+ |-----|--------|
85
+ | `↑` `↓` | Navigate rows |
86
+ | `Enter` | Open the run in the browser |
87
+ | `r` | Refresh data |
88
+ | `b` | Open pipeline summary in browser |
89
+ | `p` | Go to pipelines list |
90
+ | `e` | Go to environments overview |
91
+ | `Esc` | Back |
92
+ | `q` | Quit |
77
93
 
78
- The connection requires three GUIDs, each from a different source:
94
+ See [docs/stages-dashboard-design.md](docs/stages-dashboard-design.md) for the full design.
79
95
 
80
- | Name | Source | Used in |
81
- |------|--------|---------|
82
- | `instanceId` | `GET /_apis/connectionData` | negotiate and start URLs |
83
- | `projectId` | `GET /_apis/projects/{name}` | WebSocket connect path |
84
- | `contextToken` | negotiate response `.Url` field | connect query parameter |
96
+ ## How to run locally
85
97
 
86
- ```
87
- negotiate → wss://...connect → /start → WatchBuild(projectId, buildId)
98
+ ```bash
99
+ npm install
100
+ npm run start -- ORG/PROJECT
101
+ npm run start -- ORG/PROJECT --envs
102
+ npm run start -- ORG/PROJECT --stages <id>
103
+ npm run start -- ORG/PROJECT --runs <id>
104
+ npm run start -- ORG/PROJECT <buildId>
105
+ npm run start -- <build-url>
88
106
  ```
89
107
 
90
- The WebSocket requires the bearer token in two places — as an `Authorization` header and as the `Sec-WebSocket-Protocol` subprotocol value, otherwise the server responds with a 302 redirect.
91
-
92
- ### Hub events
108
+ ## How it works
93
109
 
94
- | Method | Action |
95
- |--------|--------|
96
- | `logConsoleLines` | Streams log lines directly into the log panel |
97
- | `timelineRecordsUpdated` | Triggers a REST poll to refresh the tree |
98
- | `buildUpdated` / `buildUpdated2` | Triggers a REST poll to refresh the header |
110
+ The TUI combines two data sources:
99
111
 
100
- ## Files
112
+ 1. **REST polling** (every 500 ms) — fetches build status, timeline records, and log lines via the Azure DevOps REST API.
113
+ 2. **SignalR** (ASP.NET SignalR 1.x over WebSocket) — receives live events as log lines are written.
101
114
 
102
- | File | Purpose |
103
- |------|---------|
104
- | `index.ts` | Blessed TUI: tree + log panel |
105
- | `signalr.ts` | SignalR client (negotiate → connect → start → invoke) |
106
- | `debugSignalR.ts` | Standalone debug script |
107
- | `signalr-messages.jsonl` | Runtime dump of all SignalR frames (written by `signalr.ts`) |
108
- | `signalr-negotiate.json` | Runtime dump of the negotiate response |
115
+ See [docs/signalr-design.md](docs/signalr-design.md) for the full SignalR protocol details.
109
116
 
110
117
  ## Note
111
- We reverse engineered this undocumented streaming API by downloading the following javascript bundles and feeding them to Claude:
112
118
 
113
- * https://cdn.vsassets.io/ext/ms.vss-build-web/run/ms.vss-build-web.run.es6.Utcc_6.min.js
114
- * https://cdn.vsassets.io/ext/ms.vss-features/signalr/ms.vss-features.signalr.es6.yu31LS.min.js
119
+ The SignalR streaming API is undocumented. We reverse-engineered it by downloading and analysing the Azure DevOps web app bundles with Claude.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "azure-pipelines-tui",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
4
4
  "description": "Azure Pipelines TUI log viewer",
5
5
  "bin": {
6
6
  "azure-pipelines-tui": "./dist/tui.js"