vinyasar 0.2.2__py3-none-any.whl

vinyasar/__init__.py

@@ -0,0 +1,21 @@
+"""Vinyasar: bounded self-healing supervision for Yasarda."""
+
+__version__ = "0.2.2"
+
+from .config import Profile, generate_profile, load_profile
+from .path_diagnostics import doctor_paths
+from .controller import Controller
+from .models import Effect, Issue, RunRecord
+from .yasarda_adapter import YasardaTarget
+
+__all__ = [
+    "Controller",
+    "Effect",
+    "Issue",
+    "Profile",
+    "RunRecord",
+    "YasardaTarget",
+    "doctor_paths",
+    "generate_profile",
+    "load_profile",
+]

vinyasar/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

vinyasar/cli.py

@@ -0,0 +1,181 @@
+"""Command-line interface for profile generation and one-shot reconciliation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+from yasarda.errors import YasardaError
+
+from . import __version__
+from .config import (
+    generate_profile,
+    load_profile,
+    profile_from_document,
+    run_schema_document,
+    schema_document,
+)
+from .controller import Controller
+from .paths import new_profile_destination
+from .path_diagnostics import doctor_paths
+from .errors import VinyasarError
+from .util import write_new
+
+
+def emit(value: Any) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vinyasar",
+        description="Policy-driven, evidence-bound self-healing supervision for Yasarda.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"vinyasar {__version__}"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    schema = commands.add_parser("schema", help="print a packaged JSON Schema")
+    schema.add_argument(
+        "name", nargs="?", choices=("profile", "run"), default="profile"
+    )
+
+    init = commands.add_parser(
+        "init", help="generate a profile from a read-only setup inspection"
+    )
+    init.add_argument("--repo", required=True)
+    init.add_argument("--out", required=True)
+    init.add_argument("--name")
+    init.add_argument("--state-dir")
+    init.add_argument("--reports-dir")
+    init.add_argument("--yasarda-state-dir")
+    init.add_argument(
+        "--schedule", help="scheduler-owned expression recorded in the profile"
+    )
+
+    validate = commands.add_parser("validate", help="validate and summarize a profile")
+    validate.add_argument("config")
+
+    doctor = commands.add_parser("doctor", help="read-only configuration diagnostics")
+    diagnoses = doctor.add_subparsers(dest="diagnostic", required=True)
+    paths = diagnoses.add_parser("paths", help="show supplied/canonical paths without writing")
+    paths.add_argument("config")
+
+    for name in ("inspect", "run"):
+        run = commands.add_parser(name)
+        run.add_argument("config")
+        run.add_argument("--trigger", default="manual")
+        run.add_argument("--trigger-id")
+        run.add_argument("--approve", action="append", default=[])
+    adopt = commands.add_parser("adopt-ledger", help="host-only conservative import of a legacy retry ledger")
+    adopt.add_argument("config")
+    adopt.add_argument("--legacy-revision", required=True)
+    adopt.add_argument("--yes", action="store_true", required=True)
+    return parser
+
+
+def _authority(profile: Any) -> list[dict[str, Any]]:
+    return [
+        {
+            "issue_codes": sorted(rule.issue_codes),
+            "effect": rule.effect.value,
+            "capabilities": sorted(rule.capabilities),
+            "playbooks": sorted(rule.playbooks),
+        }
+        for rule in profile.rules
+    ]
+
+
+def _summary(profile: Any) -> dict[str, Any]:
+    return {
+        "valid": True,
+        "name": profile.name,
+        "revision": profile.revision,
+        "repository": str(profile.repository),
+        "state_directory": str(profile.state_directory),
+        "report_directory": str(profile.reports.directory),
+        "triggers": [
+            {
+                "type": item.type,
+                **({"expression": item.expression} if item.expression else {}),
+            }
+            for item in profile.triggers
+        ],
+        "authority": _authority(profile),
+        "default_effect": profile.default_effect.value,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "schema":
+            emit(run_schema_document() if args.name == "run" else schema_document())
+            return 0
+        if args.command == "init":
+            output = new_profile_destination(args.out)
+            if not output.parent.is_dir():
+                raise ValueError("profile output directory must already exist")
+            document = generate_profile(
+                args.repo,
+                name=args.name,
+                state_directory=args.state_dir,
+                report_directory=args.reports_dir,
+                yasarda_state_directory=args.yasarda_state_dir,
+                schedule=args.schedule,
+            )
+            profile = profile_from_document(document, base_directory=output.parent)
+            payload = (
+                json.dumps(profile.document, indent=2, ensure_ascii=False) + "\n"
+            ).encode("utf-8")
+            write_new(output, payload)
+            emit({"created": str(output), **_summary(profile)})
+            return 0
+        if args.command == "doctor":
+            result = doctor_paths(args.config)
+            emit(result)
+            return 0 if result["ok"] else 2
+        profile = load_profile(args.config)
+        if args.command == "validate":
+            emit(_summary(profile))
+            return 0
+        if args.command == "adopt-ledger":
+            controller = Controller(profile)
+            with controller.runs.lock(timeout=30):
+                emit(controller.state.adopt_legacy(args.legacy_revision))
+            return 0
+        trigger_id = args.trigger_id or str(uuid.uuid4())
+        record = Controller(profile).run(
+            trigger_type=args.trigger,
+            trigger_id=trigger_id,
+            approvals=args.approve,
+            dry_run=args.command == "inspect",
+        )
+        emit(record.to_dict())
+        if record.outcome in {"healthy", "repaired", "dry_run"}:
+            return 0
+        if record.outcome == "approval_required":
+            return 3
+        return 2
+    except (VinyasarError, YasardaError) as exc:
+        print(json.dumps({"error": exc.to_dict()}, ensure_ascii=False), file=sys.stderr)
+        return 2
+    except (OSError, ValueError) as exc:
+        print(
+            json.dumps(
+                {"error": {"code": "invalid_request", "message": str(exc)}},
+                ensure_ascii=False,
+            ),
+            file=sys.stderr,
+        )
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vinyasar/config.py

@@ -0,0 +1,356 @@
+"""Strict profile loading and environment-derived profile generation."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+
+from .errors import ConfigurationError
+from .models import Effect
+from .paths import canonical_directory, pinned_path, read_profile_bytes
+from .util import digest, path_is_within, strict_json_loads
+
+API_VERSION = "vinyasar.yasarda.dev/v1alpha1"
+PROFILE_KIND = "VinyasarProfile"
+MAX_PROFILE_BYTES = 1024 * 1024
+
+
+@dataclass(frozen=True)
+class TriggerConfig:
+    type: str
+    expression: str | None = None
+
+
+@dataclass(frozen=True)
+class PolicyRule:
+    issue_codes: frozenset[str]
+    effect: Effect
+    capabilities: frozenset[str]
+    playbooks: frozenset[str]
+
+
+@dataclass(frozen=True)
+class Limits:
+    maximum_attempts: int
+    cooldown_seconds: int
+    maximum_actions: int
+    maximum_files: int
+    maximum_runtime_seconds: int
+    maximum_file_bytes: int = 8 * 1024 * 1024
+    maximum_total_bytes: int = 24 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class ReportConfig:
+    directory: Path
+    formats: tuple[str, ...]
+    retention_days: int
+    redact_source_content: bool
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    description: str
+    repository: Path
+    yasarda_state_directory: Path
+    state_directory: Path
+    triggers: tuple[TriggerConfig, ...]
+    default_effect: Effect
+    rules: tuple[PolicyRule, ...]
+    limits: Limits
+    reports: ReportConfig
+    revision: str
+    document: dict[str, Any]
+
+    def supports_trigger(self, trigger_type: str) -> bool:
+        return any(trigger.type == trigger_type for trigger in self.triggers)
+
+
+def schema_document() -> dict[str, Any]:
+    """Return the packaged Vinyasar profile schema."""
+    return strict_json_loads(
+        files("vinyasar").joinpath("profile.schema.json").read_text("utf-8")
+    )
+
+
+def run_schema_document() -> dict[str, Any]:
+    """Return the packaged canonical run-record schema."""
+    return strict_json_loads(
+        files("vinyasar").joinpath("run.schema.json").read_text("utf-8")
+    )
+
+
+def _load_document(path: Path) -> dict[str, Any]:
+    try:
+        payload = read_profile_bytes(path, MAX_PROFILE_BYTES)
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read profile: {exc}") from exc
+    if len(payload) > MAX_PROFILE_BYTES:
+        raise ConfigurationError("profile exceeds the 1 MiB limit")
+    try:
+        text = payload.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ConfigurationError("profile must be UTF-8") from exc
+    if path.suffix.casefold() in {".yaml", ".yml"}:
+        try:
+            import yaml  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise ConfigurationError(
+                "YAML support requires the vinyasar[yaml] extra"
+            ) from exc
+
+        class UniqueKeyLoader(yaml.SafeLoader):
+            pass
+
+        def construct_mapping(
+            loader: Any, node: Any, deep: bool = False
+        ) -> dict[Any, Any]:
+            loader.flatten_mapping(node)
+            result: dict[Any, Any] = {}
+            for key_node, value_node in node.value:
+                key = loader.construct_object(key_node, deep=deep)
+                if key in result:
+                    raise ConfigurationError(f"duplicate YAML key: {key}")
+                result[key] = loader.construct_object(value_node, deep=deep)
+            return result
+
+        UniqueKeyLoader.add_constructor(
+            yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+            construct_mapping,
+        )
+        try:
+            value = yaml.load(text, Loader=UniqueKeyLoader)
+        except ConfigurationError:
+            raise
+        except yaml.YAMLError as exc:
+            raise ConfigurationError(f"invalid YAML: {exc}") from exc
+    else:
+        value = strict_json_loads(text)
+    if not isinstance(value, dict):
+        raise ConfigurationError("profile root must be an object")
+    return value
+
+
+def _validate_schema(document: dict[str, Any]) -> None:
+    validator = Draft202012Validator(schema_document())
+    errors = sorted(
+        validator.iter_errors(document), key=lambda item: list(item.absolute_path)
+    )
+    if errors:
+        first = errors[0]
+        location = "/".join(str(part) for part in first.absolute_path) or "<root>"
+        raise ConfigurationError(
+            f"profile schema violation at {location}: {first.message}",
+            details={"violations": len(errors)},
+        )
+
+
+def _absolute(value: str, base: Path, *, strict: bool = False) -> Path:
+    return pinned_path(value, base=base, must_exist=strict)
+
+
+def profile_from_document(document: dict[str, Any], *, base_directory: Path) -> Profile:
+    """Validate and normalize an already parsed profile document."""
+    _validate_schema(document)
+    spec = document["spec"]
+    target = spec["target"]
+    repository = _absolute(target["repository"], base_directory, strict=True)
+    if not repository.is_dir():
+        raise ConfigurationError(f"target repository is not a directory: {repository}")
+    yasarda_state_path = _absolute(target["yasarda_state_directory"], base_directory)
+    state_directory = _absolute(spec["state_directory"], base_directory)
+    report_directory = _absolute(spec["reports"]["directory"], base_directory)
+    for label, path in (
+        ("state_directory", state_directory),
+        ("reports.directory", report_directory),
+        ("target.yasarda_state_directory", yasarda_state_path),
+    ):
+        if path_is_within(path, repository):
+            raise ConfigurationError(f"{label} must be outside the target repository")
+
+    rules: list[PolicyRule] = []
+    claimed_codes: set[str] = set()
+    for raw in spec["policy"]["rules"]:
+        codes = frozenset(raw["issue_codes"])
+        duplicate = claimed_codes & codes
+        if duplicate:
+            raise ConfigurationError(
+                f"issue code appears in more than one policy rule: {min(duplicate)}"
+            )
+        claimed_codes.update(codes)
+        effect = Effect(raw["effect"])
+        capabilities = frozenset(raw["capabilities"])
+        playbooks = frozenset(raw["playbooks"])
+        if effect in {Effect.AUTO, Effect.APPROVAL} and (
+            not capabilities or not playbooks
+        ):
+            raise ConfigurationError(
+                f"{effect.value} rules require explicit capabilities and playbooks"
+            )
+        if effect in {Effect.OBSERVE, Effect.ESCALATE} and (capabilities or playbooks):
+            raise ConfigurationError(
+                f"{effect.value} rules cannot grant capabilities or playbooks"
+            )
+        rules.append(PolicyRule(codes, effect, capabilities, playbooks))
+
+    triggers = tuple(
+        TriggerConfig(item["type"], item.get("expression"))
+        for item in spec["automation"]["triggers"]
+    )
+    trigger_keys = [(item.type, item.expression) for item in triggers]
+    if len(trigger_keys) != len(set(trigger_keys)):
+        raise ConfigurationError("automation triggers must be unique")
+
+    normalized = json.loads(json.dumps(document))
+    normalized["spec"]["target"]["repository"] = str(repository)
+    normalized["spec"]["target"]["yasarda_state_directory"] = str(yasarda_state_path)
+    normalized["spec"]["state_directory"] = str(state_directory)
+    normalized["spec"]["reports"]["directory"] = str(report_directory)
+    limits = spec["limits"]
+    report = spec["reports"]
+    return Profile(
+        name=document["metadata"]["name"],
+        description=document["metadata"].get("description", ""),
+        repository=repository,
+        yasarda_state_directory=yasarda_state_path,
+        state_directory=state_directory,
+        triggers=triggers,
+        default_effect=Effect(spec["policy"]["default_effect"]),
+        rules=tuple(rules),
+        limits=Limits(
+            maximum_attempts=limits["maximum_attempts"],
+            cooldown_seconds=limits["cooldown_seconds"],
+            maximum_actions=limits["maximum_actions"],
+            maximum_files=limits["maximum_files"],
+            maximum_runtime_seconds=limits["maximum_runtime_seconds"],
+            maximum_file_bytes=limits.get("maximum_file_bytes", 8 * 1024 * 1024),
+            maximum_total_bytes=limits.get("maximum_total_bytes", 24 * 1024 * 1024),
+        ),
+        reports=ReportConfig(
+            directory=report_directory,
+            formats=tuple(report["formats"]),
+            retention_days=report["retention_days"],
+            redact_source_content=report["redact_source_content"],
+        ),
+        revision=digest(normalized),
+        document=normalized,
+    )
+
+
+def load_profile(path: Path | str) -> Profile:
+    """Load, validate, normalize, and revision-pin a JSON or YAML profile."""
+    source = pinned_path(path, must_exist=True)
+    return profile_from_document(_load_document(source), base_directory=source.parent)
+
+
+def _profile_name(repository: Path) -> str:
+    value = re.sub(r"[^a-z0-9._-]+", "-", repository.name.casefold()).strip("-._")
+    return (value or "repository")[:64].rstrip("-._")
+
+
+def generate_profile(
+    repository: Path | str,
+    *,
+    name: str | None = None,
+    state_directory: Path | str | None = None,
+    report_directory: Path | str | None = None,
+    yasarda_state_directory: Path | str | None = None,
+    schedule: str | None = None,
+) -> dict[str, Any]:
+    """Resolve host setup paths and generate a profile without creating state.
+
+    Existing profiles are never rewritten; load_profile remains link-strict.
+    """
+    from .yasarda_adapter import probe_setup
+
+    root = canonical_directory(repository, must_exist=True)
+    if yasarda_state_directory is not None:
+        yasarda_state = canonical_directory(yasarda_state_directory)
+    elif os.environ.get("YASARDA_STATE_DIR"):
+        yasarda_state = canonical_directory(os.environ["YASARDA_STATE_DIR"])
+    else:
+        yasarda_state = canonical_directory(Path.home() / ".local" / "state" / "yasarda")
+    profile_name = name or _profile_name(root)
+    base_state = canonical_directory(state_directory if state_directory is not None
+                                     else Path.home() / ".local" / "state" / "vinyasar" / profile_name)
+    storage_issues = probe_setup(root, yasarda_state, base_state)
+    reports = (
+        canonical_directory(report_directory)
+        if report_directory is not None
+        else base_state / "reports"
+    )
+    triggers: list[dict[str, str]] = [
+        {"type": "manual"},
+        {"type": "on_startup"},
+        {"type": "after_failed_execution"},
+    ]
+    if schedule:
+        triggers.append({"type": "scheduled", "expression": schedule})
+    recovery_effect = (
+        "auto" if os.name == "posix" and not storage_issues else "escalate"
+    )
+    recovery_capabilities = ["yasarda.recover"] if recovery_effect == "auto" else []
+    recovery_playbooks = (
+        ["recover_interrupted_transaction"] if recovery_effect == "auto" else []
+    )
+    target: dict[str, str] = {
+        "repository": str(root),
+        "yasarda_state_directory": str(yasarda_state),
+    }
+    return {
+        "api_version": API_VERSION,
+        "kind": PROFILE_KIND,
+        "metadata": {
+            "name": profile_name,
+            "description": "Generated by Vinyasar from a read-only target inspection.",
+        },
+        "spec": {
+            "target": target,
+            "automation": {"triggers": triggers},
+            "policy": {
+                "default_effect": "escalate",
+                "rules": [
+                    {
+                        "issue_codes": ["INTERRUPTED_OPERATION"],
+                        "effect": recovery_effect,
+                        "capabilities": recovery_capabilities,
+                        "playbooks": recovery_playbooks,
+                    },
+                    {
+                        "issue_codes": ["DIRTY_WORKTREE"],
+                        "effect": "observe",
+                        "capabilities": [],
+                        "playbooks": [],
+                    },
+                    {
+                        "issue_codes": ["UNSUPPORTED_STORAGE", "INSPECTION_FAILED"],
+                        "effect": "escalate",
+                        "capabilities": [],
+                        "playbooks": [],
+                    },
+                ],
+            },
+            "limits": {
+                "maximum_attempts": 2,
+                "cooldown_seconds": 900,
+                "maximum_actions": 10,
+                "maximum_files": 100,
+                "maximum_runtime_seconds": 120,
+            },
+            "state_directory": str(base_state),
+            "reports": {
+                "directory": str(reports),
+                "formats": ["json", "markdown"],
+                "retention_days": 30,
+                "redact_source_content": True,
+            },
+        },
+    }