@percy/cli-doctor 1.31.10-beta.1

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/LICENSE ADDED
@@ -0,0 +1,18 @@
1
+ Copyright © Perceptual Inc.
2
+
3
+ The MIT License (MIT)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
6
+ associated documentation files (the "Software"), to deal in the Software without restriction,
7
+ including without limitation the rights to use, copy, modify, merge, publish, distribute,
8
+ sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
9
+ furnished to do so, subject to the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be included in all copies or substantial
12
+ portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
15
+ NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
16
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
17
+ OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
18
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,155 @@
1
+ # @percy/cli-doctor
2
+
3
+ > Percy CLI sub-command that diagnoses network readiness for running Percy builds.
4
+
5
+ ---
6
+
7
+ ## Installation
8
+
9
+ `@percy/cli-doctor` is bundled with `@percy/cli`. If you use the Percy CLI you already have it:
10
+
11
+ ```sh
12
+ npx percy doctor
13
+ ```
14
+
15
+ To install standalone:
16
+
17
+ ```sh
18
+ npm install --save-dev @percy/cli-doctor
19
+ # or
20
+ yarn add --dev @percy/cli-doctor
21
+ ```
22
+
23
+ ---
24
+
25
+ ## Usage
26
+
27
+ ```
28
+ percy doctor [options]
29
+
30
+ Options:
31
+ --proxy-server <url> Proxy server to test alongside direct connectivity
32
+ e.g. http://proxy.corp.example.com:8080
33
+ --url <urls> Extra URL(s) to probe (comma-separated)
34
+ --timeout <ms> Per-request timeout in milliseconds (default: 10000)
35
+ --fix Automatically apply suggested Percy config fixes
36
+ -v, --verbose Log everything
37
+ -h, --help Show help
38
+ ```
39
+
40
+ ---
41
+
42
+ ## What it checks
43
+
44
+ ### 1 · SSL / TLS
45
+
46
+ | Scenario | Outcome |
47
+ |---|---|
48
+ | `NODE_TLS_REJECT_UNAUTHORIZED=0` is set | **Warning** – SSL verification is disabled globally |
49
+ | SSL certificate error connecting to percy.io | **Fail** – likely a MITM proxy/VPN; suggests remediation |
50
+ | SSL handshake succeeds | **Pass** |
51
+
52
+ When a certificate error is detected, the command:
53
+ * Prints actionable suggestions (contact network admin, add proxy cert to trust store)
54
+ * With `--fix`: patches the nearest `.percy.yml` to add `ssl: { rejectUnauthorized: false }`
55
+ * When running interactively in a TTY: offers an inline yes/no prompt
56
+
57
+ ### 2 · Network Connectivity
58
+
59
+ Probes each required Percy / BrowserStack domain:
60
+
61
+ | Domain | Purpose |
62
+ |---|---|
63
+ | `https://percy.io` | Percy API |
64
+ | `https://www.browserstack.com` | BrowserStack API |
65
+ | `https://hub.browserstack.com` | BrowserStack Automate |
66
+
67
+ Failure modes are classified as:
68
+
69
+ * **ENOTFOUND** → DNS resolution failure; suggest whitelisting on corporate DNS
70
+ * **ETIMEDOUT / ECONNRESET** → Firewall dropping packets; list CIDRs to whitelist
71
+ * **via proxy only** → Proxy required, suggests setting `HTTPS_PROXY`
72
+
73
+ ### 3 · Proxy Detection
74
+
75
+ Detects proxy configuration from (in priority order):
76
+
77
+ 1. **Environment variables**: `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY`
78
+ 2. **macOS system proxy**: `scutil --proxy`, `networksetup -getautoproxyurl`
79
+ 3. **Linux (GNOME)**: `gsettings org.gnome.system.proxy`
80
+ 4. **Linux (/etc)**: `/etc/environment`
81
+ 5. **Windows registry**: `HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings`
82
+
83
+ Each discovered proxy is validated by attempting connections to percy.io and
84
+ browserstack.com through it.
85
+
86
+ ### 4 · PAC / WPAD Auto-Proxy Configuration
87
+
88
+ Detects PAC file URLs from:
89
+
90
+ | Source | Detection method |
91
+ |---|---|
92
+ | macOS system | `networksetup -getautoproxyurl <interface>` |
93
+ | macOS plist | `/Library/Preferences/SystemConfiguration/preferences.plist` |
94
+ | Linux GNOME | `gsettings org.gnome.system.proxy autoconfig-url` |
95
+ | Windows | `HKCU\…\Internet Settings\AutoConfigURL` |
96
+ | Chrome / Chromium | `Default/Preferences` JSON (macOS, Linux, Windows) |
97
+ | Firefox | `~/.mozilla/firefox/*/prefs.js` (network.proxy.autoconfig_url) |
98
+
99
+ The PAC script is fetched and evaluated in a sandboxed Node.js `vm` context
100
+ using shims for all standard PAC helper functions. The result of
101
+ `FindProxyForURL("https://percy.io/", "percy.io")` is reported.
102
+
103
+ If a PAC file routes percy.io through a proxy the command surfaces the exact
104
+ `HTTPS_PROXY=…` export statement to add to your CI environment.
105
+
106
+ ---
107
+
108
+ ## Example output
109
+
110
+ ```
111
+ Percy Doctor — network readiness check
112
+
113
+ ── SSL / TLS
114
+ ✔ SSL handshake with percy.io succeeded (47ms).
115
+
116
+ ── Network Connectivity
117
+ ✔ Percy API is reachable directly (HTTP 200, 51ms).
118
+ ✔ BrowserStack API is reachable directly (HTTP 200, 72ms).
119
+ ✔ BrowserStack Automate is reachable directly (HTTP 200, 89ms).
120
+
121
+ ── Proxy Configuration
122
+ ℹ No proxy configuration detected in environment or system settings.
123
+
124
+ ── PAC / Auto-Proxy Configuration
125
+ ℹ No PAC (Proxy Auto-Configuration) file detected.
126
+
127
+ ✔ All 6 checks passed
128
+ ```
129
+
130
+ ---
131
+
132
+ ## Configuration fix (`--fix`)
133
+
134
+ When the doctor detects an SSL certificate error it can automatically patch the
135
+ nearest Percy configuration file (`.percy.yml` / `.percy.yaml`):
136
+
137
+ ```sh
138
+ percy doctor --fix
139
+ ```
140
+
141
+ This appends the following snippet to your config:
142
+
143
+ ```yaml
144
+ ssl:
145
+ rejectUnauthorized: false
146
+ ```
147
+
148
+ > **Note**: disabling SSL verification is a security trade-off. Use it only
149
+ > when your network proxy performs SSL inspection and you trust the proxy's CA.
150
+
151
+ ---
152
+
153
+ ## License
154
+
155
+ MIT