@agentikos/omega-os 0.2.0 → 0.19.5

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

@@ -0,0 +1,324 @@
+"""Stack picker — the first phase of Genesis.
+
+The picker is a deterministic decision tree that turns a project type
+(``web`` / ``mobile`` / ``desktop`` / …) into a concrete :class:`StackConfig`.
+For ambiguous cases (mixed web+mobile, custom backend, exotic UI kit) the
+picker emits a list of :class:`StackQuestion` items that the orchestrator
+forwards to the operator via:
+
+  * the CLI (interactive prompt, `omega genesis new ...` without --brief)
+  * the Claude Code skill (`AskUserQuestion`)
+  * the Telegram bot (inline keyboard)
+
+Defaults
+--------
+
+The OmegaOS canonical stack is::
+
+  type=web  frontend=nextjs  backend=convex  deploy=vercel
+  payments=stripe  ui_kit=shadcn  auth=clerk
+
+It's what we know works end-to-end with the rest of the OS (audits,
+worker briefs, deploy pipeline). Any deviation should be a CONSCIOUS
+choice — the picker surfaces the alternatives explicitly.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from omega_engine.genesis.state import StackConfig
+
+
+# ---------------------------------------------------------------------------
+# Question abstraction
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StackQuestion:
+    """One operator decision the picker needs to advance.
+
+    ``key`` is the field on StackConfig to set; ``header`` is the short
+    label shown in UI (CLI / Telegram); ``options`` are the *allowed*
+    answers — the picker rejects anything else.
+
+    The ``recommended`` value is the default the orchestrator picks when
+    the operator skips the question (``--accept-defaults`` flag, or no
+    Telegram reply within the patience window).
+    """
+
+    key: str                              # StackConfig field
+    header: str                           # short label
+    question: str                         # full question text
+    options: list[str]                    # allowed answers
+    recommended: str                      # default if skipped
+    why: str = ""                         # 1-line rationale for the operator
+
+
+# ---------------------------------------------------------------------------
+# Stack pre-sets (named bundles)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Stack:
+    """A named bundle of StackConfig fields + a one-line rationale.
+
+    The orchestrator stores stacks under this name in ``PROJECT.yaml``
+    so future operators can read the deliberate choice ("we picked
+    omegaos-canonical because we wanted shadcn + convex + stripe out of
+    the box").
+    """
+
+    id: str
+    title: str
+    config: StackConfig
+    why: str
+
+
+def default_stack() -> Stack:
+    """The OmegaOS canonical stack — Next.js + Convex + Vercel + Stripe + shadcn."""
+    return Stack(
+        id="omegaos-canonical",
+        title="OmegaOS canonical (Next.js + Convex + Vercel + Stripe + shadcn + Clerk)",
+        config=StackConfig(
+            type="web",
+            frontend="nextjs",
+            backend="convex",
+            deploy="vercel",
+            payments="stripe",
+            ui_kit="shadcn",
+            auth="clerk",
+            extras=["framer-motion"],
+        ),
+        why="The stack the engine knows end-to-end. Audits, deploy, "
+            "/prod pipeline, and the design-discipline skills all assume "
+            "this shape.",
+    )
+
+
+def _mobile_native_stack() -> Stack:
+    return Stack(
+        id="omegaos-mobile-native",
+        title="iOS native (SwiftUI + Convex + Stripe Connect)",
+        config=StackConfig(
+            type="iphone",
+            frontend="swiftui",
+            backend="convex",
+            deploy="none",
+            payments="stripe",
+            ui_kit="custom",
+            auth="clerk",
+            mobile="swiftui",
+            extras=[],
+        ),
+        why="When the brief says 'iPhone app, native feel, app store'. "
+            "Convex still works as the backend; UI is pure SwiftUI.",
+    )
+
+
+def _mobile_cross_stack() -> Stack:
+    return Stack(
+        id="omegaos-mobile-expo",
+        title="Cross-platform mobile (Expo + Convex + Stripe + NativeWind)",
+        config=StackConfig(
+            type="mobile",
+            frontend="expo",
+            backend="convex",
+            deploy="eas",
+            payments="stripe",
+            ui_kit="shadcn",     # via react-native-reusables
+            auth="clerk",
+            mobile="expo",
+            extras=["nativewind", "react-native-reanimated"],
+        ),
+        why="iOS + Android in one codebase. Convex SDK has first-class "
+            "Expo support; clerk-expo handles auth.",
+    )
+
+
+def _desktop_tauri_stack() -> Stack:
+    return Stack(
+        id="omegaos-desktop-tauri",
+        title="Desktop (Tauri + Next.js renderer + Convex)",
+        config=StackConfig(
+            type="desktop",
+            frontend="nextjs",
+            backend="convex",
+            deploy="self-hosted",
+            payments="stripe",
+            ui_kit="shadcn",
+            auth="clerk",
+            desktop="tauri",
+            extras=["framer-motion"],
+        ),
+        why="Native binary, web tech inside. Smaller than Electron, "
+            "ships to mac/win/linux from one codebase.",
+    )
+
+
+def _backend_supabase_stack() -> Stack:
+    return Stack(
+        id="omegaos-supabase",
+        title="Supabase variant (Next.js + Supabase + Vercel + Stripe + shadcn)",
+        config=StackConfig(
+            type="web",
+            frontend="nextjs",
+            backend="supabase",
+            deploy="vercel",
+            payments="stripe",
+            ui_kit="shadcn",
+            auth="supabase-auth",
+        ),
+        why="When the operator explicitly wants Supabase (existing data, "
+            "PostgreSQL needs, RLS). Pay attention: Supabase auth, not Clerk.",
+    )
+
+
+CANONICAL_STACKS: dict[str, Stack] = {
+    s.id: s for s in (
+        default_stack(),
+        _mobile_native_stack(),
+        _mobile_cross_stack(),
+        _desktop_tauri_stack(),
+        _backend_supabase_stack(),
+    )
+}
+
+
+# ---------------------------------------------------------------------------
+# Question generator
+# ---------------------------------------------------------------------------
+
+
+def stack_questions(intent: str = "") -> list[StackQuestion]:
+    """The minimal question list the picker needs to settle the stack.
+
+    Five questions, each with a recommended default — operator can hit
+    Enter on each to accept the OmegaOS canonical stack.
+    """
+    return [
+        StackQuestion(
+            key="type",
+            header="Target",
+            question="What's the project's target surface?",
+            options=["web", "mobile", "desktop", "iphone", "mac", "cli", "library", "mixed"],
+            recommended="web",
+            why="Web is the default; switch only when the brief calls for native.",
+        ),
+        StackQuestion(
+            key="backend",
+            header="Backend",
+            question="Which backend?",
+            options=["convex", "supabase", "postgres+drizzle", "trpc+prisma", "firebase", "none"],
+            recommended="convex",
+            why="Convex is the OmegaOS canonical — real-time, typed, hosted, fits the agent loop.",
+        ),
+        StackQuestion(
+            key="frontend",
+            header="Frontend",
+            question="Which frontend framework?",
+            options=["nextjs", "astro", "remix", "vite-react", "expo", "tauri", "electron", "swiftui"],
+            recommended="nextjs",
+            why="Next.js + App Router is the stack the engine deploys cleanly via /prod.",
+        ),
+        StackQuestion(
+            key="auth",
+            header="Auth",
+            question="Auth provider?",
+            options=["clerk", "better-auth", "next-auth", "supabase-auth", "custom"],
+            recommended="clerk",
+            why="Clerk: organisations, MFA, OAuth, magic links — out of the box.",
+        ),
+        StackQuestion(
+            key="payments",
+            header="Payments",
+            question="Payments provider?",
+            options=["stripe", "lemonsqueezy", "paddle", "none"],
+            recommended="stripe",
+            why="Stripe Connect is the engine's tested integration.",
+        ),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# The picker
+# ---------------------------------------------------------------------------
+
+
+def pick_stack(
+    *,
+    answers: dict[str, str] | None = None,
+    intent: str = "",
+    accept_defaults: bool = False,
+) -> StackConfig:
+    """Apply ``answers`` (key → value) on top of the canonical stack.
+
+    Rules:
+      * Every key in ``answers`` MUST appear in the question list and the
+        value MUST be in that question's ``options``. Otherwise we raise.
+      * Missing keys fall back to the recommended default.
+      * When ``accept_defaults=True``, ``answers`` is ignored entirely
+        and the canonical stack is returned.
+
+    Coupled inference (after the operator's answers are applied):
+      * type=iphone → mobile=swiftui, deploy=none, ui_kit=custom
+      * type=mobile + frontend=expo → mobile=expo, deploy=eas, ui_kit=shadcn
+      * type=desktop + frontend in (electron|tauri) → desktop=<that>
+      * backend=supabase → auth=supabase-auth (unless overridden)
+    """
+    if accept_defaults:
+        return default_stack().config
+
+    answers = answers or {}
+    qs = {q.key: q for q in stack_questions(intent)}
+    cfg = default_stack().config
+
+    for key, val in answers.items():
+        if key not in qs:
+            raise ValueError(
+                f"unknown stack question key: {key!r} "
+                f"(allowed: {sorted(qs.keys())})"
+            )
+        if val not in qs[key].options:
+            raise ValueError(
+                f"invalid value {val!r} for key {key!r} "
+                f"(allowed: {qs[key].options})"
+            )
+        setattr(cfg, key, val)
+
+    # Coupled inferences — keep config internally consistent.
+    if cfg.type == "iphone":
+        cfg.mobile = "swiftui"
+        cfg.deploy = "none"
+        if "ui_kit" not in answers:
+            cfg.ui_kit = "custom"
+    elif cfg.type == "mac":
+        cfg.desktop = "swiftui"
+        cfg.deploy = "none"
+        if "ui_kit" not in answers:
+            cfg.ui_kit = "custom"
+    elif cfg.type == "mobile":
+        if cfg.frontend in ("expo", "react-native"):
+            cfg.mobile = cfg.frontend
+            cfg.deploy = "eas"
+    elif cfg.type == "desktop":
+        if cfg.frontend in ("electron", "tauri"):
+            cfg.desktop = cfg.frontend
+
+    # Auth coupling: supabase backend ⇒ default auth=supabase-auth unless
+    # the operator explicitly picked something else.
+    if cfg.backend == "supabase" and "auth" not in answers:
+        cfg.auth = "supabase-auth"
+
+    # Strip impossible combinations.
+    if cfg.type == "library" or cfg.type == "cli":
+        cfg.deploy = "none"
+        cfg.payments = "none"
+        cfg.auth = "custom"
+        cfg.ui_kit = "tailwind-only"
+        cfg.mobile = None
+        cfg.desktop = None
+
+    return cfg

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

@@ -0,0 +1,353 @@
+"""Genesis state machine + project root resolver.
+
+PROJECT.yaml schema (one file per project, source of truth)
+-----------------------------------------------------------
+
+::
+
+    slug: my-saas
+    name: My SaaS
+    created_at: 2026-05-25T14:00:00Z
+    updated_at: 2026-05-25T14:30:00Z
+    intent: "AI-powered email warmup for B2B teams"
+    phase: market        # one of PHASES
+    completed_phases:
+      - stack
+      - vision
+    stack:
+      type: web          # web | mobile | desktop | cli | library | mac | iphone
+      frontend: nextjs
+      backend: convex
+      deploy: vercel
+      payments: stripe
+      ui_kit: shadcn
+      auth: clerk
+      mobile: null
+      desktop: null
+      extras: [framer-motion, react-flow]
+    repo:
+      provider: github
+      visibility: private
+      url: null          # set after `omega genesis repo`
+    notes: |
+      Any operator notes that the orchestrator should remember.
+
+The orchestrator reads this file BEFORE every phase and writes it
+ATOMICALLY after. Resume = re-read + skip completed_phases.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import threading
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+# Ordered phase list — used by the orchestrator to walk forward and by the
+# state machine to validate transitions. Adding a new phase here is the
+# only place that needs to know about it.
+PHASES: tuple[str, ...] = (
+    "stack",        # pick the technical + programmatic stack
+    "vision",       # one-page product identity
+    "market",       # 5 research files
+    "branding",     # 3 brand files
+    "prd",          # 9 PRD files
+    "features",     # N feature files with depends_on
+    "plan",         # hand off to omega plan build
+)
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StackConfig:
+    """The technical + deployment stack the project is built on.
+
+    All fields default to the OmegaOS preferred stack (Next.js + Convex +
+    Vercel + Stripe + shadcn + Clerk). Operators can pivot any field via
+    the stack picker; `extras` is the escape hatch for libraries that
+    fall outside the canonical 5-tuple (framer-motion, react-flow,
+    three.js, gsap, …).
+    """
+
+    type: str = "web"                # web | mobile | desktop | cli | library | mac | iphone | mixed
+    frontend: str = "nextjs"         # nextjs | astro | remix | vite-react | expo | tauri | electron | swiftui | …
+    backend: str = "convex"          # convex | supabase | postgres+drizzle | trpc+prisma | firebase | none
+    deploy: str = "vercel"           # vercel | cloudflare | fly | render | self-hosted | aws-amplify | none
+    payments: str = "stripe"         # stripe | lemonsqueezy | paddle | none
+    ui_kit: str = "shadcn"           # shadcn | radix | mantine | mui | tailwind-only | custom
+    auth: str = "clerk"              # clerk | better-auth | next-auth | supabase-auth | custom
+    mobile: str | None = None        # null | expo | react-native | swiftui | flutter
+    desktop: str | None = None       # null | tauri | electron | wails
+    extras: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "StackConfig":
+        # tolerant — fill missing fields with defaults
+        kept = {k: v for k, v in d.items() if k in StackConfig().__dict__}
+        return StackConfig(**kept)
+
+
+@dataclass
+class RepoConfig:
+    provider: str = "github"          # github | gitlab | none
+    visibility: str = "private"       # private | public
+    url: str | None = None            # set after `omega genesis repo`
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "RepoConfig":
+        kept = {k: v for k, v in d.items() if k in RepoConfig().__dict__}
+        return RepoConfig(**kept)
+
+
+@dataclass
+class GenesisState:
+    """The source of truth for a project's genesis pipeline."""
+
+    slug: str
+    name: str
+    intent: str
+    created_at: str
+    updated_at: str
+    phase: str = "stack"                                  # current phase
+    completed_phases: list[str] = field(default_factory=list)
+    stack: StackConfig = field(default_factory=StackConfig)
+    repo: RepoConfig = field(default_factory=RepoConfig)
+    notes: str = ""
+
+    def is_phase_done(self, phase: str) -> bool:
+        return phase in self.completed_phases
+
+    def next_phase(self) -> str | None:
+        """The next phase to run, or None when the pipeline is finished."""
+        for ph in PHASES:
+            if not self.is_phase_done(ph):
+                return ph
+        return None
+
+    def mark_phase_done(self, phase: str) -> None:
+        if phase not in PHASES:
+            raise ValueError(f"unknown phase: {phase!r}")
+        if phase not in self.completed_phases:
+            self.completed_phases.append(phase)
+        # phase pointer advances to the next undone phase, or stays at
+        # the last one if everything is done
+        nxt = self.next_phase()
+        self.phase = nxt or PHASES[-1]
+        self.updated_at = _now_iso()
+
+    # ---- YAML / JSON serialisation -----------------------------------
+
+    def to_yaml(self) -> str:
+        try:
+            import yaml
+        except ImportError:
+            # Fallback to JSON when PyYAML isn't installed. The file will
+            # still be readable by load_state via the same fallback.
+            return json.dumps(self.to_dict(), indent=2)
+        return yaml.safe_dump(self.to_dict(), sort_keys=False, allow_unicode=True)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["stack"] = self.stack.to_dict()
+        d["repo"] = self.repo.to_dict()
+        return d
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "GenesisState":
+        stack = StackConfig.from_dict(d.get("stack") or {})
+        repo = RepoConfig.from_dict(d.get("repo") or {})
+        return GenesisState(
+            slug=str(d["slug"]),
+            name=str(d.get("name", d["slug"])),
+            intent=str(d.get("intent", "")),
+            created_at=str(d.get("created_at", _now_iso())),
+            updated_at=str(d.get("updated_at", _now_iso())),
+            phase=str(d.get("phase", "stack")),
+            completed_phases=list(d.get("completed_phases") or []),
+            stack=stack,
+            repo=repo,
+            notes=str(d.get("notes", "")),
+        )
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# ---------------------------------------------------------------------------
+# Path resolver — STRICT per-project isolation
+# ---------------------------------------------------------------------------
+
+
+def _omega_home(explicit: str | Path | None) -> Path:
+    if explicit is not None:
+        return Path(explicit)
+    return Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+
+
+def project_root(slug: str, omega_home: str | Path | None = None) -> Path:
+    """The single, canonical root for a project's genesis tree.
+
+    Every helper in this package MUST go through this function — no
+    ambient CWD heuristics, no "find the closest .git". One slug → one
+    path, always.
+    """
+    if not slug or not slug.replace("-", "").replace("_", "").isalnum():
+        raise ValueError(
+            f"invalid project slug {slug!r} — must match [A-Za-z0-9_-]+"
+        )
+    return _omega_home(omega_home) / "Agentik_Coding" / "projects" / slug
+
+
+def state_path(slug: str, omega_home: str | Path | None = None) -> Path:
+    return project_root(slug, omega_home) / "PROJECT.yaml"
+
+
+# ---------------------------------------------------------------------------
+# Atomic read / write
+# ---------------------------------------------------------------------------
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    """Same temp+fsync+rename pattern as done_signal — never partial writes."""
+    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)
+
+
+def save_state(state: GenesisState, omega_home: str | Path | None = None) -> Path:
+    """Atomically persist PROJECT.yaml. Returns the absolute path."""
+    p = state_path(state.slug, omega_home)
+    _atomic_write(p, state.to_yaml())
+    return p
+
+
+def load_state(
+    slug: str, omega_home: str | Path | None = None,
+) -> GenesisState:
+    """Read PROJECT.yaml. Raises FileNotFoundError if it doesn't exist.
+
+    Supports both YAML and JSON payloads — write_state always emits the
+    most expressive format available (YAML if PyYAML, JSON otherwise).
+    """
+    p = state_path(slug, omega_home)
+    if not p.exists():
+        raise FileNotFoundError(
+            f"no genesis state at {p} — run `omega genesis new {slug}` first"
+        )
+    raw = p.read_text()
+    try:
+        import yaml
+        data = yaml.safe_load(raw) or {}
+    except ImportError:
+        data = json.loads(raw)
+    return GenesisState.from_dict(data)
+
+
+# ---------------------------------------------------------------------------
+# Init
+# ---------------------------------------------------------------------------
+
+
+def init_project(
+    slug: str,
+    *,
+    name: str | None = None,
+    intent: str = "",
+    stack: StackConfig | None = None,
+    omega_home: str | Path | None = None,
+    force: bool = False,
+) -> GenesisState:
+    """Create the project skeleton on disk + write the initial PROJECT.yaml.
+
+    Folder shape created on disk:
+      <root>/
+        PROJECT.yaml
+        docs/
+          10-market/
+          20-brand/
+          30-prd/
+          40-features/
+        plan/
+
+    Idempotent: a re-call WITHOUT ``force`` raises if PROJECT.yaml already
+    exists. With ``force=True``, the existing state is OVERWRITTEN (the
+    docs/ tree is left intact — destructive deletes are never automatic).
+    """
+    root = project_root(slug, omega_home)
+    if state_path(slug, omega_home).exists() and not force:
+        raise FileExistsError(
+            f"PROJECT.yaml already exists at {root} — "
+            f"use `omega genesis resume {slug}` to continue, "
+            f"or pass --force to re-init"
+        )
+
+    # Create the canonical sub-tree. ``mkdir parents=True exist_ok=True`` is
+    # idempotent so re-running on an existing tree is safe.
+    for sub in (
+        "docs/10-market",
+        "docs/20-brand",
+        "docs/30-prd",
+        "docs/40-features",
+        "plan",
+    ):
+        (root / sub).mkdir(parents=True, exist_ok=True)
+
+    now = _now_iso()
+    state = GenesisState(
+        slug=slug,
+        name=name or slug,
+        intent=intent,
+        created_at=now,
+        updated_at=now,
+        phase="stack",
+        completed_phases=[],
+        stack=stack or StackConfig(),
+        repo=RepoConfig(),
+    )
+    save_state(state, omega_home=omega_home)
+    return state
+
+
+def delete_project(slug: str, omega_home: str | Path | None = None) -> bool:
+    """Best-effort destroy a project tree. Returns True if anything was
+    deleted. Refuses if the path escapes the canonical
+    Agentik_Coding/projects/ root."""
+    root = project_root(slug, omega_home)
+    if not root.exists():
+        return False
+    # Defence in depth — make sure we don't shutil.rmtree something
+    # unexpected (a symlink, an ambient relative path, …).
+    home = _omega_home(omega_home)
+    canon = (home / "Agentik_Coding" / "projects").resolve()
+    if not str(root.resolve()).startswith(str(canon)):
+        raise RuntimeError(
+            f"refusing to delete {root} — outside canonical projects/ root"
+        )
+    shutil.rmtree(root, ignore_errors=True)
+    return True