devready-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{devready_cli-0.1.0 → devready_cli-0.3.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devready",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "homepage": "https://devready-ten.vercel.app/",
   "description": "Read-only environment preflight: compares a project's declared Node/Python versions with what is installed.",
   "author": { "name": "DevReady contributors" },

{devready_cli-0.1.0 → devready_cli-0.3.0}/.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python: ["3.10", "3.13"]
+        python: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

{devready_cli-0.1.0 → devready_cli-0.3.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0 - 2026-10-16
+- Text output now shows the suggestion under each non-passing result (community PR #6, fixes #2).
+- Fix: a pin file with short hostile text (e.g. `.nvmrc`, `rust-toolchain.toml`, `global.json`, `.tool-versions`) was echoed in the summary when the matching tool was not installed. Only specs the matcher fully parses are now shown. Affects 0.2.0 and earlier.
+- Docs: check catalog, architecture, security model, versioning policy; CI matrix adds Python 3.11/3.12.
+- Platform checks, shown only when relevant: Windows long paths, PowerShell execution policy, `core.autocrlf`; macOS Xcode CLT and Linux compiler/make for native builds.
+
+## 0.2.0 - 2026-10-16
+- `check --baseline FILE` (and `baseline:` Action input): show only results that changed since a saved JSON report.
+- Optional `.devready.json` (`skip`, `require`, `env`) and `devready init` (prints a starter).
+
 ## 0.1.0 - 2026-10-16
 - GitHub Action (`action.yml`) wrapping `devready check`.
 - `--format junit|sarif`, `--only`/`--skip` filters, and `devready fix --plan` (suggestions only).

{devready_cli-0.1.0 → devready_cli-0.3.0}/CONTRIBUTING.md

@@ -23,7 +23,13 @@ ruff check . && ruff format --check . && pytest
 ## Adding a check
 
 Return a `Result` (`src/devready/models.py`). Run external commands with a fixed argument list and
-a timeout, and report only parsed values. Add the check to the README only once it works.
+a timeout, and report only parsed values. Then:
+
+1. Pick a stable id matching `^[a-z_]+(\.[a-z_]+)+$` (no digits or hyphens). Ids are public API.
+2. Add an entry in `src/devready/explain.py` and a row in `docs/checks.md` (a test enforces both).
+3. Register it in `src/devready/runner.py`; make it silent when the project does not use the thing.
+4. Test with injected fakes, plus a hostile-content case if it reads project files.
+5. Mention it in `CHANGELOG.md`. See [docs/versioning.md](docs/versioning.md) for what may change.
 
 ## Conduct and security
 

{devready_cli-0.1.0 → devready_cli-0.3.0}/PKG-INFO

@@ -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 → devready_cli-0.3.0}/README.md

@@ -90,6 +90,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
 ```
@@ -166,7 +169,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)
 
@@ -178,7 +181,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 → devready_cli-0.3.0}/ROADMAP.md

@@ -2,12 +2,12 @@
 
 Principles (unchanged): read-only, local-first, zero runtime dependencies, Python >= 3.10, never print env values or raw command output.
 
-## Where we are (0.1.0)
+## Where we are (0.3.0)
 
 - Tools: Git, Node, npm, Python. Docker, Go, Ruby, Java, Rust, .NET, pnpm, Yarn, Bun only when the project declares them (details in the sections below).
 - Pins compared: `.nvmrc`, `.node-version`, `.python-version`, `package.json` engines.node, `pyproject.toml` requires-python, `.tool-versions` (node/python only).
 - Also: `.env.example` vs `.env` key names, git identity presence, free disk space.
-- Interfaces: `check` (text/JSON, exit 1 on `fail`), `explain`, `mcp`, Claude Code plugin, `AGENTS.md`.
+- Interfaces: `check` (text/JSON/JUnit/SARIF, `--only`/`--skip`/`--baseline`, exit 1 on `fail`), `fix --plan`, `init`, `explain`, `mcp`, GitHub Action, Claude Code plugin, `AGENTS.md`.
 - CI and PyPI publish workflows exist.
 
 ## Decisions (from the docs review)
@@ -41,26 +41,27 @@ Principles (unchanged): read-only, local-first, zero runtime dependencies, Pytho
 - [x] `devready fix --plan`: prints each `fail`/`warn` with its suggestion. Never runs anything. (Suggestions are prose today, not exact commands.)
 - [x] `--format sarif` and `junit` (SARIF has no file locations yet, so GitHub code scanning may not show alerts).
 - [x] `--only` / `--skip` filters by check id or dotted prefix (repeatable).
-- [ ] Optional `.devready.toml` to declare requirements and silence checks (needs a 3.10-safe parser, or limit to JSON).
-- [ ] `devready init` generates that file from what it detects.
+- [x] Optional `.devready.json` (JSON, so no parser dependency): `skip` ids, `require` node/python, required `env` names.
+- [x] `devready init` prints a starter file (does not write it; DevReady stays read-only).
 
-## 0.4 - Team and CI (in progress)
+## 0.4 - Team and CI
 
 - [x] GitHub Action (`action.yml`, composite). Untested on a real runner; needs a release with the new flags.
-- [ ] Shared baseline file (committed) to compare against.
-- [ ] `--watch`/diff mode: show only what changed since the last run.
+- [x] `--baseline FILE`: compare with a saved `--format json` report (commit it for a team baseline). Shows new/changed results; exit 1 only for a new or worse `fail`. Results that disappeared are not reported.
+- [x] Diff mode = `--baseline` against your own saved snapshot. DevReady never writes the snapshot (read-only), and there is no `--watch` loop.
 
-## 0.5 - Platform specifics
+## 0.5 - Platform specifics (WSL left)
 
-- [ ] Windows: long paths enabled, execution policy, `core.autocrlf`.
+- [x] Windows: long paths (registry), PowerShell execution policy (blocks npm.ps1), `core.autocrlf` without `.gitattributes`. Only when relevant (`package.json` / a git repo). Verified against real long-paths and policy values on one Windows machine; the warning paths are unit-tested only.
 - [ ] WSL version and Docker Desktop backend.
-- [ ] macOS: Xcode CLT; Linux: common missing build deps.
+- [x] macOS Xcode CLT / Linux `cc`+`make`, only when `binding.gyp`, `setup.py`, `Gemfile` or `Cargo.toml` exists. Not run on macOS or Linux yet (CI runs the suite there, with fakes).
 
 ## 1.0 - Stabilize
 
-- [ ] Freeze JSON schema (`docs/schema.json`) with a versioning policy.
-- [ ] Test matrix on Windows/macOS/Linux x Python 3.10-3.13.
-- [ ] Docs pass: check catalog, plugin/MCP setup, contributing guide for adding a check.
+- [x] Schema frozen at v1 with a policy: `docs/versioning.md`, enforced by `tests/unit/test_stability.py` (fields, statuses, id pattern, catalog in sync).
+- [x] CI matrix: Ubuntu/Windows/macOS x Python 3.10, 3.11, 3.12, 3.13 (edited, not yet run on GitHub).
+- [x] Docs: `docs/checks.md`, `architecture.md`, `security.md`, `versioning.md`, and an "Adding a check" guide in CONTRIBUTING. Plugin/MCP setup already in `docs/agents.md`.
+- [ ] Bump to 1.0.0 once the patch release below is out and CI is green on the full matrix.
 
 ## Opt-in only (needs explicit design review)
 

{devready_cli-0.1.0 → devready_cli-0.3.0}/action.yml

@@ -16,6 +16,9 @@ inputs:
   skip:
     description: Space-separated check ids or prefixes to skip.
     default: ""
+  baseline:
+    description: Path to a committed `--format json` report; only changes are shown and only a new or worse failure fails the job.
+    default: ""
   version:
     description: devready-cli version to install (empty = latest).
     default: ""
@@ -36,10 +39,12 @@ runs:
         DR_ONLY: ${{ inputs.only }}
         DR_SKIP: ${{ inputs.skip }}
         DR_VERSION: ${{ inputs.version }}
+        DR_BASELINE: ${{ inputs.baseline }}
       run: |
         set -eu
         python -m pip install --quiet "devready-cli${DR_VERSION:+==$DR_VERSION}"
         args=(check --project "$DR_PROJECT" --format "$DR_FORMAT")
         for id in $DR_ONLY; do args+=(--only "$id"); done
         for id in $DR_SKIP; do args+=(--skip "$id"); done
+        if [ -n "$DR_BASELINE" ]; then args+=(--baseline "$DR_BASELINE"); fi
         python -m devready "${args[@]}"

devready_cli-0.3.0/docs/architecture.md

@@ -0,0 +1,18 @@
+# Architecture
+
+```
+cli.py  ->  runner.run_checks(root)  ->  checks/*  ->  list[Result]
+                  |                                        |
+          .devready.json skip                 filters (--only/--skip), --baseline diff
+                                                           |
+                                    text | json | junit | sarif | fix plan   (formats.py)
+```
+
+- `models.py`: `Result` and `Status`. Every check returns `Result`s; nothing else crosses a boundary.
+- `runner.py`: runs the checks in order, applies the config `skip` list. `mcp_server.py` calls it too.
+- `checks/`: `tools` (Git/Node/npm), `python_check`, `project` (pin files), `runtimes` (Go, Ruby, Java, Rust, .NET, pnpm, Yarn, Bun), `health` (.env ignored, node_modules, ports), `extras` (Docker, git identity, disk), `platform_checks`, `config` (`.devready.json`).
+- `versions.py`: tiny range matcher; anything it cannot parse is `skip`, never a guess.
+- `explain.py`: one text per check id; `docs/checks.md` mirrors it (enforced by a test).
+- `baseline.py`: compares a run with a saved JSON report. DevReady never writes it.
+
+Rules every check follows: fixed argv with a timeout, regular files only (no symlinks, 1 MB cap), report only parsed or validated values.

devready_cli-0.3.0/docs/checks.md

@@ -0,0 +1,57 @@
+# Check catalog
+
+Every check id DevReady can emit. Ids are a public API (see [versioning.md](versioning.md)).
+`devready explain <id>` prints the same text. A test fails if an id is missing from this file.
+
+| Check id | What it means |
+|---|---|
+| `bun.version` | Bun runtime and package manager; checked only when package.json packageManager names bun. |
+| `disk.space` | Warns below 1 GB free where the project lives; installs and builds can fail when the disk is full. |
+| `docker.cli` | Shown only when the project has a Dockerfile or compose file and the docker command is missing. |
+| `docker.daemon` | The Docker CLI can exist while the daemon is stopped. Start Docker Desktop or the service. |
+| `dotnet.version` | The .NET SDK; checked only when the project has a global.json or a dotnet pin. |
+| `git.identity` | Commits need user.name and user.email. DevReady checks they exist, never what they are. |
+| `git.version` | Git is needed to clone, branch and commit. Install: https://git-scm.com/downloads |
+| `go.version` | Go toolchain; checked only when the project has a go.mod or a golang line in .tool-versions. |
+| `java.version` | Java runtime; checked only when the project pins it (.java-version or .tool-versions). |
+| `node.version` | Node.js runs JavaScript tooling. Many projects pin a version; see project.node.* checks. |
+| `npm.version` | npm installs JavaScript dependencies and ships with Node.js. |
+| `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). |
+| `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.long_paths` | Windows only, when package.json exists. Without LongPathsEnabled, deeply nested node_modules paths can exceed 260 characters and installs fail. |
+| `pnpm.version` | pnpm package manager; checked only when package.json packageManager names pnpm. |
+| `project.bun.pin` | package.json packageManager pins the Bun version. |
+| `project.bun.tool_versions` | .tool-versions (asdf/mise) pins Bun for this project. |
+| `project.config.file` | .devready.json is optional. With unknown keys or invalid values it is ignored entirely. Run `devready init` for a starter. |
+| `project.dotnet.global` | global.json sdk.version pins the .NET SDK for this project. |
+| `project.dotnet.tool_versions` | .tool-versions (asdf/mise) pins .NET for this project. |
+| `project.env.ignored` | Warns when .env exists but git would commit it (not ignored, or already tracked). Values are never shown. |
+| `project.env.keys` | Compares variable NAMES in .env.example with .env. Values are never read or shown. |
+| `project.env.required` | Variable NAMES listed under env in .devready.json must be set in the environment. Values are never read. |
+| `project.go.mod` | The go directive in go.mod is the minimum Go version. A lower toolchain fails the check. |
+| `project.go.tool_versions` | .tool-versions (asdf/mise) pins Go for this project. |
+| `project.java.pin` | .java-version pins Java for this project (jenv, mise). |
+| `project.java.tool_versions` | .tool-versions (asdf/mise) pins Java for this project. |
+| `project.node.config` | require.node in .devready.json is a hard requirement (fails when unmet). |
+| `project.node.engines` | package.json engines.node is a hard requirement. A mismatch fails the check and npm may refuse to install. |
+| `project.node.modules` | Checked when package.json lists dependencies: node_modules must exist and not be older than a lockfile. |
+| `project.node.pin` | A .nvmrc/.node-version file says which Node the team uses. A mismatch is a warning; switch with nvm, fnm or mise. |
+| `project.node.tool_versions` | .tool-versions (asdf/mise) pins Node for this project. |
+| `project.pnpm.pin` | package.json packageManager pins the pnpm version (corepack enable can install it). |
+| `project.pnpm.tool_versions` | .tool-versions (asdf/mise) pins pnpm for this project. |
+| `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.python.config` | require.python in .devready.json is a hard requirement (fails when unmet). |
+| `project.python.pin` | .python-version (pyenv/uv) pins Python for this project. |
+| `project.python.requires` | pyproject.toml requires-python is a hard requirement; pip refuses incompatible versions. |
+| `project.python.tool_versions` | .tool-versions (asdf/mise) pins Python for this project. |
+| `project.ruby.pin` | .ruby-version pins Ruby for this project (rbenv, rvm, mise). |
+| `project.ruby.tool_versions` | .tool-versions (asdf/mise) pins Ruby for this project. |
+| `project.rust.tool_versions` | .tool-versions (asdf/mise) pins Rust for this project. |
+| `project.rust.toolchain` | rust-toolchain(.toml) pins the Rust channel. Named channels such as stable are reported as not evaluated. |
+| `project.yarn.pin` | package.json packageManager pins the Yarn version (corepack enable can install it). |
+| `project.yarn.tool_versions` | .tool-versions (asdf/mise) pins Yarn for this project. |
+| `python.version` | The Python interpreter running DevReady; not necessarily your project's virtualenv. |
+| `ruby.version` | Ruby interpreter; checked only when the project pins it (.ruby-version or .tool-versions). |
+| `rust.version` | Rust compiler (rustc); checked only when the project has a rust-toolchain file or pin. |
+| `yarn.version` | Yarn package manager; checked only when package.json packageManager names yarn. |

devready_cli-0.3.0/docs/security.md

@@ -0,0 +1,11 @@
+# Security model
+
+DevReady is read-only and local. See [SECURITY.md](../SECURITY.md) to report a vulnerability.
+
+- **Commands:** fixed argument lists, short timeouts, no shell. Never built from project content.
+- **Files:** only named files, regular files only, symlinks skipped, 1 MB cap, never executed.
+- **Output:** only parsed digits, validated version specs, validated names and fixed phrases. Raw file or command output is never echoed, so a hostile `.nvmrc` or `package.json` cannot inject instructions into an agent reading the JSON. Tests check this.
+- **Secrets:** environment and `.env` values are never read into output; only variable names (validated) and presence.
+- **Network:** none. The only socket use is connecting to `127.0.0.1` ports the project declares.
+- **Writes:** none. `init`, `fix --plan` and `--baseline` print or read; saving files is up to you.
+- **Known limit:** project-declared ids and names pass through validated character sets, not an allowlist of meanings.

devready_cli-0.3.0/docs/versioning.md

@@ -0,0 +1,24 @@
+# Stability and versioning
+
+From 1.0, these are the public interface. Breaking any of them needs a major version.
+
+## JSON report (`--format json`, `docs/schema.json`)
+
+- `schema_version` is `1`. Fields and enum values in the schema are frozen for the 1.x line.
+- Allowed in a minor release: new check ids, new result summaries and suggestions (free text, never parse them).
+- Needs `schema_version: 2` and a major release: adding, removing or renaming a result field, adding a status, changing a field's type.
+- Check ids match `^[a-z_]+(\.[a-z_]+)+$`. Renaming or removing an id is breaking; adding one is not.
+- Statuses: `pass`, `warn`, `fail`, `skip`, `error`. `fail` means a declared requirement is unmet; `skip`/`error` mean "not evaluated".
+
+## Exit codes (`check`)
+
+`0` no blocking failure, `1` at least one `fail` (with `--baseline`: a new or worse `fail`), `2` usage error, `3` internal error.
+
+## Config and CLI
+
+- `.devready.json` keys (`skip`, `require`, `env`) are frozen; unknown keys make the file invalid by design.
+- Existing flags keep their meaning. New flags are minor releases.
+
+## Not covered
+
+Human-readable text output, JUnit/SARIF layout details beyond their formats, summary wording, and the Python import API (`devready.*` modules are internal).

{devready_cli-0.1.0 → devready_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devready-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "A local-first, read-only CLI that checks a project's environment requirements against what is installed."
 readme = "README.md"
 requires-python = ">=3.10"

devready_cli-0.3.0/src/devready/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

devready_cli-0.3.0/src/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_cli-0.3.0/src/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_cli-0.3.0/src/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_cli-0.1.0 → devready_cli-0.3.0}/src/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)