runmark 0.2.1__py3-none-any.whl

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/__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/cli/__init__.py

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

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/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/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)

runmark/cli/commands/contract.py

@@ -0,0 +1,236 @@
+"""CLI command group: runmark contract."""
+
+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.core.contract_diff import ContractDiffService
+from runmark.core.contract_init import ContractInitService
+from runmark.output.contract import (
+    render_contract_diff,
+    render_contract_preview,
+    render_contract_show,
+)
+from runmark.output.terminal import term
+
+contract_app = typer.Typer(
+    name="contract",
+    help="Inspect, validate, initialize, and display project environment contracts (runmark.json).",
+    no_args_is_help=True,
+)
+
+
+@contract_app.command(
+    "init", help="Bootstrap a runmark.json contract from discovered project evidence."
+)
+def init_contract_command(
+    path: Path | None = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Target project root directory (defaults to current directory)",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip interactive confirmation and generate contract directly",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview generated contract without modifying any files",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing runmark.json contract",
+    ),
+) -> None:
+    """Bootstrap an environment contract from project evidence."""
+    target_root = path.resolve() if path else Path.cwd().resolve()
+    target_file = target_root / "runmark.json"
+
+    # Pre-check for existing contract if not using force/dry-run
+    if target_file.exists() and not force and not dry_run:
+        term.print_error(
+            f"Environment contract 'runmark.json' already exists in '{target_root}'.\n"
+            "Use --force to replace the existing contract."
+        )
+        raise typer.Exit(code=2)
+
+    try:
+        contract, evidence, _ = ContractInitService.init_contract(
+            project_path=path,
+            force=force,
+            dry_run=True,  # Always generate in dry-run first for preview and validation
+        )
+    except ContractSecurityError as sec_err:
+        term.print_error(str(sec_err))
+        raise typer.Exit(code=4) from None
+    except FileExistsError as fe_err:
+        term.print_error(str(fe_err))
+        raise typer.Exit(code=2) 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 generating contract: {exc}")
+        raise typer.Exit(code=3) from None
+
+    # Render Preview
+    render_contract_preview(contract, evidence)
+
+    if dry_run:
+        term.print_warning("Dry-run mode enabled. No files were modified.")
+        raise typer.Exit(code=0)
+
+    # Interactive confirmation if not skipped with --yes
+    if not yes:
+        confirmed = typer.confirm("Create runmark.json?", default=True)
+        if not confirmed:
+            term.print("Aborted. No files were modified.")
+            raise typer.Exit(code=0)
+
+    # Persist contract atomically
+    try:
+        ContractInitService.init_contract(
+            project_path=path,
+            force=force,
+            dry_run=False,
+        )
+    except ContractSecurityError as sec_err:
+        term.print_error(str(sec_err))
+        raise typer.Exit(code=4) from None
+    except Exception as exc:
+        term.print_error(f"Failed to persist contract: {exc}")
+        raise typer.Exit(code=3) from None
+
+    term.print_success("Environment contract 'runmark.json' created successfully.")
+    raise typer.Exit(code=0)
+
+
+@contract_app.command(
+    "diff", help="Show semantic differences between working contract and baseline."
+)
+def diff_contract_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 semantic contract diff as machine-readable JSON",
+    ),
+) -> None:
+    """Compare working runmark.json against Git repository baseline."""
+    try:
+        diff_result = ContractDiffService.diff_contracts(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 diffing contracts: {exc}")
+        raise typer.Exit(code=3) from None
+
+    if json_output:
+        term.print_json(diff_result)
+    else:
+        render_contract_diff(diff_result)
+    raise typer.Exit(code=0)
+
+
+@contract_app.command(
+    "validate", help="Validate runmark.json syntax, schema, domain semantics, and security."
+)
+def validate_contract_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 validation status as machine-readable JSON",
+    ),
+) -> None:
+    """Validate that runmark.json is structurally, semantically, and securely valid."""
+    try:
+        contract = ContractCheckService.validate_contract(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 validating contract: {exc}")
+        raise typer.Exit(code=3) from None
+
+    if json_output:
+        term.print_json(
+            {
+                "status": "valid",
+                "version": contract.version,
+                "project": contract.project.name,
+            }
+        )
+    else:
+        term.print_success(
+            f"Environment contract 'runmark.json' is valid (version {contract.version})."
+        )
+    raise typer.Exit(code=0)
+
+
+@contract_app.command(
+    "show", help="Display the canonical / normalized interpretation of runmark.json."
+)
+def show_contract_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 canonical contract definition as machine-readable JSON",
+    ),
+) -> None:
+    """Display normalized contract specifications and canonical fingerprint."""
+    try:
+        contract, canonical, fingerprint = ContractCheckService.show_contract(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 displaying contract: {exc}")
+        raise typer.Exit(code=3) from None
+
+    if json_output:
+        term.print_json(
+            {
+                "contract": canonical,
+                "fingerprint": fingerprint,
+            }
+        )
+    else:
+        render_contract_show(contract, canonical, fingerprint)
+    raise typer.Exit(code=0)

runmark/cli/commands/diff.py

@@ -0,0 +1,90 @@
+"""CLI command: runmark diff."""
+
+from pathlib import Path
+
+import typer
+
+from runmark.core.diff import DiffEngine
+from runmark.core.scanner import Scanner
+from runmark.core.snapshot import SnapshotManager
+from runmark.models.runmark import RunmarkState
+from runmark.output.tables import render_diff
+from runmark.output.terminal import term
+from runmark.storage.paths import find_project_root
+
+
+def diff_command(
+    from_snapshot: str | None = typer.Option(
+        None,
+        "--from",
+        help="Baseline snapshot ID (defaults to current active snapshot)",
+    ),
+    to_snapshot: str | None = typer.Option(
+        None,
+        "--to",
+        help="Target snapshot ID (defaults to active live scan of current environment)",
+    ),
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Compare environment state between snapshots or against current live environment."""
+    root = find_project_root(path)
+    mgr = SnapshotManager(root)
+
+    # 1. Load baseline state
+    base_state: RunmarkState
+    if from_snapshot:
+        try:
+            base_state = mgr.get_snapshot(from_snapshot)
+        except FileNotFoundError:
+            term.print_error(f"Snapshot '{from_snapshot}' not found.")
+            raise typer.Exit(code=2) from None
+    else:
+        loaded_base = mgr.get_current()
+        if not loaded_base:
+            term.print_error(
+                "No baseline snapshot found. Run 'runmark snapshot' first to create a baseline."
+            )
+            raise typer.Exit(code=2)
+        base_state = loaded_base
+
+    # 2. Load target state
+    target_state: RunmarkState
+    if to_snapshot:
+        try:
+            target_state = mgr.get_snapshot(to_snapshot)
+        except FileNotFoundError:
+            term.print_error(f"Snapshot '{to_snapshot}' not found.")
+            raise typer.Exit(code=2) from None
+    else:
+        scanner = Scanner(root)
+        target_state = scanner.scan()
+
+    # 3. Compute semantic diff
+    diff = DiffEngine.compare(base_state, target_state)
+
+    if json_output:
+        term.print_json(
+            {
+                "from_id": diff.from_id,
+                "to_id": diff.to_id,
+                "from_fingerprint": diff.from_fingerprint,
+                "to_fingerprint": diff.to_fingerprint,
+                "is_identical": diff.is_identical,
+                "items": [
+                    {
+                        "category": item.category,
+                        "item_name": item.item_name,
+                        "classification": item.classification.value,
+                        "severity": item.severity.value,
+                        "old_value": item.old_value,
+                        "new_value": item.new_value,
+                        "description": item.description,
+                        "is_source_revision": item.is_source_revision,
+                    }
+                    for item in diff.items
+                ],
+            }
+        )
+    else:
+        render_diff(diff, term.console)

runmark/cli/commands/doctor.py

@@ -0,0 +1,73 @@
+"""CLI command: runmark doctor."""
+
+from pathlib import Path
+
+import typer
+
+from runmark.core.diff import DiffEngine
+from runmark.core.doctor import Doctor
+from runmark.core.scanner import Scanner
+from runmark.core.snapshot import SnapshotManager
+from runmark.output.tables import render_doctor
+from runmark.output.terminal import term
+from runmark.storage.paths import find_project_root
+
+
+def doctor_command(
+    snapshot: str | None = typer.Option(
+        None,
+        "--snapshot",
+        "-s",
+        help="Compare current machine against a baseline snapshot",
+    ),
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Diagnose development environment issues, missing dependencies, or baseline drift."""
+    root = find_project_root(path)
+    scanner = Scanner(root)
+    current_state = scanner.scan()
+
+    if snapshot:
+        mgr = SnapshotManager(root)
+        try:
+            expected_state = mgr.get_snapshot(snapshot)
+            diff = DiffEngine.compare(expected_state, current_state)
+            report = Doctor.diagnose_diff(diff)
+        except FileNotFoundError:
+            term.print_error(f"Snapshot '{snapshot}' not found.")
+            raise typer.Exit(code=2) from None
+    else:
+        # Check against baseline snapshot if exists, or diagnose current scan directly
+        mgr = SnapshotManager(root)
+        baseline = mgr.get_current()
+        if baseline:
+            diff = DiffEngine.compare(baseline, current_state)
+            report = Doctor.diagnose_diff(diff)
+            # If diff is clean, also do standalone check for missing required env vars in current state
+            if report.is_healthy:
+                report = Doctor.diagnose_state(current_state)
+        else:
+            report = Doctor.diagnose_state(current_state)
+
+    if json_output:
+        term.print_json(
+            {
+                "project_name": report.project_name,
+                "fingerprint": report.fingerprint,
+                "is_healthy": report.is_healthy,
+                "issues": [
+                    {
+                        "code": issue.code,
+                        "severity": issue.severity.value,
+                        "title": issue.title,
+                        "evidence": issue.evidence,
+                        "explanation": issue.explanation,
+                        "suggested_action": issue.suggested_action,
+                    }
+                    for issue in report.issues
+                ],
+            }
+        )
+    else:
+        render_doctor(report, term.console)

runmark/cli/commands/history.py

@@ -0,0 +1,25 @@
+"""CLI command: runmark history."""
+
+from pathlib import Path
+
+import typer
+
+from runmark.core.snapshot import SnapshotManager
+from runmark.output.tables import render_history
+from runmark.output.terminal import term
+from runmark.storage.paths import find_project_root
+
+
+def history_command(
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Display chronological history of captured environment snapshots."""
+    root = find_project_root(path)
+    mgr = SnapshotManager(root)
+    snapshots = mgr.list_history()
+
+    if json_output:
+        term.print_json([s.model_dump(mode="json") for s in snapshots])
+    else:
+        render_history(snapshots, term.console)

runmark/cli/commands/init.py

@@ -0,0 +1,65 @@
+"""CLI command: runmark init."""
+
+from pathlib import Path
+
+import typer
+from rich.panel import Panel
+
+from runmark.output.terminal import term
+from runmark.storage.filesystem import FilesystemStorage
+from runmark.storage.paths import find_project_root
+
+
+def init_command(
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing configuration"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Initialize Runmark configuration in the current project."""
+    root = find_project_root(path)
+    storage = FilesystemStorage(root)
+
+    already_initialized = storage.paths.is_initialized()
+    if already_initialized and not force:
+        if json_output:
+            term.print_json(
+                {
+                    "status": "already_initialized",
+                    "project_root": str(root),
+                    "runmark_dir": str(storage.paths.runmark_dir),
+                }
+            )
+        else:
+            term.print(
+                Panel(
+                    f"[yellow]Runmark is already initialized in:[/yellow] [bold]{root}[/bold]\n"
+                    f"Configuration: [dim]{storage.paths.config_file}[/dim]\n"
+                    f"Use [cyan]--force[/cyan] to re-initialize.",
+                    border_style="yellow",
+                )
+            )
+        return
+
+    storage.initialize(force=force)
+
+    if json_output:
+        term.print_json(
+            {
+                "status": "initialized",
+                "project_root": str(root),
+                "runmark_dir": str(storage.paths.runmark_dir),
+                "config_file": str(storage.paths.config_file),
+            }
+        )
+    else:
+        term.print(
+            Panel(
+                f"[bold green]✓ Initialized Runmark in:[/bold green] [bold]{root}[/bold]\n\n"
+                f"• Created configuration: [dim]{storage.paths.config_file}[/dim]\n"
+                f"• Created snapshots dir: [dim]{storage.paths.snapshots_dir}[/dim]\n\n"
+                f"Next steps:\n"
+                f"  1. Run [bold cyan]runmark scan[/bold cyan] to inspect your environment.\n"
+                f"  2. Run [bold cyan]runmark snapshot[/bold cyan] to create your first baseline.",
+                border_style="green",
+            )
+        )