devready-cli 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

devready/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.3.0"

devready/baseline.py

@@ -0,0 +1,43 @@
+"""Compare a run with a saved report (`devready check --format json > baseline.json`).
+
+DevReady only reads the baseline; saving or committing it is up to you. That covers both a
+shared team baseline (committed file) and diffing against an earlier local run.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from devready.checks.project import _read
+from devready.models import Result, Status
+
+_ID = re.compile(r"^[a-z_]+(\.[a-z_]+)+$")
+_RANK = {Status.PASS: 0, Status.SKIP: 0, Status.WARN: 1, Status.ERROR: 2, Status.FAIL: 3}
+
+
+def load_baseline(path: Path) -> dict[str, Status] | None:
+    """check_id -> status, or None if the file is missing, too big, or not a v1 report."""
+    text = _read(path)
+    try:
+        data = json.loads(text) if text else None
+        if data["schema_version"] != 1:
+            return None
+        return {
+            r["check_id"]: Status(r["status"])
+            for r in data["results"]
+            if isinstance(r["check_id"], str) and _ID.match(r["check_id"])
+        }
+    except (ValueError, KeyError, TypeError):
+        return None
+
+
+def diff(results: list[Result], base: dict[str, Status]) -> tuple[list[Result], bool]:
+    """(results that are new or changed status, whether any FAIL got worse)."""
+    changed = [r for r in results if base.get(r.check_id) is not r.status]
+    worse = any(
+        r.status is Status.FAIL and _RANK[r.status] > _RANK.get(base.get(r.check_id), 0)
+        for r in changed
+    )
+    return changed, worse

devready/checks/config.py

@@ -0,0 +1,102 @@
+"""Optional `.devready.json`: extra requirements, required env var names, checks to skip.
+
+{"skip": ["project.ports"], "require": {"node": ">=20", "python": ">=3.11"}, "env": ["API_KEY"]}
+
+Read-only, same file rules as project.py. Env vars are tested for presence only; values are
+never read. Invalid files give one ERROR result and never echo file content.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from devready.checks.project import _compare, _read
+from devready.models import Result, Status
+from devready.versions import SAFE_SPEC, parse_version
+
+CONFIG_FILE = ".devready.json"
+_ID = re.compile(r"^[a-z_]+(\.[a-z_]+)*$")
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+_RUNTIMES = {"node": "Node", "python": "Python"}
+
+
+def _valid(cfg: object) -> bool:
+    if not isinstance(cfg, dict) or not set(cfg) <= {"skip", "require", "env"}:
+        return False
+    skip, req, env = cfg.get("skip", []), cfg.get("require", {}), cfg.get("env", [])
+    return (
+        isinstance(skip, list)
+        and all(isinstance(i, str) and _ID.match(i) for i in skip)
+        and isinstance(req, dict)
+        and all(
+            k in _RUNTIMES and isinstance(v, str) and SAFE_SPEC.match(v) for k, v in req.items()
+        )
+        and isinstance(env, list)
+        and all(isinstance(n, str) and _ENV_NAME.match(n) for n in env)
+    )
+
+
+def load_config(root: Path) -> tuple[dict | None, Result | None]:
+    """(config, None) if absent/valid ({} when absent), (None, error result) if invalid."""
+    text = _read(root / CONFIG_FILE)
+    if text is None:
+        return {}, None
+    try:
+        cfg = json.loads(text)
+    except ValueError:
+        cfg = None
+    if _valid(cfg):
+        return cfg, None
+    return None, Result(
+        "project.config.file",
+        "Config",
+        Status.ERROR,
+        f"{CONFIG_FILE} is invalid; it was ignored",
+        'Allowed keys: "skip" (check ids), "require" (node/python specs), "env" (variable names).',
+    )
+
+
+def check_config(
+    cfg: dict, node: str | None, python: str | None, environ: Mapping[str, str] = os.environ
+) -> list[Result]:
+    out: list[Result] = []
+    versions = {
+        "node": parse_version(node) if node else None,
+        "python": parse_version(python or ""),
+    }
+    for key, spec in cfg.get("require", {}).items():
+        out.append(
+            _compare(
+                f"project.{key}.config",
+                f"{_RUNTIMES[key]} required",
+                CONFIG_FILE,
+                spec,
+                versions[key],
+                Status.FAIL,
+            )
+        )
+    wanted = cfg.get("env", [])
+    if wanted:
+        missing = [n for n in wanted if n not in environ]
+        cid, title = "project.env.required", "Required env"
+        if missing:
+            out.append(
+                Result(
+                    cid,
+                    title,
+                    Status.FAIL,
+                    f"{len(missing)} of {len(wanted)} not set: {', '.join(missing[:10])}",
+                    "Set these variables in your shell or CI (values are never read).",
+                )
+            )
+        else:
+            out.append(Result(cid, title, Status.PASS, f"all {len(wanted)} variables are set"))
+    return out
+
+
+# Empty on purpose: pre-filling "env" from .env.example would make optional variables fail.
+TEMPLATE = json.dumps({"skip": [], "require": {}, "env": []}, indent=2)

devready/checks/platform_checks.py

@@ -0,0 +1,108 @@
+"""OS-specific pain points, each checked only when the project makes it relevant.
+
+Windows: long paths, PowerShell execution policy (blocks npm.ps1), git line endings.
+macOS/Linux: a compiler toolchain when the project looks like it builds native code.
+Read-only; fixed argv only.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from devready.checks.extras import _run
+from devready.models import Result, Status
+
+NATIVE_HINTS = ("binding.gyp", "setup.py", "Gemfile", "Cargo.toml")
+BLOCKING_POLICIES = {"Restricted", "AllSigned"}
+KNOWN_POLICIES = BLOCKING_POLICIES | {"RemoteSigned", "Unrestricted", "Bypass", "Undefined"}
+
+
+def _long_paths_enabled() -> bool | None:
+    try:
+        import winreg
+
+        with winreg.OpenKey(
+            winreg.HKEY_LOCAL_MACHINE, r"SYSTEM\CurrentControlSet\Control\FileSystem"
+        ) as key:
+            return bool(winreg.QueryValueEx(key, "LongPathsEnabled")[0])
+    except (ImportError, OSError):
+        return None
+
+
+def _windows(root: Path, run: Callable, which: Callable, long_paths: Callable) -> list[Result]:
+    out: list[Result] = []
+    if (root / "package.json").is_file():
+        if long_paths() is False:
+            out.append(
+                Result(
+                    "platform.long_paths",
+                    "Long paths",
+                    Status.WARN,
+                    "Windows long path support is off; deep node_modules trees can fail",
+                    "Enable LongPathsEnabled (administrator) and git's core.longpaths.",
+                )
+            )
+        ps = which("powershell")
+        p = (
+            run([ps, "-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"])
+            if ps
+            else None
+        )
+        policy = p.stdout.strip() if p is not None and p.returncode == 0 else ""
+        if policy in BLOCKING_POLICIES:
+            out.append(
+                Result(
+                    "platform.exec_policy",
+                    "PowerShell policy",
+                    Status.WARN,
+                    f"PowerShell policy is {policy}; npm/pnpm .ps1 scripts will be blocked",
+                    "Use cmd, or allow local scripts for your user: "
+                    "Set-ExecutionPolicy -Scope CurrentUser RemoteSigned",
+                )
+            )
+    git = which("git")
+    if git and (root / ".git").exists() and not (root / ".gitattributes").is_file():
+        p = run([git, "-C", str(root), "config", "--get", "core.autocrlf"])
+        if p is not None and not p.stdout.strip():
+            out.append(
+                Result(
+                    "platform.autocrlf",
+                    "Line endings",
+                    Status.WARN,
+                    "core.autocrlf is unset and the repo has no .gitattributes",
+                    "Add a .gitattributes with line-ending rules, or set core.autocrlf.",
+                )
+            )
+    return out
+
+
+def _build_tools(root: Path, plat: str, run: Callable, which: Callable) -> list[Result]:
+    if not any((root / n).is_file() for n in NATIVE_HINTS):
+        return []
+    cid, title = "platform.build_tools", "Build tools"
+    if plat == "darwin":
+        xs = which("xcode-select")
+        p = run([xs, "-p"]) if xs else None
+        ok = p is not None and p.returncode == 0
+        fix = "Install the Xcode Command Line Tools: xcode-select --install"
+    else:
+        ok = any(which(c) for c in ("cc", "gcc", "clang")) and bool(which("make"))
+        fix = "Install a C compiler and make (for example your distro's build-essential)."
+    if ok:
+        return [Result(cid, title, Status.PASS, "compiler toolchain found")]
+    return [Result(cid, title, Status.WARN, "no compiler toolchain found for native builds", fix)]
+
+
+def check_platform(
+    root: Path,
+    plat: str = sys.platform,
+    run: Callable = _run,
+    which: Callable = shutil.which,
+    long_paths: Callable = _long_paths_enabled,
+) -> list[Result]:
+    if plat == "win32":
+        return _windows(root, run, which, long_paths)
+    return _build_tools(root, plat, run, which)

devready/checks/project.py

@@ -11,7 +11,7 @@ import re
 from pathlib import Path
 
 from devready.models import Result, Status
-from devready.versions import SAFE_SPEC, Version, parse_version, satisfies
+from devready.versions import Version, parse_version, satisfies
 
 MAX_BYTES = 1_000_000
 
@@ -25,7 +25,8 @@ def _read(path: Path) -> str | None:
 def _compare(
     check_id: str, title: str, source: str, spec: str, installed: Version | None, miss: Status
 ) -> Result:
-    shown = spec if SAFE_SPEC.match(spec) else "(unrecognized)"
+    # Echo only specs the matcher fully parses: plain words can pass SAFE_SPEC but are not versions.
+    shown = spec if satisfies((0, 0, 0), spec) is not None else "(unrecognized)"
     if installed is None:
         return Result(check_id, title, Status.SKIP, f"{source} wants {shown}; tool not found")
     ok = satisfies(installed, spec)

devready/cli.py

@@ -6,26 +6,26 @@ import sys
 from pathlib import Path
 
 from devready import __version__
+from devready.baseline import diff, load_baseline
 from devready.formats import fix_plan, junit, sarif
 from devready.models import Result, Status
-from devready.runner import report, run_checks
+from devready.runner import matches, report, run_checks
 
 EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_INTERNAL = 0, 1, 2, 3
 
 
 def _text(results: list[Result]) -> str:
     lines = ["DevReady - Environment Check", ""]
-    lines += [f"[{r.status.value.upper():<5}] {r.title:<12} {r.summary}" for r in results]
+    for r in results:
+        lines.append(f"[{r.status.value.upper():<5}] {r.title:<12} {r.summary}")
+        if r.status is not Status.PASS and r.suggestion:
+            lines.append(f"    {r.suggestion}")
     lines += ["", "No changes were made to your system."]
     return "\n".join(lines)
 
 
-def _matches(check_id: str, ids: list[str]) -> bool:
-    return any(check_id == i or check_id.startswith(i + ".") for i in ids)
-
-
 def _selected(check_id: str, only: list[str], skip: list[str]) -> bool:
-    return (not only or _matches(check_id, only)) and not _matches(check_id, skip)
+    return (not only or matches(check_id, only)) and not matches(check_id, skip)
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -34,10 +34,14 @@ def main(argv: list[str] | None = None) -> int:
     sub = parser.add_subparsers(dest="command", required=True)
     check = sub.add_parser("check", help="run read-only environment checks")
     check.add_argument("--format", choices=["text", "json", "junit", "sarif"], default="text")
+    check.add_argument(
+        "--baseline", metavar="FILE", help="saved --format json report; show only what changed"
+    )
     fix = sub.add_parser("fix", help="print suggested fixes (never runs them)")
     fix.add_argument("--plan", action="store_true", help="required: list steps without running")
     explain = sub.add_parser("explain", help="explain what a check id means")
     explain.add_argument("check_id")
+    sub.add_parser("init", help="print a starter .devready.json (does not write it)")
     sub.add_parser("mcp", help="run as an MCP server over stdio")
     for p in (check, fix):
         p.add_argument("--project", default=".", help="directory whose version pins to compare")
@@ -54,6 +58,12 @@ def main(argv: list[str] | None = None) -> int:
 
         return serve()
 
+    if args.command == "init":
+        from devready.checks.config import TEMPLATE
+
+        print(TEMPLATE)
+        return EXIT_OK
+
     if args.command == "explain":
         from devready.explain import EXPLANATIONS
 
@@ -86,12 +96,24 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "fix":
         print(fix_plan(results))
         return EXIT_OK
+
+    regressed = None
+    if args.baseline:
+        base = load_baseline(Path(args.baseline))
+        if base is None:
+            print("devready: baseline is not a readable devready JSON report", file=sys.stderr)
+            return EXIT_USAGE
+        total = len(results)
+        results, regressed = diff(results, base)
+        print(f"Compared with baseline: {len(results)} of {total} changed.", file=sys.stderr)
     if args.format == "json":
         print(json.dumps(report(results), indent=2))
     elif args.format in ("junit", "sarif"):
         print(junit(results) if args.format == "junit" else sarif(results))
     else:
         print(_text(results))
+    if regressed is not None:  # with a baseline only a new or worse FAIL breaks the build
+        return EXIT_FAILED if regressed else EXIT_OK
     return EXIT_FAILED if any(r.status is Status.FAIL for r in results) else EXIT_OK
 
 

devready/explain.py

@@ -43,4 +43,12 @@ EXPLANATIONS = {
     "project.env.ignored": "Warns when .env exists but git would commit it (not ignored, or already tracked). Values are never shown.",
     "project.node.modules": "Checked when package.json lists dependencies: node_modules must exist and not be older than a lockfile.",
     "project.ports.free": "Ports declared in compose files (host side) or *PORT= lines in .env.example, tested by connecting to localhost. A busy port may be this project already running.",
+    "project.config.file": ".devready.json is optional. With unknown keys or invalid values it is ignored entirely. Run `devready init` for a starter.",
+    "project.node.config": "require.node in .devready.json is a hard requirement (fails when unmet).",
+    "project.python.config": "require.python in .devready.json is a hard requirement (fails when unmet).",
+    "project.env.required": "Variable NAMES listed under env in .devready.json must be set in the environment. Values are never read.",
+    "platform.long_paths": "Windows only, when package.json exists. Without LongPathsEnabled, deeply nested node_modules paths can exceed 260 characters and installs fail.",
+    "platform.exec_policy": "Windows only, when package.json exists. A Restricted or AllSigned PowerShell policy blocks npm.ps1 ('running scripts is disabled'). Use cmd or relax the policy for your user.",
+    "platform.autocrlf": "Windows only, in a git repo without .gitattributes. Unset core.autocrlf can flip line endings between Windows and Linux/macOS contributors.",
+    "platform.build_tools": "macOS/Linux, when the project has binding.gyp, setup.py, Gemfile or Cargo.toml. Native dependencies need a compiler (Xcode CLT on macOS, cc/gcc/clang and make on Linux).",
 }

devready/runner.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 import platform
 from pathlib import Path
 
+from devready.checks.config import check_config, load_config
 from devready.checks.extras import check_disk, check_docker, check_git_identity
 from devready.checks.health import check_health
+from devready.checks.platform_checks import check_platform
 from devready.checks.project import check_project
 from devready.checks.python_check import check_python
 from devready.checks.runtimes import check_runtimes
@@ -12,7 +14,12 @@ from devready.checks.tools import TOOLS, check_tool
 from devready.models import Result
 
 
+def matches(check_id: str, ids: list[str]) -> bool:
+    return any(check_id == i or check_id.startswith(i + ".") for i in ids)
+
+
 def run_checks(root: Path) -> list[Result]:
+    cfg, cfg_error = load_config(root)
     results = [check_python()]
     versions = {}
     for tool in TOOLS:
@@ -21,7 +28,12 @@ def run_checks(root: Path) -> list[Result]:
     results += check_git_identity()
     results += check_project(root, versions["node"], platform.python_version())
     results += check_runtimes(root) + check_health(root)
-    return results + check_docker(root) + check_disk(root)
+    results += check_docker(root) + check_platform(root) + check_disk(root)
+    results += (
+        [cfg_error] if cfg_error else check_config(cfg, versions["node"], platform.python_version())
+    )
+    skip = (cfg or {}).get("skip", [])
+    return [r for r in results if not matches(r.check_id, skip)]
 
 
 def report(results: list[Result]) -> dict:

{devready_cli-0.1.0.dist-info → devready_cli-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: devready-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: A local-first, read-only CLI that checks a project's environment requirements against what is installed.
 Project-URL: Homepage, https://devready-ten.vercel.app/
 Project-URL: Repository, https://github.com/Evalogical-Inc/devReady
@@ -114,6 +114,9 @@ devready explain docker.daemon    # what a check means and how to fix it
 devready check --format junit     # or sarif, for CI
 devready check --only project --skip project.ports   # filter by id or prefix
 devready fix --plan               # suggested steps only; never runs them
+devready check --format json > baseline.json   # save a snapshot (commit it for a team baseline)
+devready check --baseline baseline.json          # show only what changed; fail only on new/worse failures
+devready init > .devready.json    # optional config: skip ids, require node/python, required env names
 devready mcp                      # run as an MCP server over stdio
 devready --version
 ```
@@ -190,7 +193,7 @@ args = ["--from", "devready-cli", "devready", "mcp"]
 - Environment variable values are never read into output. Nothing leaves your machine.
 - A passing report does **not** guarantee your project builds.
 
-See [SECURITY.md](SECURITY.md) to report a vulnerability.
+See [docs/security.md](docs/security.md) for the model, [docs/versioning.md](docs/versioning.md) for what stays stable, [docs/checks.md](docs/checks.md) for every check, and [SECURITY.md](SECURITY.md) to report a vulnerability.
 
 ## Limitations (alpha)
 
@@ -202,7 +205,8 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
 
 - [x] Docker CLI + daemon reachability, `.tool-versions`, `.env` key-name diff, disk space, git identity, `devready explain`
 - [x] Port-in-use checks, more ecosystems (Go, Rust, Java, Ruby, .NET, pnpm/yarn/bun), JUnit/SARIF output, `fix --plan`, GitHub Action
-- [ ] Config file, shared baseline (see [ROADMAP.md](ROADMAP.md))
+- [x] `.devready.json` config, `--baseline` snapshots
+- [ ] Platform-specific checks (see [ROADMAP.md](ROADMAP.md))
 - [ ] Standalone binaries
 
 Have a setup problem DevReady should catch? [Open an issue](https://github.com/Evalogical-Inc/devReady/issues/new/choose). Early feedback shapes the roadmap.

{devready_cli-0.1.0.dist-info → devready_cli-0.3.0.dist-info}/RECORD

@@ -1,21 +1,24 @@
-devready/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+devready/__init__.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,22
 devready/__main__.py,sha256=c-4qpm2SKZs1nENGzSnPnChNTo8iMwjY0XaPyAApn4I,60
-devready/cli.py,sha256=OucYELHjvcFY2qw96Kc6yi4lp1RX9GnSif3MlelJ3ks,3787
-devready/explain.py,sha256=UbYKUdfdVsITUtuFIvG4vJ21SP8GI-HNPKh9xp6LCRE,4641
+devready/baseline.py,sha256=pfVzZ695bLEiSWKUBK0PNDp1S2UWTWj9lfUCDAsVS4g,1524
+devready/cli.py,sha256=oetC_jJlXk4SlyB_oKqi5XYwDouFBjeT5Ya9vUmSfXc,4736
+devready/explain.py,sha256=zVRUNzqtVdO-EcC6rUCLPuwswbMlo59xzncCBiSvi1M,5889
 devready/formats.py,sha256=akN62ouKLeZQB6POcXNzINYKHwpUd4im0n2-9rtB8eE,3129
 devready/mcp_server.py,sha256=zVm89kZL_-pZwTSWkt6rxKonytNklUSa0RCQkX0lzFk,3177
 devready/models.py,sha256=KyGp3ie2LVQmuSfzLV8tbEH_hJyU5-Vi11d0JcQPAuE,646
-devready/runner.py,sha256=3OLWash5jGZKQM30iA1ObAzF2FTmM7STsiDD3LMO9Qs,1005
+devready/runner.py,sha256=yjd7cdH0G-ksUD9viJ6coEB0iug7CazqWBQPlIW2lLU,1538
 devready/versions.py,sha256=dXKIl1-qvcfadRNaCURMoftwx7YtadDZ-YfUp-85XZc,2112
 devready/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devready/checks/config.py,sha256=SGyIot_QXmZtPLIybtxnyJEFL2aV1NemSqX_fXbFI6A,3471
 devready/checks/extras.py,sha256=pDJbFaAwjkLc92tcFagOmj-5c_vMx32_MtYa_DBfCz8,3428
 devready/checks/health.py,sha256=woaaUL2TJ_biRuiStXqJtnvPua_y69bW2quNPlwd7tQ,4235
-devready/checks/project.py,sha256=UnnjuZmG2aXXBAY45wTEP-bj4CWODMv3DPfEi1V_QDE,5983
+devready/checks/platform_checks.py,sha256=_ayTrJalFf4k5As0jq-t8GDh4IOMmgZJJdhKU4rIujQ,4113
+devready/checks/project.py,sha256=JTeSmkuz4Z7Jy5aQnP4o4TcdhQYRZfGaGhj6f0NslXw,6090
 devready/checks/python_check.py,sha256=uQCd-N0LEwt9R5gwZm5mlYiPMST1JXVDNQOdZ5xpako,328
 devready/checks/runtimes.py,sha256=OiC5LEhmfkiMseP2PbQS6Dc6TC2JhYNICU6LmdFFvqk,4446
 devready/checks/tools.py,sha256=AiL9TdIREmY7tEkkpt62DELKuJ2lhu3XcA2yGak9QkA,1616
-devready_cli-0.1.0.dist-info/METADATA,sha256=jlbjbIv1omn0U0G-ZlgrrHdDMP-O33GC4tMmAJC8pdE,10176
-devready_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-devready_cli-0.1.0.dist-info/entry_points.txt,sha256=7oAecSWtsIt7qLOP8PipOeDqhXCkEJat0oxhD4T1RpY,47
-devready_cli-0.1.0.dist-info/licenses/LICENSE,sha256=S_AQsEw289FIsOgT-OPWL5JZeV8nn5kicwEq0r9qu7s,1071
-devready_cli-0.1.0.dist-info/RECORD,,
+devready_cli-0.3.0.dist-info/METADATA,sha256=RV9QzIMUHmNpmJLfHQaUtAmKQybnQ97MILhHPl3Z2xs,10703
+devready_cli-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+devready_cli-0.3.0.dist-info/entry_points.txt,sha256=7oAecSWtsIt7qLOP8PipOeDqhXCkEJat0oxhD4T1RpY,47
+devready_cli-0.3.0.dist-info/licenses/LICENSE,sha256=S_AQsEw289FIsOgT-OPWL5JZeV8nn5kicwEq0r9qu7s,1071
+devready_cli-0.3.0.dist-info/RECORD,,