@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/genesis/orchestrator.py

@@ -0,0 +1,262 @@
+"""Genesis orchestrator — walks the state machine, writes the files,
+flips PROJECT.yaml after each phase.
+
+Why this lives in a separate file from ``state.py`` + ``phases.py``
+-------------------------------------------------------------------
+
+  * ``state.py`` is pure data + atomic IO (testable without phases).
+  * ``phases.py`` is pure content generation (testable without IO).
+  * ``orchestrator.py`` is the boring glue that sequences them with
+    proper error handling, resume semantics, and progress reporting.
+
+Resume semantics
+----------------
+
+Every call to :meth:`GenesisOrchestrator.run` reads PROJECT.yaml first,
+picks the next unfinished phase via :func:`GenesisState.next_phase`,
+runs it, persists the artifacts atomically, then flips the state. If
+any phase raises, the state is NOT flipped — re-running picks up at the
+same phase. This makes Genesis idempotent and crash-safe.
+"""
+from __future__ import annotations
+
+import os
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from omega_engine.genesis.state import (
+    GenesisState,
+    PHASES,
+    load_state,
+    project_root,
+    save_state,
+)
+from omega_engine.genesis import phases as _phases
+
+
+# Phase → callable mapping. Each callable returns a list[FileSpec].
+_PHASE_FUNCS: dict[str, Callable[[GenesisState], list[_phases.FileSpec]]] = {
+    # "stack" is handled separately because it needs operator answers,
+    # not deterministic content. The orchestrator calls into stack.pick_stack
+    # before this map is consulted.
+    "vision": _phases.phase_vision,
+    "market": _phases.phase_market,
+    "branding": _phases.phase_branding,
+    "prd": _phases.phase_prd,
+    "features": _phases.phase_features,
+    "plan": _phases.phase_plan,
+}
+
+
+# ---------------------------------------------------------------------------
+# Phase result
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PhaseResult:
+    phase: str
+    files_written: list[str] = field(default_factory=list)
+    elapsed_s: float = 0.0
+    skipped: bool = False           # phase was already done, we no-op'd
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return not self.error
+
+
+# ---------------------------------------------------------------------------
+# Atomic write helper — same pattern as state.py
+# ---------------------------------------------------------------------------
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(
+        path.suffix + f".tmp.{os.getpid()}.{threading.get_ident()}"
+    )
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(content)
+        fh.flush()
+        try:
+            os.fsync(fh.fileno())
+        except OSError:
+            pass
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class GenesisOrchestrator:
+    """Drives a Genesis pipeline for one project.
+
+    Construct with the slug + optional ``omega_home`` (defaults to
+    ``$OMEGA_HOME``). Then call :meth:`run` to advance one phase or
+    :meth:`run_all` to walk to completion.
+
+    The orchestrator is single-project — to drive multiple, create one
+    orchestrator per slug. Per-project isolation is enforced by the
+    :func:`project_root` resolver in ``state.py``.
+    """
+
+    slug: str
+    omega_home: str | Path | None = None
+
+    # ----- runtime helpers ------------------------------------------------
+
+    def _state(self) -> GenesisState:
+        return load_state(self.slug, omega_home=self.omega_home)
+
+    def _persist(self, state: GenesisState) -> None:
+        save_state(state, omega_home=self.omega_home)
+
+    def _root(self) -> Path:
+        return project_root(self.slug, omega_home=self.omega_home)
+
+    # ----- single-phase runner --------------------------------------------
+
+    def run(self, *, only: str | None = None) -> PhaseResult:
+        """Advance ONE phase.
+
+        ``only`` (optional) forces the orchestrator to run that specific
+        phase — even if it's already marked done. Useful for "regen the
+        PRD after I changed the vision".
+
+        Returns a :class:`PhaseResult`. On error, ``error`` is set and
+        the state is NOT flipped (the next call retries the same phase).
+        """
+        import time as _t
+        started = _t.time()
+        state = self._state()
+        phase = only or state.next_phase()
+        if phase is None:
+            return PhaseResult(phase="(complete)", elapsed_s=0.0, skipped=True)
+
+        # Sanity: phase must be one of the known phases
+        if phase not in PHASES:
+            return PhaseResult(
+                phase=phase, error=f"unknown phase {phase!r}",
+            )
+
+        # Stack phase is special — it has no doc output; it just records
+        # the operator's stack choice (already done at init_project time
+        # OR via `omega genesis stack`). We just mark it done.
+        if phase == "stack":
+            if not state.is_phase_done("stack"):
+                state.mark_phase_done("stack")
+                self._persist(state)
+            return PhaseResult(
+                phase="stack",
+                files_written=[],
+                elapsed_s=round(_t.time() - started, 3),
+                skipped=False,
+            )
+
+        fn = _PHASE_FUNCS.get(phase)
+        if fn is None:
+            return PhaseResult(
+                phase=phase, error=f"no generator for phase {phase!r}",
+            )
+
+        try:
+            specs = fn(state)
+        except Exception as exc:  # noqa: BLE001
+            return PhaseResult(
+                phase=phase, error=f"generator raised: {exc!r}",
+                elapsed_s=round(_t.time() - started, 3),
+            )
+
+        root = self._root()
+        written: list[str] = []
+        for spec in specs:
+            dest = root / spec.rel_path
+            try:
+                _atomic_write(dest, spec.content)
+            except OSError as exc:
+                return PhaseResult(
+                    phase=phase,
+                    error=f"failed to write {dest}: {exc}",
+                    files_written=written,
+                    elapsed_s=round(_t.time() - started, 3),
+                )
+            written.append(spec.rel_path)
+
+        # Flip state ATOMICALLY only after every file was written.
+        state.mark_phase_done(phase)
+        self._persist(state)
+
+        return PhaseResult(
+            phase=phase,
+            files_written=written,
+            elapsed_s=round(_t.time() - started, 3),
+            skipped=False,
+        )
+
+    # ----- multi-phase runner ---------------------------------------------
+
+    def run_all(
+        self,
+        *,
+        max_phases: int | None = None,
+        stop_at: str | None = None,
+    ) -> list[PhaseResult]:
+        """Walk forward through every undone phase.
+
+        ``max_phases`` caps the loop (useful for tests). ``stop_at`` stops
+        AFTER finishing the named phase (e.g. "branding" to halt before
+        PRD generation).
+        """
+        out: list[PhaseResult] = []
+        steps = 0
+        while True:
+            res = self.run()
+            if res.skipped and res.phase == "(complete)":
+                break
+            out.append(res)
+            if not res.ok:
+                break
+            steps += 1
+            if max_phases is not None and steps >= max_phases:
+                break
+            if stop_at and res.phase == stop_at:
+                break
+        return out
+
+    # ----- read-only helpers ----------------------------------------------
+
+    def status(self) -> dict[str, Any]:
+        """Snapshot of where this project is in the pipeline."""
+        try:
+            state = self._state()
+        except FileNotFoundError:
+            return {
+                "slug": self.slug,
+                "exists": False,
+                "phase": None,
+                "completed_phases": [],
+                "remaining_phases": list(PHASES),
+            }
+        return {
+            "slug": state.slug,
+            "name": state.name,
+            "exists": True,
+            "intent": state.intent,
+            "phase": state.phase,
+            "completed_phases": state.completed_phases,
+            "remaining_phases": [
+                p for p in PHASES if p not in state.completed_phases
+            ],
+            "stack": state.stack.to_dict(),
+            "repo": state.repo.to_dict(),
+            "created_at": state.created_at,
+            "updated_at": state.updated_at,
+            "root": str(self._root()),
+        }