@trac3er/oh-my-god 2.2.4 → 2.2.5

package/runtime/config_transaction.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import hashlib
+import os
+from pathlib import Path
+import time
+from typing import Literal, NotRequired, TypedDict, cast
+
+from runtime import mcp_config_writers as _mcp_config_writers
+
+
+_ATOMIC_WRITE_TEXT_SAFE = cast(
+    "_AtomicWriteFn",
+    getattr(_mcp_config_writers, "_atomic_write_text_safe"),
+)
+_FSYNC_DIR = cast("_FsyncDirFn", getattr(_mcp_config_writers, "_fsync_dir"))
+
+
+class _AtomicWriteFn:
+    def __call__(self, path: Path, content: str, *, mode: int = 0o600) -> None: ...
+
+
+class _FsyncDirFn:
+    def __call__(self, path: Path | str) -> None: ...
+
+
+VerificationStatus = Literal["ok", "mismatch", "missing"]
+
+
+class PlannedWriteReceipt(TypedDict):
+    path: str
+    content_hash: str
+
+
+class ExecutedWriteReceipt(TypedDict):
+    path: str
+    content_hash: str
+    executed: bool
+    error: NotRequired[str]
+
+
+class RollbackReceipt(TypedDict):
+    restored: list[str]
+    failed: list[str]
+
+
+class ConfigReceipt(TypedDict):
+    planned_writes: list[PlannedWriteReceipt]
+    executed_writes: list[ExecutedWriteReceipt]
+    backup_path: str
+    verification: dict[str, VerificationStatus]
+    executed: bool
+    rollback: RollbackReceipt | None
+
+
+class ConfigTransactionError(RuntimeError):
+    receipt: ConfigReceipt | None
+
+    def __init__(self, message: str, *, receipt: ConfigReceipt | None = None) -> None:
+        super().__init__(message)
+        self.receipt = receipt
+
+
+@dataclass
+class _PlannedWrite:
+    path: Path
+    content: str
+    content_hash: str
+    mode: int = 0o600
+
+
+class ConfigTransaction:
+    def __init__(
+        self,
+        *,
+        stale_lock_ms: int = 10000,
+        lock_path: Path | None = None,
+        backup_root: Path | None = None,
+    ) -> None:
+        home = Path.home()
+        self._lock_path: Path = lock_path or (home / ".omg" / "state" / "config-transaction.lock")
+        self._backup_root: Path = backup_root or (home / ".omg" / "backups")
+        self._stale_lock_ms: int = stale_lock_ms
+        self._planned: list[_PlannedWrite] = []
+        self._last_backup_path: str | None = None
+        self._last_backup_index: dict[str, str | None] = {}
+        self._last_planned_paths: list[str] = []
+
+    def plan(self, target_path: Path | str, content: str, *, mode: int = 0o600) -> None:
+        path = Path(target_path).resolve()
+        digest = hashlib.sha256(content.encode("utf-8")).hexdigest()
+        self._planned.append(_PlannedWrite(path=path, content=content, content_hash=digest, mode=mode))
+
+    def execute(self) -> ConfigReceipt:
+        return self._run(executed=True)
+
+    def dry_run(self) -> ConfigReceipt:
+        return self._run(executed=False)
+
+    def rollback(self) -> RollbackReceipt:
+        if not self._last_backup_path:
+            raise ConfigTransactionError("rollback requested before any backup snapshot")
+
+        restored: list[str] = []
+        failed: list[str] = []
+        backup_dir = Path(self._last_backup_path)
+        for target in self._last_planned_paths:
+            backup_file = self._last_backup_index.get(target)
+            target_path = Path(target)
+            try:
+                if backup_file is None:
+                    if target_path.exists() or target_path.is_symlink():
+                        target_path.unlink()
+                        _FSYNC_DIR(target_path.parent)
+                    restored.append(target)
+                    continue
+                source = backup_dir / backup_file
+                if not source.exists():
+                    failed.append(target)
+                    continue
+                content = source.read_text(encoding="utf-8")
+                _ATOMIC_WRITE_TEXT_SAFE(target_path, content)
+                restored.append(target)
+            except OSError:
+                failed.append(target)
+        return {"restored": restored, "failed": failed}
+
+    def list_backups(self) -> list[str]:
+        if not self._backup_root.exists():
+            return []
+        dirs = [path for path in self._backup_root.iterdir() if path.is_dir()]
+        dirs.sort(key=lambda path: (path.stat().st_mtime_ns, path.name), reverse=True)
+        return [str(path) for path in dirs]
+
+    def _run(self, *, executed: bool) -> ConfigReceipt:
+        self._acquire_lock()
+        try:
+            backup_path = self._snapshot_backups()
+            receipt: ConfigReceipt = {
+                "planned_writes": [
+                    {"path": str(item.path), "content_hash": item.content_hash}
+                    for item in self._planned
+                ],
+                "executed_writes": [],
+                "backup_path": backup_path,
+                "verification": {},
+                "executed": executed,
+                "rollback": None,
+            }
+
+            if executed:
+                for item in self._planned:
+                    try:
+                        _ATOMIC_WRITE_TEXT_SAFE(item.path, item.content, mode=item.mode)
+                        receipt["executed_writes"].append(
+                            {
+                                "path": str(item.path),
+                                "content_hash": item.content_hash,
+                                "executed": True,
+                            }
+                        )
+                    except OSError as exc:
+                        receipt["executed_writes"].append(
+                            {
+                                "path": str(item.path),
+                                "content_hash": item.content_hash,
+                                "executed": False,
+                                "error": str(exc),
+                            }
+                        )
+                        rollback_data = self.rollback()
+                        receipt["rollback"] = rollback_data
+                        raise ConfigTransactionError(str(exc), receipt=receipt) from exc
+            else:
+                for item in self._planned:
+                    receipt["executed_writes"].append(
+                        {
+                            "path": str(item.path),
+                            "content_hash": item.content_hash,
+                            "executed": False,
+                        }
+                    )
+
+            receipt["verification"] = self._verify_written_content()
+            return receipt
+        finally:
+            self._release_lock()
+
+    def _verify_written_content(self) -> dict[str, VerificationStatus]:
+        verification: dict[str, VerificationStatus] = {}
+        for item in self._planned:
+            if not item.path.exists():
+                verification[str(item.path)] = "missing"
+                continue
+            content = item.path.read_text(encoding="utf-8")
+            actual_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()
+            verification[str(item.path)] = "ok" if actual_hash == item.content_hash else "mismatch"
+        return verification
+
+    def _snapshot_backups(self) -> str:
+        backup_dir = self._new_backup_dir()
+        backup_dir.mkdir(parents=True, exist_ok=False)
+
+        index: dict[str, str | None] = {}
+        planned_paths: list[str] = []
+        for idx, item in enumerate(self._planned):
+            path_str = str(item.path)
+            planned_paths.append(path_str)
+            if not item.path.exists():
+                index[path_str] = None
+                continue
+            backup_name = f"{idx:04d}.bak"
+            backup_path = backup_dir / backup_name
+            original = item.path.read_text(encoding="utf-8")
+            _ATOMIC_WRITE_TEXT_SAFE(backup_path, original)
+            index[path_str] = backup_name
+
+        self._last_backup_path = str(backup_dir)
+        self._last_backup_index = index
+        self._last_planned_paths = planned_paths
+        return str(backup_dir)
+
+    def _new_backup_dir(self) -> Path:
+        self._backup_root.mkdir(parents=True, exist_ok=True)
+        stamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%S.%fZ")
+        base = self._backup_root / f"{stamp}-{os.getpid()}"
+        if not base.exists():
+            return base
+        counter = 1
+        while True:
+            candidate = self._backup_root / f"{stamp}-{os.getpid()}-{counter}"
+            if not candidate.exists():
+                return candidate
+            counter += 1
+
+    def _acquire_lock(self) -> None:
+        self._lock_path.parent.mkdir(parents=True, exist_ok=True)
+        self._cleanup_stale_lock_if_needed()
+        try:
+            fd = os.open(str(self._lock_path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        except FileExistsError as exc:
+            raise ConfigTransactionError(
+                f"config transaction lock already held: {self._lock_path}"
+            ) from exc
+        try:
+            ts_ms = int(time.time() * 1000)
+            payload = f"{os.getpid()}\n{ts_ms}\n".encode("utf-8")
+            written = 0
+            while written < len(payload):
+                written += os.write(fd, payload[written:])
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        _FSYNC_DIR(self._lock_path.parent)
+
+    def _release_lock(self) -> None:
+        try:
+            self._lock_path.unlink(missing_ok=True)
+        except OSError:
+            return
+        _FSYNC_DIR(self._lock_path.parent)
+
+    def _cleanup_stale_lock_if_needed(self) -> None:
+        if not self._lock_path.exists():
+            return
+
+        try:
+            raw = self._lock_path.read_text(encoding="utf-8").splitlines()
+            pid = int(raw[0].strip()) if raw else -1
+            ts_ms = int(raw[1].strip()) if len(raw) > 1 else 0
+        except (OSError, ValueError):
+            try:
+                self._lock_path.unlink(missing_ok=True)
+                _FSYNC_DIR(self._lock_path.parent)
+            except OSError:
+                pass
+            return
+
+        age_ms = int(time.time() * 1000) - ts_ms
+        if age_ms <= self._stale_lock_ms:
+            return
+        if self._pid_is_alive(pid):
+            return
+
+        try:
+            self._lock_path.unlink(missing_ok=True)
+            _FSYNC_DIR(self._lock_path.parent)
+        except OSError:
+            pass
+
+    def _pid_is_alive(self, pid: int) -> bool:
+        if pid <= 0:
+            return False
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True
+        except OSError:
+            return False
+        return True

package/runtime/contract_compiler.py

@@ -34,6 +34,7 @@ from runtime.adoption import (
     CANONICAL_REPO_URL,
     CANONICAL_VERSION,
 )
+from runtime.canonical_taxonomy import CANONICAL_PRESETS, RELEASE_CHANNELS
 from runtime.canonical_surface import get_canonical_hosts, get_compat_hosts
 from registry.verify_artifact import sign_artifact_statement, verify_artifact_statement
 
@@ -46,7 +47,8 @@ RELEASE_BLOCKING_HOSTS = tuple(get_canonical_hosts())
 # Compatibility-only hosts (for example, OpenCode) are intentionally excluded from
 # release-blocking parity and compile-readiness requirements.
 COMPATIBILITY_ONLY_HOSTS = tuple(get_compat_hosts())
-SUPPORTED_CHANNELS = ("public", "enterprise")
+SUPPORTED_PRESETS = CANONICAL_PRESETS
+SUPPORTED_CHANNELS = RELEASE_CHANNELS
 DEFAULT_REQUIRED_BUNDLES = (
     "control-plane",
     "plan-council",

package/runtime/doc_generator.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, cast
+
+from runtime.adoption import CANONICAL_VERSION, PRESET_FEATURES
+from runtime.canonical_taxonomy import (
+    RELEASE_CHANNELS,
+    CANONICAL_PRESETS,
+    SUBSCRIPTION_TIERS,
+    POLICY_PACK_IDS,
+)
+from runtime.canonical_surface import get_canonical_hosts, get_compat_hosts
+
+def generate_docs(output_root: Path) -> dict[str, Any]:
+    output_root.mkdir(parents=True, exist_ok=True)
+    
+    canonical_hosts = list(get_canonical_hosts())
+    compat_hosts = list(get_compat_hosts())
+    timestamp = datetime.now(timezone.utc).isoformat()
+    
+    # 1. support-matrix.json
+    support_matrix = {
+        "generated_by": "omg docs generate",
+        "version": CANONICAL_VERSION,
+        "generated_at": timestamp,
+        "canonical_hosts": canonical_hosts,
+        "compatibility_hosts": compat_hosts,
+        "channels": list(RELEASE_CHANNELS),
+        "presets": list(CANONICAL_PRESETS),
+        "subscription_tiers": list(SUBSCRIPTION_TIERS),
+        "policy_packs": list(POLICY_PACK_IDS),
+    }
+    _write_json(output_root / "support-matrix.json", support_matrix)
+    
+    # 2. preset-matrix.json
+    preset_matrix = {
+        "generated_by": "omg docs generate",
+        "version": CANONICAL_VERSION,
+        "generated_at": timestamp,
+        "presets": PRESET_FEATURES,
+    }
+    _write_json(output_root / "preset-matrix.json", preset_matrix)
+    
+    # 3. host-tiers.json
+    host_tiers = {
+        "generated_by": "omg docs generate",
+        "version": CANONICAL_VERSION,
+        "generated_at": timestamp,
+        "tiers": {
+            "canonical": canonical_hosts,
+            "compatibility": compat_hosts,
+        }
+    }
+    _write_json(output_root / "host-tiers.json", host_tiers)
+    
+    # 4. install-verification.json
+    install_verification = {
+        "generated_by": "omg docs generate",
+        "version": CANONICAL_VERSION,
+        "generated_at": timestamp,
+        "verification_commands": [
+            {"name": "doctor", "command": "python3 scripts/omg.py doctor"},
+            {"name": "validate", "command": "python3 scripts/omg.py validate"},
+        ],
+        "cache_paths": [
+            ".omg/cache",
+        ]
+    }
+    _write_json(output_root / "install-verification.json", install_verification)
+    
+    # 5. SUPPORT-MATRIX.md
+    support_md = [
+        "<!-- GENERATED: DO NOT EDIT MANUALLY -->",
+        "# OMG Support Matrix",
+        "",
+        "## Canonical Hosts",
+        "",
+        "| Host | Tier |",
+        "| :--- | :--- |",
+    ]
+    for host in canonical_hosts:
+        support_md.append(f"| {host} | Canonical |")
+    
+    support_md.extend([
+        "",
+        "## Compatibility Hosts",
+        "",
+        "| Host | Tier |",
+        "| :--- | :--- |",
+    ])
+    for host in compat_hosts:
+        support_md.append(f"| {host} | Compatibility |")
+    
+    _write_text(output_root / "SUPPORT-MATRIX.md", "\n".join(support_md) + "\n")
+    
+    # 6. PRESET-REFERENCE.md
+    preset_md = [
+        "<!-- GENERATED: DO NOT EDIT MANUALLY -->",
+        "# OMG Preset Reference",
+        "",
+    ]
+    
+    # Get all unique flags
+    all_flags = sorted(next(iter(PRESET_FEATURES.values())).keys())
+    
+    header = "| Feature | " + " | ".join(CANONICAL_PRESETS) + " |"
+    separator = "| :--- | " + " | ".join([":---:"] * len(CANONICAL_PRESETS)) + " |"
+    preset_md.append(header)
+    preset_md.append(separator)
+    
+    for flag in all_flags:
+        row = f"| {flag} | "
+        row += " | ".join(["✅" if PRESET_FEATURES[p].get(flag) else "❌" for p in CANONICAL_PRESETS])
+        row += " |"
+        preset_md.append(row)
+    
+    _write_text(output_root / "PRESET-REFERENCE.md", "\n".join(preset_md) + "\n")
+    
+    # 7. INSTALL-VERIFICATION-INDEX.md
+    install_md = [
+        "<!-- GENERATED: DO NOT EDIT MANUALLY -->",
+        "# OMG Install Process Verification Index",
+        "",
+        "**Purpose:** Track all CLI adapter integration points, installation flows, and critical assumptions for end-to-end verification.",
+        "",
+        f"**Version:** OMG {CANONICAL_VERSION}",
+        "",
+        "---",
+        "",
+        "## 📖 Documentation Map",
+        "",
+        "### Primary References",
+        "- **`CLI-ADAPTER-MAP.md`**",
+        "- **`QUICK-REFERENCE.md`**",
+        "",
+        "### Source Files Referenced",
+        "- `runtime/mcp_config_writers.py`",
+        "- `runtime/adoption.py`",
+        "- `OMG-setup.sh`",
+        "",
+        "---",
+        "",
+        "## 🎯 Installation Targets & Methods",
+        "",
+        "### Canonical Targets",
+    ]
+    
+    target_configs = {
+        "claude": ".mcp.json",
+        "codex": "~/.codex/config.toml",
+        "gemini": "~/.gemini/settings.json",
+        "kimi": "~/.kimi/mcp.json",
+    }
+    
+    for i, host in enumerate(canonical_hosts, 1):
+        config_path = target_configs.get(host, "Unknown")
+        install_md.extend([
+            f"{i}. **{host.capitalize()}**",
+            f"   - **Config:** `{config_path}`",
+            "",
+        ])
+    
+    install_md.extend([
+        "---",
+        "",
+        "## 🔧 Verification Commands",
+        "",
+        "| Name | Command |",
+        "| :--- | :--- |",
+    ])
+    verification_cmds = cast(list[dict[str, str]], install_verification["verification_commands"])
+    for cmd in verification_cmds:
+        name = cmd.get("name", "")
+        command = cmd.get("command", "")
+        install_md.append(f"| {name} | `{command}` |")
+        
+    install_md.extend([
+        "",
+        "## 📂 Cache Paths",
+        "",
+    ])
+    for path in install_verification["cache_paths"]:
+        install_md.append(f"- `{path}`")
+        
+    _write_text(output_root / "INSTALL-VERIFICATION-INDEX.md", "\n".join(install_md) + "\n")
+    
+    # 8. QUICK-REFERENCE.md
+    quick_md = [
+        "<!-- GENERATED: DO NOT EDIT MANUALLY -->",
+        "# OMG CLI Adapter Quick Reference",
+        "",
+        "## 🎯 Core Integration Points",
+        "",
+        "### Canonical Hosts",
+        "",
+        "| Host | Config File |",
+        "| :--- | :--- |",
+    ]
+    for host in canonical_hosts:
+        config_path = target_configs.get(host, "Unknown")
+        quick_md.append(f"| {host} | `{config_path}` |")
+        
+    quick_md.extend([
+        "",
+        "### Release Channels",
+        "",
+    ])
+    for channel in RELEASE_CHANNELS:
+        quick_md.append(f"- `{channel}`")
+        
+    quick_md.extend([
+        "",
+        "### Preset Quick Reference",
+        "",
+        "| Preset | Key Features |",
+        "| :--- | :--- |",
+    ])
+    for preset in CANONICAL_PRESETS:
+        features = [f for f, enabled in PRESET_FEATURES[preset].items() if enabled]
+        feature_summary = ", ".join(features[:5]) + ("..." if len(features) > 5 else "")
+        quick_md.append(f"| {preset} | {feature_summary or 'None'} |")
+        
+    quick_md.extend([
+        "",
+        "### Quick Commands",
+        "",
+        "| Task | Command |",
+        "| :--- | :--- |",
+        "| Setup | `/OMG:setup` |",
+        "| Browser | `/OMG:browser <goal>` |",
+        "| Crazy Mode | `/OMG:crazy <goal>` |",
+        "| Deep Plan | `/OMG:deep-plan <goal>` |",
+    ])
+    
+    _write_text(output_root / "QUICK-REFERENCE.md", "\n".join(quick_md) + "\n")
+    
+    # 9. channel-guarantees.json
+    channel_guarantees = {
+        "generated_by": "omg docs generate",
+        "version": CANONICAL_VERSION,
+        "generated_at": timestamp,
+        "channels": {
+            "public": "Standard production channel. Guarantees behavior parity across canonical hosts and standard evidence-backed verification.",
+            "enterprise": "Hardened production channel. Guarantees enhanced evidence (lineage, provenance), tier-gated policy enforcement, and compatibility with specialized policy packs (fintech, airgapped).",
+        },
+        "precedence_rule": "subscription tier → channel → policy pack → preset",
+        "policy_pack_ids": list(POLICY_PACK_IDS),
+    }
+    _write_json(output_root / "channel-guarantees.json", channel_guarantees)
+    
+    return {
+        "status": "ok",
+        "output_root": str(output_root),
+        "artifacts": [
+            "support-matrix.json",
+            "preset-matrix.json",
+            "host-tiers.json",
+            "install-verification.json",
+            "SUPPORT-MATRIX.md",
+            "PRESET-REFERENCE.md",
+            "INSTALL-VERIFICATION-INDEX.md",
+            "QUICK-REFERENCE.md",
+            "channel-guarantees.json",
+        ]
+    }
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    _ = path.write_text(json.dumps(data, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+
+def _write_text(path: Path, content: str) -> None:
+    _ = path.write_text(content, encoding="utf-8")

package/runtime/evidence_narrator.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+from runtime.verdict_schema import VerdictReceipt
+
+
+class NarrativeResult(TypedDict):
+    verdict_summary: str
+    blockers_section: list[str]
+    provenance_note: str | None
+    evidence_paths_section: list[str]
+    next_actions: list[str]
+
+
+def narrate(verdict: VerdictReceipt) -> NarrativeResult:
+    status = verdict.get("status", "pending")
+    
+    if status == "pass":
+        summary = "The verification process passed successfully."
+    elif status == "fail":
+        summary = "The verification process failed."
+    elif status == "action_required":
+        summary = "Action required to complete the verification process."
+    else:
+        summary = "The verification process is pending or in an unknown state."
+
+    blockers = list(verdict.get("blockers", []))
+    next_steps = list(verdict.get("next_steps", []))
+    
+    evidence_paths = verdict.get("evidence_paths", {})
+    evidence_sections = [f"{k}: {v}" for k, v in evidence_paths.items()]
+    
+    provenance = verdict.get("provenance")
+    
+    return {
+        "verdict_summary": summary,
+        "blockers_section": blockers,
+        "provenance_note": provenance,
+        "evidence_paths_section": evidence_sections,
+        "next_actions": next_steps,
+    }