pcpulse 0.1.0__tar.gz

pcpulse-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e '.[dev]'
+      - run: pytest -q
+      - run: ruff check .
+      - run: mypy src

pcpulse-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage

pcpulse-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — Initial public release
+
+- Cross-platform system snapshot API
+- JSON and Markdown serialization
+- CLI snapshot and doctor commands
+- Versioned snapshot schema
+- Privacy-conscious identity opt-in
+- Automated tests and development tooling

pcpulse-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+PCPulse is committed to a respectful, technical, and inclusive community. Participants must avoid harassment, personal attacks, discrimination, doxxing, and intentionally disruptive behavior.
+
+Maintainers may moderate discussions, reject contributions, or restrict participation when behavior violates these expectations.

pcpulse-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Contributions are welcome. Keep changes focused and include tests for behavior changes.
+
+## Development
+
+    python -m pip install -e '.[dev]'
+
+Run:
+
+    pytest -q
+    ruff check .
+    mypy src
+
+## Pull requests
+
+Explain the problem, approach, testing performed, and compatibility or privacy implications.

pcpulse-0.1.0/GOVERNANCE.md

@@ -0,0 +1,5 @@
+# Governance
+
+PCPulse uses a maintainer-led model. Technical decisions should be discussed openly in issues and pull requests whenever practical.
+
+Changes affecting public APIs, schemas, privacy behavior, security, or compatibility require additional review and documentation.

pcpulse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Para
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pcpulse-0.1.0/MAINTAINERS.md

@@ -0,0 +1,5 @@
+# Maintainers
+
+## Project maintainer
+
+- Matthew Para — project owner and maintainer

pcpulse-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: pcpulse
+Version: 0.1.0
+Summary: Privacy-first cross-platform PC diagnostics library and CLI.
+Author: Matthew Para
+License: MIT License
+        
+        Copyright (c) 2026 Matthew Para
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,diagnostics,hardware,pc,privacy,system
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: psutil<8,>=5.9
+Requires-Dist: rich<15,>=13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PCPulse
+
+**Local-first, privacy-conscious, cross-platform PC diagnostics for humans, scripts, support tools, and developer applications.**
+
+PCPulse is an open-source Python library and CLI for collecting useful system diagnostics without requiring a cloud service. It turns local machine information into typed Python objects and stable machine-readable output.
+
+## Highlights
+
+- Cross-platform system snapshots
+- CPU, memory, disk, OS, architecture, and uptime information
+- JSON and Markdown output
+- Conservative local health checks with `pcpulse doctor`
+- Versioned snapshot schema
+- Privacy-first identity handling
+- Python library API for integration into other tools
+- No telemetry or mandatory network service
+- MIT licensed
+- Tests, linting, type checking, CI, security guidance, and contributor documentation
+
+## Installation
+
+Install the published package when available:
+
+    python -m pip install pcpulse
+
+For development:
+
+    git clone https://github.com/matthewpara567/pcpulse.git
+    cd pcpulse
+    python -m pip install -e '.[dev]'
+
+## Quick start
+
+Collect a human-readable snapshot:
+
+    pcpulse snapshot
+
+Get JSON:
+
+    pcpulse snapshot --json
+
+Get Markdown:
+
+    pcpulse snapshot --markdown
+
+Run health checks:
+
+    pcpulse doctor
+
+Get machine-readable health checks:
+
+    pcpulse doctor --json
+
+Identity information is excluded by default. Opt in explicitly:
+
+    pcpulse snapshot --include-identity
+
+## Python API
+
+    from pcpulse import collect_snapshot, run_checks
+
+    snapshot = collect_snapshot()
+    print(snapshot.to_dict())
+
+    for check in run_checks(snapshot):
+        print(check.status, check.message)
+
+The library is intended to be the stable integration layer. The CLI is an interface over that library.
+
+## Privacy
+
+PCPulse is designed around a local-first model:
+
+- No telemetry is required.
+- No account is required.
+- No cloud backend is required.
+- Hostname and username are not collected unless explicitly requested.
+- Collectors are read-only diagnostics and do not intentionally modify the host.
+- Applications should sanitize reports before sharing them externally.
+
+A diagnostic report can still contain machine-specific information such as operating-system details, mount paths, hardware counts, or uptime. Review output before publishing it.
+
+## Snapshot schema
+
+Snapshots carry an explicit schema version so consumers can distinguish format changes:
+
+    "schema_version": "1.0"
+
+The canonical JSON Schema is stored at:
+
+    schemas/snapshot-1.0.schema.json
+
+Consumers should treat schema changes as compatibility-sensitive and avoid assuming that every platform exposes every metric.
+
+## Health checks
+
+`pcpulse doctor` performs conservative checks for conditions such as high memory usage and high disk utilization.
+
+A check can report:
+
+- `ok`
+- `warning`
+- `error`
+- `unknown`
+
+Unknown is preferred over inventing a value when the operating system does not expose a metric.
+
+## Architecture
+
+PCPulse separates:
+
+1. **Collectors** — read local system information.
+2. **Models** — provide typed Python representations.
+3. **Serialization** — converts snapshots to JSON or Markdown.
+4. **Health checks** — interprets selected metrics.
+5. **CLI** — provides a user-facing command interface.
+
+This separation makes PCPulse useful as a library without requiring applications to scrape terminal output.
+
+## Development
+
+Install development dependencies:
+
+    python -m pip install -e '.[dev]'
+
+Run the test suite:
+
+    pytest -q
+
+Run linting:
+
+    ruff check .
+
+Run type checking:
+
+    mypy src
+
+## Contributing
+
+Bug fixes, documentation improvements, tests, platform compatibility work, and carefully scoped features are welcome.
+
+Before opening a pull request:
+
+- Keep the change focused.
+- Add or update tests where appropriate.
+- Document public API or schema changes.
+- Consider privacy implications.
+- Run the test, lint, and type-check commands.
+- Avoid unrelated formatting churn.
+
+See CONTRIBUTING.md for details.
+
+## Security
+
+Please do not disclose vulnerabilities in public issues. Follow SECURITY.md for responsible reporting.
+
+Security-sensitive areas include unintended network activity, unsafe parsing, dependency vulnerabilities, command execution, and accidental disclosure of local information.
+
+## Project structure
+
+    pcpulse/
+    ├── .github/
+    │   ├── ISSUE_TEMPLATE/
+    │   └── workflows/
+    ├── docs/
+    ├── examples/
+    ├── schemas/
+    ├── src/
+    │   └── pcpulse/
+    ├── tests/
+    ├── CHANGELOG.md
+    ├── CODE_OF_CONDUCT.md
+    ├── CONTRIBUTING.md
+    ├── GOVERNANCE.md
+    ├── LICENSE
+    ├── MAINTAINERS.md
+    ├── README.md
+    ├── RELEASING.md
+    ├── SECURITY.md
+    ├── SUPPORT.md
+    └── pyproject.toml
+
+## Design principles
+
+PCPulse follows a few simple principles:
+
+- **Local-first:** the core collector should work without a cloud service.
+- **Privacy-first:** identity data is opt-in.
+- **Structured:** machine-readable output is a first-class interface.
+- **Best-effort:** unavailable metrics are represented as unavailable.
+- **Read-only:** diagnostics should not silently modify the host.
+- **Compatibility-conscious:** public API and schema changes should be deliberate.
+- **Small core:** features should justify their maintenance cost.
+
+## Roadmap
+
+Potential future work includes:
+
+- More detailed platform-specific hardware metrics
+- Battery, temperature, and fan information where safely available
+- Pluggable collectors
+- Richer diagnostic bundles
+- More schema validation tooling
+- Additional operating-system compatibility tests
+- Release provenance and artifact-integrity improvements
+
+Roadmap items are not promises and may change as the project evolves.
+
+## License
+
+PCPulse is released under the MIT License. See LICENSE.
+
+## Status
+
+PCPulse is currently an early open-source project. APIs and schema details may evolve before the first stable release.

pcpulse-0.1.0/README.md

@@ -0,0 +1,215 @@
+# PCPulse
+
+**Local-first, privacy-conscious, cross-platform PC diagnostics for humans, scripts, support tools, and developer applications.**
+
+PCPulse is an open-source Python library and CLI for collecting useful system diagnostics without requiring a cloud service. It turns local machine information into typed Python objects and stable machine-readable output.
+
+## Highlights
+
+- Cross-platform system snapshots
+- CPU, memory, disk, OS, architecture, and uptime information
+- JSON and Markdown output
+- Conservative local health checks with `pcpulse doctor`
+- Versioned snapshot schema
+- Privacy-first identity handling
+- Python library API for integration into other tools
+- No telemetry or mandatory network service
+- MIT licensed
+- Tests, linting, type checking, CI, security guidance, and contributor documentation
+
+## Installation
+
+Install the published package when available:
+
+    python -m pip install pcpulse
+
+For development:
+
+    git clone https://github.com/matthewpara567/pcpulse.git
+    cd pcpulse
+    python -m pip install -e '.[dev]'
+
+## Quick start
+
+Collect a human-readable snapshot:
+
+    pcpulse snapshot
+
+Get JSON:
+
+    pcpulse snapshot --json
+
+Get Markdown:
+
+    pcpulse snapshot --markdown
+
+Run health checks:
+
+    pcpulse doctor
+
+Get machine-readable health checks:
+
+    pcpulse doctor --json
+
+Identity information is excluded by default. Opt in explicitly:
+
+    pcpulse snapshot --include-identity
+
+## Python API
+
+    from pcpulse import collect_snapshot, run_checks
+
+    snapshot = collect_snapshot()
+    print(snapshot.to_dict())
+
+    for check in run_checks(snapshot):
+        print(check.status, check.message)
+
+The library is intended to be the stable integration layer. The CLI is an interface over that library.
+
+## Privacy
+
+PCPulse is designed around a local-first model:
+
+- No telemetry is required.
+- No account is required.
+- No cloud backend is required.
+- Hostname and username are not collected unless explicitly requested.
+- Collectors are read-only diagnostics and do not intentionally modify the host.
+- Applications should sanitize reports before sharing them externally.
+
+A diagnostic report can still contain machine-specific information such as operating-system details, mount paths, hardware counts, or uptime. Review output before publishing it.
+
+## Snapshot schema
+
+Snapshots carry an explicit schema version so consumers can distinguish format changes:
+
+    "schema_version": "1.0"
+
+The canonical JSON Schema is stored at:
+
+    schemas/snapshot-1.0.schema.json
+
+Consumers should treat schema changes as compatibility-sensitive and avoid assuming that every platform exposes every metric.
+
+## Health checks
+
+`pcpulse doctor` performs conservative checks for conditions such as high memory usage and high disk utilization.
+
+A check can report:
+
+- `ok`
+- `warning`
+- `error`
+- `unknown`
+
+Unknown is preferred over inventing a value when the operating system does not expose a metric.
+
+## Architecture
+
+PCPulse separates:
+
+1. **Collectors** — read local system information.
+2. **Models** — provide typed Python representations.
+3. **Serialization** — converts snapshots to JSON or Markdown.
+4. **Health checks** — interprets selected metrics.
+5. **CLI** — provides a user-facing command interface.
+
+This separation makes PCPulse useful as a library without requiring applications to scrape terminal output.
+
+## Development
+
+Install development dependencies:
+
+    python -m pip install -e '.[dev]'
+
+Run the test suite:
+
+    pytest -q
+
+Run linting:
+
+    ruff check .
+
+Run type checking:
+
+    mypy src
+
+## Contributing
+
+Bug fixes, documentation improvements, tests, platform compatibility work, and carefully scoped features are welcome.
+
+Before opening a pull request:
+
+- Keep the change focused.
+- Add or update tests where appropriate.
+- Document public API or schema changes.
+- Consider privacy implications.
+- Run the test, lint, and type-check commands.
+- Avoid unrelated formatting churn.
+
+See CONTRIBUTING.md for details.
+
+## Security
+
+Please do not disclose vulnerabilities in public issues. Follow SECURITY.md for responsible reporting.
+
+Security-sensitive areas include unintended network activity, unsafe parsing, dependency vulnerabilities, command execution, and accidental disclosure of local information.
+
+## Project structure
+
+    pcpulse/
+    ├── .github/
+    │   ├── ISSUE_TEMPLATE/
+    │   └── workflows/
+    ├── docs/
+    ├── examples/
+    ├── schemas/
+    ├── src/
+    │   └── pcpulse/
+    ├── tests/
+    ├── CHANGELOG.md
+    ├── CODE_OF_CONDUCT.md
+    ├── CONTRIBUTING.md
+    ├── GOVERNANCE.md
+    ├── LICENSE
+    ├── MAINTAINERS.md
+    ├── README.md
+    ├── RELEASING.md
+    ├── SECURITY.md
+    ├── SUPPORT.md
+    └── pyproject.toml
+
+## Design principles
+
+PCPulse follows a few simple principles:
+
+- **Local-first:** the core collector should work without a cloud service.
+- **Privacy-first:** identity data is opt-in.
+- **Structured:** machine-readable output is a first-class interface.
+- **Best-effort:** unavailable metrics are represented as unavailable.
+- **Read-only:** diagnostics should not silently modify the host.
+- **Compatibility-conscious:** public API and schema changes should be deliberate.
+- **Small core:** features should justify their maintenance cost.
+
+## Roadmap
+
+Potential future work includes:
+
+- More detailed platform-specific hardware metrics
+- Battery, temperature, and fan information where safely available
+- Pluggable collectors
+- Richer diagnostic bundles
+- More schema validation tooling
+- Additional operating-system compatibility tests
+- Release provenance and artifact-integrity improvements
+
+Roadmap items are not promises and may change as the project evolves.
+
+## License
+
+PCPulse is released under the MIT License. See LICENSE.
+
+## Status
+
+PCPulse is currently an early open-source project. APIs and schema details may evolve before the first stable release.

pcpulse-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+Do not disclose security vulnerabilities in public issues. Report suspected vulnerabilities privately through GitHub's private vulnerability reporting when available.
+
+Do not include passwords, API keys, private keys, tokens, or personal data in reports.
+
+PCPulse is designed as a local read-only diagnostics library. Reports involving unintended network access, data disclosure, command execution, unsafe parsing, or dependency vulnerabilities are especially important.

pcpulse-0.1.0/SUPPORT.md

@@ -0,0 +1,7 @@
+# Support
+
+For bugs, open a GitHub issue with the Python version, operating system, PCPulse version, reproduction steps, and sanitized output.
+
+Do not post credentials, private tokens, private keys, or other sensitive information.
+
+For security issues, follow SECURITY.md.

pcpulse-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,32 @@
+# Architecture
+
+PCPulse separates collection, models, serialization, health checks, and the CLI.
+
+## Data flow
+
+    Operating system
+          |
+          v
+      Collectors
+          |
+          v
+        Models
+        /     \
+       v       v
+ Serialization Health checks
+       |       |
+       v       v
+    JSON/MD   Doctor
+          \
+           v
+          CLI
+
+Collectors read local information and return typed models. Serialization converts those models to external formats. Health checks interpret collected values without modifying the machine. The CLI provides a user-facing interface over the library.
+
+This separation allows downstream applications to import PCPulse instead of parsing terminal output.
+
+## Compatibility
+
+Platform-specific collectors should degrade gracefully. If a metric is unavailable, the model should represent it as unavailable rather than guessing.
+
+Public schema changes should be documented and versioned deliberately.

pcpulse-0.1.0/docs/DESIGN_PRINCIPLES.md

@@ -0,0 +1,29 @@
+# Design Principles
+
+## Local-first
+
+The core functionality should work without a hosted service or mandatory network connection.
+
+## Privacy-first
+
+Identity information is opt-in. Diagnostic output should be treated as potentially sensitive even when PCPulse itself does not transmit it.
+
+## Structured output
+
+JSON and typed Python objects are first-class interfaces. Human-readable terminal output is useful, but applications should use the library or structured formats.
+
+## Best-effort collection
+
+Operating systems expose different metrics. PCPulse should report unavailable values rather than fabricate data.
+
+## Read-only diagnostics
+
+Collectors should observe the host rather than silently modifying it.
+
+## Compatibility
+
+Changes to public APIs, output schemas, and command behavior should be deliberate and documented.
+
+## Maintainability
+
+The project should prefer understandable implementations and a small dependency surface over unnecessary complexity.

pcpulse-0.1.0/examples/library_usage.py

@@ -0,0 +1,7 @@
+from pcpulse import collect_snapshot, run_checks
+
+snapshot = collect_snapshot()
+print(snapshot.to_dict())
+
+for check in run_checks(snapshot):
+    print(check.status, check.message)

pcpulse-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pcpulse"
+version = "0.1.0"
+description = "Privacy-first cross-platform PC diagnostics library and CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Matthew Para" }]
+keywords = ["diagnostics", "system", "hardware", "pc", "cli", "privacy"]
+classifiers = ["Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+dependencies = ["psutil>=5.9,<8", "rich>=13,<15"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[project.scripts]
+pcpulse = "pcpulse.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pcpulse"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

pcpulse-0.1.0/schemas/snapshot-1.0.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/matthewpara567/pcpulse/blob/main/schemas/snapshot-1.0.schema.json",
+  "title": "PCPulse Snapshot",
+  "type": "object",
+  "required": [
+    "collected_at",
+    "schema_version",
+    "os",
+    "kernel",
+    "architecture",
+    "cpu",
+    "memory",
+    "disks",
+    "uptime_seconds"
+  ],
+  "properties": {
+    "collected_at": { "type": "string" },
+    "schema_version": { "const": "1.0" },
+    "os": { "type": "string" },
+    "kernel": { "type": "string" },
+    "architecture": { "type": "string" },
+    "cpu": { "type": "object" },
+    "memory": { "type": "object" },
+    "disks": { "type": "array" },
+    "uptime_seconds": { "type": ["number", "null"] },
+    "hostname": { "type": ["string", "null"] },
+    "username": { "type": ["string", "null"] },
+    "extra": { "type": "object" }
+  }
+}

pcpulse-0.1.0/src/pcpulse/__init__.py

@@ -0,0 +1,6 @@
+"""PCPulse public API."""
+from .collectors import collect_snapshot
+from .health import run_checks
+from .models import HealthCheck, Snapshot
+__all__ = ["HealthCheck", "Snapshot", "collect_snapshot", "run_checks"]
+__version__ = "0.1.0"

pcpulse-0.1.0/src/pcpulse/cli.py

@@ -0,0 +1,67 @@
+import argparse
+import json
+
+from . import __version__, collect_snapshot, run_checks
+from .serialization import to_json, to_markdown
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pcpulse",
+        description="Privacy-first cross-platform PC diagnostics.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    snapshot = sub.add_parser("snapshot", help="Collect a local system snapshot.")
+    snapshot.add_argument("--json", action="store_true")
+    snapshot.add_argument("--markdown", action="store_true")
+    snapshot.add_argument("--include-identity", action="store_true")
+
+    doctor = sub.add_parser("doctor", help="Run conservative local health checks.")
+    doctor.add_argument("--json", action="store_true")
+
+    sub.add_parser("schema", help="Show the current snapshot schema version.")
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+
+    if args.command == "schema":
+        print("1.0")
+        return 0
+
+    if args.command == "snapshot":
+        snapshot = collect_snapshot(include_identity=args.include_identity)
+        if args.json:
+            print(to_json(snapshot))
+        elif args.markdown:
+            print(to_markdown(snapshot), end="")
+        else:
+            print(f"OS: {snapshot.os}")
+            print(f"Kernel: {snapshot.kernel}")
+            print(f"Architecture: {snapshot.architecture}")
+            print(
+                f"CPU: {snapshot.cpu.logical_cores} logical / "
+                f"{snapshot.cpu.physical_cores} physical"
+            )
+            print(f"CPU load: {snapshot.cpu.load_percent}%")
+            print(f"Memory: {snapshot.memory.used_percent}% used")
+        return 0
+
+    if args.command == "doctor":
+        checks = run_checks(collect_snapshot())
+        if args.json:
+            print(json.dumps([check.__dict__ for check in checks], indent=2))
+        else:
+            for check in checks:
+                print(f"[{check.status.upper()}] {check.message}")
+        return 0 if not any(check.status == "error" for check in checks) else 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pcpulse-0.1.0/src/pcpulse/collectors.py

@@ -0,0 +1,25 @@
+from datetime import datetime, timezone
+import getpass, platform, time
+import psutil
+from .models import CpuInfo, DiskInfo, MemoryInfo, Snapshot
+SCHEMA_VERSION = "1.0"
+def collect_snapshot(*, include_identity: bool = False) -> Snapshot:
+    vm = psutil.virtual_memory()
+    disks, seen = [], set()
+    for part in psutil.disk_partitions(all=False):
+        if part.mountpoint in seen: continue
+        seen.add(part.mountpoint)
+        try:
+            u = psutil.disk_usage(part.mountpoint)
+            disks.append(DiskInfo(part.mountpoint, u.total, u.free, u.percent))
+        except (OSError, PermissionError):
+            disks.append(DiskInfo(part.mountpoint, None, None, None))
+    return Snapshot(
+        collected_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        schema_version=SCHEMA_VERSION, os=platform.system(), kernel=platform.release(),
+        architecture=platform.machine(),
+        cpu=CpuInfo(psutil.cpu_count(), psutil.cpu_count(logical=False), psutil.cpu_percent(interval=0.05)),
+        memory=MemoryInfo(vm.total, vm.available, vm.used, vm.percent), disks=disks,
+        uptime_seconds=max(0.0, time.time() - psutil.boot_time()),
+        hostname=platform.node() if include_identity else None,
+        username=getpass.getuser() if include_identity else None)

pcpulse-0.1.0/src/pcpulse/health.py

@@ -0,0 +1,16 @@
+from .models import HealthCheck, Snapshot
+def run_checks(snapshot: Snapshot) -> list[HealthCheck]:
+    checks = []
+    mem = snapshot.memory.used_percent
+    if mem is None: checks.append(HealthCheck("memory.available","unknown","Memory usage is unavailable."))
+    elif mem >= 95: checks.append(HealthCheck("memory.usage","error","Memory usage is critically high.",{"used_percent":mem}))
+    elif mem >= 85: checks.append(HealthCheck("memory.usage","warning","Memory usage is high.",{"used_percent":mem}))
+    else: checks.append(HealthCheck("memory.usage","ok","Memory usage is within the normal threshold.",{"used_percent":mem}))
+    for d in snapshot.disks:
+        v=d.used_percent
+        if v is None: status,msg="unknown",f"Disk usage unavailable for {d.path}."
+        elif v >= 95: status,msg="error",f"Disk usage is critically high on {d.path}."
+        elif v >= 85: status,msg="warning",f"Disk usage is high on {d.path}."
+        else: status,msg="ok",f"Disk usage is within the normal threshold on {d.path}."
+        checks.append(HealthCheck(f"disk.usage:{d.path}",status,msg,{"used_percent":v}))
+    return checks

pcpulse-0.1.0/src/pcpulse/models.py

@@ -0,0 +1,41 @@
+from dataclasses import asdict, dataclass, field
+from typing import Any
+@dataclass(frozen=True)
+class CpuInfo:
+    logical_cores: int | None
+    physical_cores: int | None
+    load_percent: float | None
+@dataclass(frozen=True)
+class MemoryInfo:
+    total_bytes: int | None
+    available_bytes: int | None
+    used_bytes: int | None
+    used_percent: float | None
+@dataclass(frozen=True)
+class DiskInfo:
+    path: str
+    total_bytes: int | None
+    free_bytes: int | None
+    used_percent: float | None
+@dataclass(frozen=True)
+class Snapshot:
+    collected_at: str
+    schema_version: str
+    os: str
+    kernel: str
+    architecture: str
+    cpu: CpuInfo
+    memory: MemoryInfo
+    disks: list[DiskInfo] = field(default_factory=list)
+    uptime_seconds: float | None = None
+    hostname: str | None = None
+    username: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+@dataclass(frozen=True)
+class HealthCheck:
+    id: str
+    status: str
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)

pcpulse-0.1.0/src/pcpulse/serialization.py

@@ -0,0 +1,12 @@
+import json
+from typing import Any
+from .models import Snapshot
+def to_dict(snapshot: Snapshot) -> dict[str, Any]: return snapshot.to_dict()
+def to_json(snapshot: Snapshot) -> str: return json.dumps(to_dict(snapshot), indent=2)
+def to_markdown(snapshot: Snapshot) -> str:
+    rows=[("OS",snapshot.os),("Kernel",snapshot.kernel),("Architecture",snapshot.architecture),("CPU logical",snapshot.cpu.logical_cores),("CPU physical",snapshot.cpu.physical_cores),("CPU load",snapshot.cpu.load_percent),("Memory used",snapshot.memory.used_percent),("Uptime seconds",snapshot.uptime_seconds)]
+    out=["# PCPulse System Snapshot","","| Metric | Value |","|---|---|"]
+    out += [f"| {k} | {v if v is not None else 'unavailable'} |" for k,v in rows]
+    out += ["","## Disks"]
+    out += [f"- {d.path}: {d.used_percent if d.used_percent is not None else 'unavailable'}% used" for d in snapshot.disks]
+    return "\n".join(out)+"\n"

pcpulse-0.1.0/tests/test_cli.py

@@ -0,0 +1,9 @@
+import sys
+from pcpulse.cli import main
+def test_schema_command(capsys):
+    old=sys.argv
+    try:
+        sys.argv=["pcpulse","schema"]
+        assert main()==0
+        assert capsys.readouterr().out.strip()=="1.0"
+    finally: sys.argv=old

pcpulse-0.1.0/tests/test_collectors.py

@@ -0,0 +1,5 @@
+from pcpulse import collect_snapshot
+def test_snapshot_has_core_fields():
+    s=collect_snapshot()
+    assert s.schema_version=="1.0"
+    assert s.os and s.architecture

pcpulse-0.1.0/tests/test_health.py

@@ -0,0 +1,5 @@
+from pcpulse import collect_snapshot, run_checks
+def test_health_checks_return_results():
+    checks=run_checks(collect_snapshot())
+    assert checks
+    assert all(c.status in {"ok","warning","error","unknown"} for c in checks)

pcpulse-0.1.0/tests/test_serialization.py

@@ -0,0 +1,7 @@
+import json
+from pcpulse import collect_snapshot
+from pcpulse.serialization import to_json, to_markdown
+def test_json_is_valid():
+    assert json.loads(to_json(collect_snapshot()))["schema_version"]=="1.0"
+def test_markdown_contains_title():
+    assert "PCPulse System Snapshot" in to_markdown(collect_snapshot())