runmark 0.2.1__tar.gz

runmark-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runmark Maintainers
+
+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.

runmark-0.2.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: runmark
+Version: 0.2.1
+Summary: Know what makes your code run. Local-first development environment observability, fingerprinting, comparison, and verification.
+Author: Runmark Maintainers
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: jsonschema>=4.20.0; extra == "dev"
+Dynamic: license-file
+
+# Runmark
+
+> **Know what makes your code run.**
+> *Git tracks your code. Runmark tracks what makes your code run.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)]()
+[![Type Checked: mypy strict](https://img.shields.io/badge/mypy-strict-blue.svg)]()
+[![Code Style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)]()
+
+---
+
+## The Problem
+
+Software frequently fails because the development environment differs between machines:
+- **Developer A** has Python 3.12, Node 22, PostgreSQL 16, Redis 7, Docker 28, and valid `.env` variables.
+- **Developer B** has Python 3.11, Node 20, PostgreSQL 17, Redis stopped, and a missing environment variable.
+
+Both developers have the exact same Git repository commit, yet the application breaks.
+
+Git tracks source code. Package managers lock application dependencies. Containers reproduce environments. **Runmark is the missing observation, fingerprinting, comparison, verification, and diagnosis layer.**
+
+---
+
+## What Runmark Is NOT
+
+To keep expectations clear, Runmark is deliberately focused:
+- **Runmark is NOT a package manager.** It does not replace `pip`, `uv`, `npm`, `pnpm`, or `cargo`.
+- **Runmark is NOT a container manager.** It does not replace `docker`, `podman`, or `k8s`.
+- **Runmark is NOT an AI coding assistant.** It relies on deterministic facts and structural verification.
+- **Runmark is NOT a cloud platform.** It is 100% local-first, offline, and zero-telemetry.
+- **Runmark is NOT an environment installer.** It never automatically installs packages or mutates system state.
+- **Runmark is NOT a replacement for Git or Docker.** It observes and diagnoses what makes your code run alongside them.
+
+---
+
+## Key Features
+
+- 🏗️ **Contract Bootstrap (`runmark contract init`)**: Automatically synthesize canonical `runmark.json` contracts from project evidence manifests (`pyproject.toml`, `package.json`, `Dockerfile`, `compose.yaml`, `.env.example`).
+- 🔄 **Semantic Contract Diffing (`runmark contract diff`)**: Compare contract requirement changes against Git baseline (`HEAD:runmark.json`) or previous versions before committing.
+- 📜 **Environment Contracts (`runmark.json`)**: Declare project runtime, service, dependency, environment, network, and container requirements directly alongside source code.
+- ⚡ **Contract Proof & Evaluation (`runmark check`)**: Prove deterministically whether the host machine satisfies project requirements before running builds or tests.
+- 🔍 **Detailed Diagnostic Explanations (`runmark check --explain`)**: Deeply diagnose failed or unknown requirements with explicit evidence citations, causal explanations, and actionable remediation steps.
+- 🛠️ **Contract Tooling (`runmark contract`)**: Validate syntax, JSON schema, domain semantics, and security (`runmark contract validate`), inspect normalized specifications (`runmark contract show`), or initialize contracts (`runmark contract init`).
+- 📤 **Share & Diagnose**: Generate clean, sanitized, portable Markdown or JSON diagnostic reports (`runmark share`) ready to attach directly to GitHub Issues, Slack, or teammate chats.
+- 🛡️ **Zero-Secret Guarantee & Security Boundaries**: Multi-pass secret scanning prevents credentials, API keys, passwords in URIs, or tokens from escaping in shared reports or being stored in contract files (exit code `4`).
+- 🔍 **Safe Scanning**: Inspects project signals, runtimes (Python, Node, Docker, Git), dependencies, local services (PostgreSQL, Redis), ports, and environment variable requirements.
+- 🏷️ **Deterministic Fingerprinting**: Computes a canonical SHA-256 environment fingerprint decoupled from source code commits and timestamps.
+- ⚡ **Semantic Diffing**: Categorizes drift as `ADDED`, `REMOVED`, `CHANGED`, and `UNCHANGED` with rule-driven severity (`INFO`, `WARNING`, `CRITICAL`).
+- 🛡️ **Environment Verification**: Verifies your current machine against a baseline snapshot with CI-ready exit codes (`0`, `1`, `2`, `3`, `4`).
+- 🩺 **Doctor Mode**: Explains environment discrepancies with distinct observed evidence, inferred reasoning, and read-only remediation advice.
+- 💻 **Local-First & Cross-Platform**: 100% offline, cross-platform (Windows, Linux, macOS), atomic filesystem storage, and zero telemetry.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install runmark
+```
+
+### Basic Workflow
+
+```bash
+# 1. Bootstrap an environment contract from project evidence
+runmark contract init --dry-run
+runmark contract init --yes
+
+# 2. Check current machine against project environment contract
+runmark check
+runmark check --explain
+
+# 3. Compare contract requirement changes against Git HEAD
+runmark contract diff
+
+# 4. Inspect your current development environment
+runmark scan
+
+# 5. Save a known-good baseline snapshot
+runmark snapshot -m "Initial working dev environment"
+
+# 6. Compare current machine state against the snapshot
+runmark diff
+
+# 7. Verify compliance in CI or on coworker machines
+runmark verify --strict
+
+# 8. Diagnose and fix discrepancies
+runmark doctor
+
+# 9. Safely share a sanitized diagnostic report with teammates
+runmark share --output report.md
+
+# 10. Inspect and validate environment contracts
+runmark contract validate
+runmark contract show
+```
+
+---
+
+## Documentation
+
+- [Environment Contracts Guide](docs/contracts.md)
+- [Architecture Guide](docs/architecture.md)
+- [Specification & Exit Codes](docs/specification.md)
+- [Security Policy](docs/security.md)
+- [Detectors Guide](docs/detectors.md)
+
+---
+
+## License
+
+MIT © Runmark Maintainers

runmark-0.2.1/README.md

@@ -0,0 +1,116 @@
+# Runmark
+
+> **Know what makes your code run.**
+> *Git tracks your code. Runmark tracks what makes your code run.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)]()
+[![Type Checked: mypy strict](https://img.shields.io/badge/mypy-strict-blue.svg)]()
+[![Code Style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)]()
+
+---
+
+## The Problem
+
+Software frequently fails because the development environment differs between machines:
+- **Developer A** has Python 3.12, Node 22, PostgreSQL 16, Redis 7, Docker 28, and valid `.env` variables.
+- **Developer B** has Python 3.11, Node 20, PostgreSQL 17, Redis stopped, and a missing environment variable.
+
+Both developers have the exact same Git repository commit, yet the application breaks.
+
+Git tracks source code. Package managers lock application dependencies. Containers reproduce environments. **Runmark is the missing observation, fingerprinting, comparison, verification, and diagnosis layer.**
+
+---
+
+## What Runmark Is NOT
+
+To keep expectations clear, Runmark is deliberately focused:
+- **Runmark is NOT a package manager.** It does not replace `pip`, `uv`, `npm`, `pnpm`, or `cargo`.
+- **Runmark is NOT a container manager.** It does not replace `docker`, `podman`, or `k8s`.
+- **Runmark is NOT an AI coding assistant.** It relies on deterministic facts and structural verification.
+- **Runmark is NOT a cloud platform.** It is 100% local-first, offline, and zero-telemetry.
+- **Runmark is NOT an environment installer.** It never automatically installs packages or mutates system state.
+- **Runmark is NOT a replacement for Git or Docker.** It observes and diagnoses what makes your code run alongside them.
+
+---
+
+## Key Features
+
+- 🏗️ **Contract Bootstrap (`runmark contract init`)**: Automatically synthesize canonical `runmark.json` contracts from project evidence manifests (`pyproject.toml`, `package.json`, `Dockerfile`, `compose.yaml`, `.env.example`).
+- 🔄 **Semantic Contract Diffing (`runmark contract diff`)**: Compare contract requirement changes against Git baseline (`HEAD:runmark.json`) or previous versions before committing.
+- 📜 **Environment Contracts (`runmark.json`)**: Declare project runtime, service, dependency, environment, network, and container requirements directly alongside source code.
+- ⚡ **Contract Proof & Evaluation (`runmark check`)**: Prove deterministically whether the host machine satisfies project requirements before running builds or tests.
+- 🔍 **Detailed Diagnostic Explanations (`runmark check --explain`)**: Deeply diagnose failed or unknown requirements with explicit evidence citations, causal explanations, and actionable remediation steps.
+- 🛠️ **Contract Tooling (`runmark contract`)**: Validate syntax, JSON schema, domain semantics, and security (`runmark contract validate`), inspect normalized specifications (`runmark contract show`), or initialize contracts (`runmark contract init`).
+- 📤 **Share & Diagnose**: Generate clean, sanitized, portable Markdown or JSON diagnostic reports (`runmark share`) ready to attach directly to GitHub Issues, Slack, or teammate chats.
+- 🛡️ **Zero-Secret Guarantee & Security Boundaries**: Multi-pass secret scanning prevents credentials, API keys, passwords in URIs, or tokens from escaping in shared reports or being stored in contract files (exit code `4`).
+- 🔍 **Safe Scanning**: Inspects project signals, runtimes (Python, Node, Docker, Git), dependencies, local services (PostgreSQL, Redis), ports, and environment variable requirements.
+- 🏷️ **Deterministic Fingerprinting**: Computes a canonical SHA-256 environment fingerprint decoupled from source code commits and timestamps.
+- ⚡ **Semantic Diffing**: Categorizes drift as `ADDED`, `REMOVED`, `CHANGED`, and `UNCHANGED` with rule-driven severity (`INFO`, `WARNING`, `CRITICAL`).
+- 🛡️ **Environment Verification**: Verifies your current machine against a baseline snapshot with CI-ready exit codes (`0`, `1`, `2`, `3`, `4`).
+- 🩺 **Doctor Mode**: Explains environment discrepancies with distinct observed evidence, inferred reasoning, and read-only remediation advice.
+- 💻 **Local-First & Cross-Platform**: 100% offline, cross-platform (Windows, Linux, macOS), atomic filesystem storage, and zero telemetry.
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install runmark
+```
+
+### Basic Workflow
+
+```bash
+# 1. Bootstrap an environment contract from project evidence
+runmark contract init --dry-run
+runmark contract init --yes
+
+# 2. Check current machine against project environment contract
+runmark check
+runmark check --explain
+
+# 3. Compare contract requirement changes against Git HEAD
+runmark contract diff
+
+# 4. Inspect your current development environment
+runmark scan
+
+# 5. Save a known-good baseline snapshot
+runmark snapshot -m "Initial working dev environment"
+
+# 6. Compare current machine state against the snapshot
+runmark diff
+
+# 7. Verify compliance in CI or on coworker machines
+runmark verify --strict
+
+# 8. Diagnose and fix discrepancies
+runmark doctor
+
+# 9. Safely share a sanitized diagnostic report with teammates
+runmark share --output report.md
+
+# 10. Inspect and validate environment contracts
+runmark contract validate
+runmark contract show
+```
+
+---
+
+## Documentation
+
+- [Environment Contracts Guide](docs/contracts.md)
+- [Architecture Guide](docs/architecture.md)
+- [Specification & Exit Codes](docs/specification.md)
+- [Security Policy](docs/security.md)
+- [Detectors Guide](docs/detectors.md)
+
+---
+
+## License
+
+MIT © Runmark Maintainers

runmark-0.2.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runmark"
+version = "0.2.1"
+description = "Know what makes your code run. Local-first development environment observability, fingerprinting, comparison, and verification."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Runmark Maintainers" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "jsonschema>=4.20.0",
+]
+
+[project.scripts]
+runmark = "runmark.cli.app:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = ["E501", "B008"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q"
+testpaths = ["tests"]
+pythonpath = ["src"]

runmark-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

runmark-0.2.1/src/runmark/__init__.py

@@ -0,0 +1,7 @@
+"""Runmark: Know what makes your code run.
+
+Local-first development environment observability, fingerprinting, comparison, and verification.
+"""
+
+__version__ = "0.2.1"
+__schema_version__ = "1.0"

runmark-0.2.1/src/runmark/__main__.py

@@ -0,0 +1,8 @@
+"""Entrypoint for `python -m runmark`."""
+
+import sys
+
+from runmark.cli.app import main
+
+if __name__ == "__main__":
+    sys.exit(main())

runmark-0.2.1/src/runmark/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package."""
+
+from runmark.cli.app import app, main
+
+__all__ = ["app", "main"]

runmark-0.2.1/src/runmark/cli/app.py

@@ -0,0 +1,74 @@
+"""Runmark CLI application entrypoint."""
+
+import sys
+
+import typer
+
+from runmark.cli.commands.check import check_command
+from runmark.cli.commands.contract import contract_app
+from runmark.cli.commands.diff import diff_command
+from runmark.cli.commands.doctor import doctor_command
+from runmark.cli.commands.history import history_command
+from runmark.cli.commands.init import init_command
+from runmark.cli.commands.scan import scan_command
+from runmark.cli.commands.share import share_command
+from runmark.cli.commands.snapshot import snapshot_command
+from runmark.cli.commands.verify import verify_command
+from runmark.cli.commands.version import version_command
+from runmark.output.terminal import term
+
+app = typer.Typer(
+    name="runmark",
+    help="Runmark — Know what makes your code run.\n\nGit tracks your code. Runmark tracks what makes your code run.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Register subcommands
+app.command("init", help="Initialize Runmark tracking in the current project.")(init_command)
+app.command(
+    "scan", help="Inspect and display the complete runtime, dependency, and service state."
+)(scan_command)
+app.command(
+    "check",
+    help="Evaluate whether the host environment satisfies the project environment contract (runmark.json).",
+)(check_command)
+app.add_typer(contract_app)
+app.command(
+    "snapshot",
+    help="Capture and persist current environment state into an immutable baseline snapshot.",
+)(snapshot_command)
+app.command(
+    "diff", help="Compare environment state between snapshots or against live environment."
+)(diff_command)
+app.command("verify", help="Verify current machine environment against a baseline snapshot.")(
+    verify_command
+)
+app.command(
+    "doctor", help="Diagnose environment discrepancies and get actionable remediation advice."
+)(doctor_command)
+app.command(
+    "share",
+    help="Generate a sanitized, portable diagnostic report for sharing with teammates or issues.",
+)(share_command)
+app.command("version", help="Display version and platform diagnostics.")(version_command)
+app.command("history", help="List snapshot history.")(history_command)
+
+
+def main() -> int:
+    """Main CLI entrypoint."""
+    try:
+        app()
+        return 0
+    except typer.Exit as e:
+        return e.exit_code
+    except KeyboardInterrupt:
+        term.print("\n[dim]Operation cancelled by user.[/dim]")
+        return 130
+    except Exception as exc:
+        term.print_error(f"Unexpected error: {exc}")
+        return 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())

runmark-0.2.1/src/runmark/cli/commands/__init__.py

@@ -0,0 +1,27 @@
+"""CLI commands package."""
+
+from runmark.cli.commands.check import check_command
+from runmark.cli.commands.contract import contract_app
+from runmark.cli.commands.diff import diff_command
+from runmark.cli.commands.doctor import doctor_command
+from runmark.cli.commands.history import history_command
+from runmark.cli.commands.init import init_command
+from runmark.cli.commands.scan import scan_command
+from runmark.cli.commands.share import share_command
+from runmark.cli.commands.snapshot import snapshot_command
+from runmark.cli.commands.verify import verify_command
+from runmark.cli.commands.version import version_command
+
+__all__ = [
+    "check_command",
+    "contract_app",
+    "diff_command",
+    "doctor_command",
+    "history_command",
+    "init_command",
+    "scan_command",
+    "share_command",
+    "snapshot_command",
+    "verify_command",
+    "version_command",
+]

runmark-0.2.1/src/runmark/cli/commands/check.py

@@ -0,0 +1,54 @@
+"""CLI command: runmark check."""
+
+from pathlib import Path
+
+import typer
+
+from runmark.contracts.parser import ContractParseError
+from runmark.contracts.security import ContractSecurityError
+from runmark.contracts.validator import ContractValidationError
+from runmark.core.contract_check import ContractCheckService
+from runmark.output.contract import render_contract_check
+from runmark.output.terminal import term
+
+
+def check_command(
+    path: Path | None = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Target project root directory (defaults to current directory)",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output evaluation results as machine-readable JSON",
+    ),
+    explain: bool = typer.Option(
+        False,
+        "--explain",
+        help="Display detailed diagnostic breakdown and suggested actions for unsatisfied requirements",
+    ),
+) -> None:
+    """Evaluate whether current host environment satisfies the project environment contract (runmark.json)."""
+    try:
+        contract, result = ContractCheckService.check_environment(project_path=path)
+    except ContractSecurityError as sec_err:
+        term.print_error(str(sec_err))
+        raise typer.Exit(code=4) from None
+    except (FileNotFoundError, ContractParseError, ContractValidationError) as err:
+        term.print_error(str(err))
+        raise typer.Exit(code=2) from None
+    except Exception as exc:
+        term.print_error(f"Internal error during contract evaluation: {exc}")
+        raise typer.Exit(code=3) from None
+
+    if json_output:
+        term.print_json(result)
+    else:
+        render_contract_check(result, explain=explain)
+
+    if result.is_passed:
+        raise typer.Exit(code=0)
+    else:
+        raise typer.Exit(code=1)