CI: strengthen PR checks across OS/Python matrix & document local verification

.github/workflows/ci.yml

@@ -2,31 +2,46 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
+    branches: [main]
 
 jobs:
   tests:
-    runs-on: ubuntu-latest
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.11", "3.12"]
 
     steps:
-      - name: Checkout repository
+      - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
 
-      - name: Install dependencies
+      - name: Install
         run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          python -m pip install -U pip
+          python -m pip install -e ".[dev]"
 
-      - name: Run Ruff
-        run: ruff check .
+      - name: Format
+        run: python -m ruff format --check .
 
-      - name: Run pytest
-        run: pytest
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Smoke
+        run: |
+          python -m sysforge --version
+          python -m sysforge doctor
+          python -m sysforge collect --pretty
+
+      - name: Tests
+        run: python -m pytest -q

.gitignore

@@ -18,3 +18,6 @@ dist/
 # Editors
 .DS_Store
 .vscode/
+
+# sysforge output artifacts
+sysforge-report.json

README.md

@@ -11,7 +11,8 @@ Modular system diagnostics and analysis CLI. Collects environment data, runs hea
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate  # Windows: .venv\Scripts\activate
-pip install -e ".[dev]"
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
 ```
 
 ## Usage
@@ -56,10 +57,17 @@ Exit codes (for `sysforge doctor` and `sysforge report`):
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate  # Windows: .venv\Scripts\activate
-pip install -e ".[dev]"
-pip install pre-commit
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+python -m pip install -U pre-commit
 pre-commit install
 pre-commit run --all-files  # optional: run on demand
-ruff check .
-pytest
+```
+
+Run the same checks locally that CI performs:
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m pytest -q
+sysforge --version
 ```

src/sysforge/__init__.py

@@ -3,4 +3,4 @@
 """
 
 __all__ = ["__version__"]
-__version__ = "0.1.0"
+__version__ = "0.1.0"

src/sysforge/cli.py

@@ -16,6 +16,7 @@
     help="sysforge — collect environment data, run health checks, and write reports.",
 )
 
+
 def _exit_code_from_summary(summary: object) -> int:
     """Map doctor `summary` to CLI exit codes.
 

src/sysforge/reporting.py

@@ -29,13 +29,13 @@ def write_report_file(data: dict[str, Any], path: Path, *, pretty: bool = False)
 
 
 def _format_bytes(value: Any) -> str:
-    if isinstance(value, (int, float)):
+    if isinstance(value, int | float):
         return f"{int(value):,} bytes"
     return "unknown"
 
 
 def _format_percent(value: Any) -> str:
-    if isinstance(value, (int, float)):
+    if isinstance(value, int | float):
         return f"{value * 100:.1f}%"
     return "unknown"