devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/cli/cro.py

@@ -0,0 +1,298 @@
+"""`devrel cro ...`: CRO auditor verbs (Cyra)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sqlite3
+from datetime import date, timedelta
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devrel_origin.cli._common import find_paths_or_exit
+from devrel_origin.core.cyra import Cyra
+from devrel_origin.core.llm import LLMClient
+from devrel_origin.tools.api_client import PostHogClient
+
+cro_app = typer.Typer(
+    name="cro",
+    help="CRO auditor (Cyra). Funnel drop-offs + LLM-generated A/B hypotheses.",
+    no_args_is_help=True,
+)
+
+_console = Console()
+
+
+def _build_cyra(db_path: Path) -> Cyra:
+    """Construct Cyra with clients from environment variables. Patched in unit tests."""
+    posthog = PostHogClient(
+        api_key=os.environ.get("POSTHOG_API_KEY", ""),
+        project_id=os.environ.get("POSTHOG_PROJECT_ID", ""),
+    )
+    llm = LLMClient(api_key=os.environ.get("ANTHROPIC_API_KEY", ""))
+    llm.set_agent("cyra")
+    return Cyra(
+        posthog_client=posthog,
+        llm_client=llm,
+        db_path=db_path,
+    )
+
+
+@cro_app.command("report")
+def report(
+    since: str = typer.Option("7d", "--since", help="Window: 7d, 30d, 90d"),
+    push: bool = typer.Option(False, "--push", help="Email/Telegram the report"),
+    format: str = typer.Option("markdown", "--format", help="markdown|json"),
+) -> None:
+    """Run a Cyra cycle and persist Recommendation rows + Mox briefs."""
+    paths = find_paths_or_exit(_console)
+    _days = int(since.rstrip("d"))
+    period_end = date.today().isoformat()
+
+    # Insert an analytics_reports row to anchor the FK from analytics_recommendations.
+    # The CLI is the report producer here; Cyra emits recommendation rows attached
+    # to this report_id.
+    db_path = paths.state_db
+    period_start = (date.today() - timedelta(days=_days)).isoformat()
+    with sqlite3.connect(db_path) as conn:
+        cur = conn.execute(
+            "INSERT INTO analytics_reports (period_start, period_end, report_json) "
+            "VALUES (?, ?, ?)",
+            (period_start, period_end, "{}"),
+        )
+        report_id = cur.lastrowid
+        conn.commit()
+
+    cyra = _build_cyra(db_path)
+
+    async def _run():
+        return await cyra.execute(
+            period_end=period_end,
+            report_id=report_id,
+            page_html_by_url={},
+            iris_themes=[],
+            sage_friction=[],
+            deliverables_dir=paths.deliverables_dir,
+        )
+
+    result = asyncio.run(_run())
+
+    if format == "json":
+        _console.print(
+            json.dumps(
+                {
+                    "period_end": result.period_end,
+                    "funnel_id": result.funnel_id,
+                    "dropoffs": [
+                        {
+                            "from_step": d.from_step,
+                            "to_step": d.to_step,
+                            "conversion_rate": d.conversion_rate,
+                            "pp_delta_vs_prior": d.pp_delta_vs_prior,
+                            "sample_size": d.sample_size,
+                        }
+                        for d in result.dropoffs
+                    ],
+                    "recommendations": [
+                        {
+                            "action": r.action,
+                            "target": r.target,
+                            "confidence": r.confidence,
+                            "source_ids": r.source_ids,
+                        }
+                        for r in result.recommendations
+                    ],
+                },
+                indent=2,
+                default=str,
+            )
+        )
+        return
+
+    # Markdown table via Rich
+    table = Table(title=f"Cyra report: {period_end}")
+    table.add_column("From -> To", style="cyan")
+    table.add_column("Conv", justify="right")
+    table.add_column("WoW Delta", justify="right")
+    table.add_column("Sample", justify="right")
+    for d in result.dropoffs:
+        table.add_row(
+            f"{d.from_step} -> {d.to_step}",
+            f"{d.conversion_rate:.1%}",
+            f"{d.pp_delta_vs_prior:+.1%}",
+            f"{d.sample_size:,}",
+        )
+    _console.print(table)
+    _console.print(f"[green]Wrote {len(result.recommendations)} recommendation(s).[/green]")
+    if push:
+        _console.print("[yellow]--push not yet implemented for cro; printed-only.[/yellow]")
+
+
+@cro_app.command("history")
+def history(
+    funnel_step: str = typer.Argument(..., help="Funnel step name to track"),
+    limit: int = typer.Option(20, "--limit"),
+) -> None:
+    """Show conversion-rate trajectory for a funnel step across reports."""
+    paths = find_paths_or_exit(_console)
+    db_path = paths.devrel_dir / "state.db"
+    if not db_path.is_file():
+        _console.print("[yellow]No state.db yet, run `devrel cro report` first.[/yellow]")
+        raise typer.Exit(code=0)
+
+    table = Table(title=f"History: {funnel_step}")
+    table.add_column("Period", style="cyan")
+    table.add_column("Conv", justify="right")
+    table.add_column("Sample", justify="right")
+
+    with sqlite3.connect(db_path) as conn:
+        cur = conn.execute(
+            """
+            SELECT period_end, conversion_rate, sample_size
+            FROM cro_funnel_metrics
+            WHERE step_index = (
+                SELECT MIN(step_index) FROM cro_funnel_metrics
+                WHERE funnel_id IN (SELECT DISTINCT funnel_id FROM cro_funnel_metrics)
+            )
+            ORDER BY period_end DESC
+            LIMIT ?
+            """,
+            (limit,),
+        )
+        for period_end, conv, sample in cur:
+            table.add_row(period_end, f"{(conv or 0):.1%}", f"{(sample or 0):,}")
+
+    _console.print(table)
+
+
+@cro_app.command("diff")
+def diff(
+    period_a: str = typer.Argument(..., help="Earlier ISO period"),
+    period_b: str = typer.Argument(..., help="Later ISO period"),
+) -> None:
+    """Per-step conversion delta between two CRO reports."""
+    paths = find_paths_or_exit(_console)
+    db_path = paths.devrel_dir / "state.db"
+    if not db_path.is_file():
+        _console.print("[yellow]No state.db yet.[/yellow]")
+        raise typer.Exit(code=0)
+
+    table = Table(title=f"CRO diff: {period_a} -> {period_b}")
+    table.add_column("Funnel", style="cyan")
+    table.add_column("Step", justify="right")
+    table.add_column(f"{period_a}", justify="right")
+    table.add_column(f"{period_b}", justify="right")
+    table.add_column("Delta pp", justify="right")
+
+    with sqlite3.connect(db_path) as conn:
+        cur = conn.execute(
+            """
+            SELECT a.funnel_id, a.step_index, a.conversion_rate, b.conversion_rate
+            FROM cro_funnel_metrics a
+            JOIN cro_funnel_metrics b
+              ON a.funnel_id = b.funnel_id AND a.step_index = b.step_index
+            WHERE a.period_end = ? AND b.period_end = ?
+            ORDER BY a.funnel_id, a.step_index
+            """,
+            (period_a, period_b),
+        )
+        for funnel_id, step_index, conv_a, conv_b in cur:
+            delta = (conv_b or 0) - (conv_a or 0)
+            table.add_row(
+                funnel_id,
+                str(step_index),
+                f"{(conv_a or 0):.1%}",
+                f"{(conv_b or 0):.1%}",
+                f"{delta:+.1%}",
+            )
+
+    _console.print(table)
+
+
+@cro_app.command("calibration")
+def calibration() -> None:
+    """Score historical CRO recommendations against subsequent funnel data."""
+    paths = find_paths_or_exit(_console)
+    db_path = paths.devrel_dir / "state.db"
+    if not db_path.is_file():
+        _console.print("[yellow]No state.db yet.[/yellow]")
+        raise typer.Exit(code=0)
+
+    from devrel_origin.core.growth.recommendations import calibrate
+    from devrel_origin.core.growth.target_kinds import Pillar
+
+    def _score_outcome(rec) -> str:
+        """Did conversion improve at this funnel step after the rec was applied?"""
+        if rec.applied_at is None:
+            return "unchanged"
+        with sqlite3.connect(db_path) as conn:
+            cur = conn.execute(
+                """
+                SELECT conversion_rate FROM cro_funnel_metrics
+                WHERE funnel_id IN (SELECT DISTINCT funnel_id FROM cro_funnel_metrics)
+                  AND period_end >= ?
+                ORDER BY period_end ASC LIMIT 2
+                """,
+                (rec.applied_at[:10],),
+            )
+            rates = [row[0] for row in cur.fetchall()]
+        if len(rates) < 2:
+            return "unchanged"
+        return (
+            "improved"
+            if rates[1] > rates[0]
+            else ("regressed" if rates[1] < rates[0] else "unchanged")
+        )
+
+    result = calibrate(db_path, Pillar.CRO, outcome_scorer=_score_outcome)
+
+    if not result:
+        _console.print("[yellow]No applied CRO recommendations yet.[/yellow]")
+        return
+
+    table = Table(title="CRO calibration")
+    table.add_column("Action", style="cyan")
+    table.add_column("Applied", justify="right")
+    table.add_column("Hit rate", justify="right")
+    table.add_column("Lift vs coinflip", justify="right")
+    for action, stats in result.items():
+        table.add_row(
+            action,
+            str(stats["applied_count"]),
+            f"{stats['hit_rate']:.1%}",
+            f"{stats['lift_vs_coinflip']:+.1%}",
+        )
+    _console.print(table)
+
+
+@cro_app.command("funnel")
+def funnel(
+    show_detected: bool = typer.Option(
+        False, "--show-detected", help="Show what auto-detect picked"
+    ),
+    days: int = typer.Option(7, "--days"),
+) -> None:
+    """Inspect the current (auto-detected or configured) CRO funnel."""
+    paths = find_paths_or_exit(_console)
+    cyra = _build_cyra(paths.devrel_dir / "state.db")
+
+    async def _run():
+        return await cyra._autodetect_funnel(days=days)
+
+    funnel_events = asyncio.run(_run())
+
+    table = Table(title=f"Cyra funnel (auto-detected, {days}d)")
+    table.add_column("#", justify="right")
+    table.add_column("Event", style="cyan")
+    for i, ev in enumerate(funnel_events):
+        table.add_row(str(i), ev)
+
+    _console.print(table)
+    if show_detected:
+        _console.print(
+            "[dim]Override via `[growth].cro_funnel = [...]` in .devrel/config.toml[/dim]"
+        )

devrel_origin/cli/deliverables.py

@@ -0,0 +1,65 @@
+"""`devrel deliverables {list, show}` — browse generated artifacts.
+
+Lists / cats files under .devrel/deliverables/ — the canonical output
+directory used by `devrel content draft|audit` and the agent pipeline.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from devrel_origin.cli._common import find_paths_or_exit
+
+console = Console()
+
+deliverables_app = typer.Typer(
+    name="deliverables",
+    help="List and inspect generated content/artifacts under .devrel/deliverables/.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@deliverables_app.command("list")
+def list_files() -> None:
+    """List all deliverable files (newest first)."""
+    paths = find_paths_or_exit(console)
+    if not paths.deliverables_dir.exists():
+        console.print("[yellow]No deliverables directory yet.[/yellow]")
+        return
+    files = sorted(
+        paths.deliverables_dir.rglob("*"),
+        key=lambda p: p.stat().st_mtime if p.is_file() else 0,
+        reverse=True,
+    )
+    files = [p for p in files if p.is_file()]
+    if not files:
+        console.print("[yellow]No deliverables yet.[/yellow]")
+        return
+    for p in files:
+        rel = p.relative_to(paths.deliverables_dir)
+        size = p.stat().st_size
+        console.print(f"  [dim]{size:>7d}[/dim]  {rel}")
+    console.print(f"\n[green]{len(files)} file(s)[/green]")
+
+
+@deliverables_app.command("show")
+def show(
+    name: str = typer.Argument(..., help="Filename (or substring) to display."),
+) -> None:
+    """Print the contents of a deliverable file (substring match on name)."""
+    paths = find_paths_or_exit(console)
+    if not paths.deliverables_dir.exists():
+        console.print("[yellow]No deliverables directory yet.[/yellow]")
+        raise typer.Exit(code=1)
+    matches = [p for p in paths.deliverables_dir.rglob("*") if p.is_file() and name in p.name]
+    if not matches:
+        console.print(f"[red]No deliverable matching '{name}'[/red]")
+        raise typer.Exit(code=1)
+    if len(matches) > 1:
+        console.print(f"[yellow]Multiple matches for '{name}':[/yellow]")
+        for p in matches:
+            console.print(f"  {p.relative_to(paths.deliverables_dir)}")
+        raise typer.Exit(code=1)
+    typer.echo(matches[0].read_text())

devrel_origin/cli/docs.py

@@ -0,0 +1,91 @@
+"""`devrel docs build` - AST-based docs via Dex."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from devrel_origin.cli._common import build_atlas_or_exit, find_paths_or_exit, render_result
+
+console = Console()
+
+docs_app = typer.Typer(
+    name="docs",
+    help="Documentation generation.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _persist_dex_output(output: dict[str, Any], deliverables_dir: Path) -> list[Path]:
+    """Write Dex's architecture / API / summary / modules outputs to disk.
+
+    Returns the list of files actually written (skips empty values). Used by
+    `devrel docs build` so users don't have to invoke with --json and split
+    the JSON blob themselves; Dex's architecture_doc is ~36KB and api_reference
+    is ~270KB on a real codebase, both unreadable through the truncated render.
+    """
+    deliverables_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+
+    def _write_text(name: str, value: Any) -> None:
+        if not value or not isinstance(value, str):
+            return
+        path = deliverables_dir / name
+        path.write_text(value)
+        written.append(path)
+
+    _write_text("dex-architecture.md", output.get("architecture_doc"))
+    _write_text("dex-api-reference.md", output.get("api_reference"))
+    _write_text("dex-summary.md", output.get("llm_summary"))
+
+    # Modules + languages travel as structured data, so persist as JSON for
+    # downstream tooling. Skip if absent or empty.
+    modules = output.get("modules")
+    if modules:
+        manifest = {
+            "languages": output.get("languages", {}),
+            "modules": modules,
+            "status": output.get("status", "generated"),
+        }
+        path = deliverables_dir / "dex-modules.json"
+        path.write_text(json.dumps(manifest, indent=2, default=str))
+        written.append(path)
+
+    return written
+
+
+@docs_app.command("build")
+def build(
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Build architecture docs + API reference from source via Dex.
+
+    Successful runs persist architecture_doc / api_reference / llm_summary
+    to .devrel/deliverables/dex-*.md so users don't have to pipe --json and
+    split the blob manually.
+    """
+    paths = find_paths_or_exit(console)
+    atlas = build_atlas_or_exit(paths, console)
+
+    async def _do() -> None:
+        result = await atlas.run_single_task("dex", "Build architecture docs and API reference")
+        if result.success and isinstance(result.output, dict):
+            written = _persist_dex_output(result.output, paths.deliverables_dir)
+            if written and not json_output:
+                console.print(f"[green]✓[/green] dex completed; wrote {len(written)} file(s):")
+                for p in written:
+                    try:
+                        rel = p.relative_to(paths.root)
+                        console.print(f"  [dim]-[/dim] {rel}")
+                    except ValueError:
+                        console.print(f"  [dim]-[/dim] {p}")
+                return
+        render_result(result, console, json_output=json_output)
+
+    asyncio.run(_do())

devrel_origin/cli/doctor.py

@@ -0,0 +1,178 @@
+"""`devrel doctor` — health checks for the current project."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import asdict, dataclass
+
+import typer
+from rich.console import Console
+
+from devrel_origin.project.config import ConfigError, ProjectConfig
+from devrel_origin.project.paths import (
+    ProjectNotFoundError,
+    ProjectPaths,
+    find_devrel_root,
+)
+from devrel_origin.project.state import SCHEMA_VERSION, get_schema_version
+
+console = Console()
+
+# LLM key requirement is one-of: Anthropic direct OR OpenRouter (multi-provider).
+LLM_KEY_OPTIONS: tuple[str, ...] = ("ANTHROPIC_API_KEY", "OPENROUTER_API_KEY")
+OPTIONAL_ENV = (
+    "GITHUB_TOKEN",
+    "FIRECRAWL_API_KEY",
+    "BRAVE_API_KEY",
+    "INSTANTLY_API_KEY",
+    "APOLLO_API_KEY",
+    "OPENAI_API_KEY",
+    "TELEGRAM_BOT_TOKEN",
+)
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: str  # 'pass' | 'warn' | 'fail'
+    detail: str = ""
+
+
+def _run_checks(paths: ProjectPaths) -> list[CheckResult]:
+    results: list[CheckResult] = []
+
+    # Python version.
+    py = sys.version_info
+    py_str = f"{py.major}.{py.minor}.{py.micro}"
+    if (py.major, py.minor) >= (3, 12):
+        results.append(CheckResult("python_version", "pass", py_str))
+    else:
+        results.append(CheckResult("python_version", "fail", f"{py_str} (requires >=3.12)"))
+
+    # Required files.
+    for label, fp in [
+        ("config.toml", paths.config_file),
+        ("voice.md", paths.voice_file),
+        ("style.md", paths.style_file),
+        ("slop-blocklist.md", paths.slop_file),
+    ]:
+        if fp.is_file():
+            results.append(CheckResult(label, "pass"))
+        else:
+            results.append(CheckResult(label, "fail", f"missing at {fp}"))
+
+    # Config parses.
+    if paths.config_file.is_file():
+        try:
+            cfg = ProjectConfig.load(paths.config_file)
+            results.append(CheckResult("config_parses", "pass", f"project={cfg.project.name}"))
+        except ConfigError as e:
+            results.append(CheckResult("config_parses", "fail", str(e)))
+
+    # State DB.
+    sv = get_schema_version(paths.state_db)
+    if sv is None:
+        results.append(CheckResult("state_db", "fail", "missing or unreadable; run `devrel init`"))
+    elif sv == SCHEMA_VERSION:
+        results.append(CheckResult("state_db", "pass", f"schema v{sv}"))
+    else:
+        results.append(
+            CheckResult(
+                "state_db",
+                "warn",
+                f"schema v{sv}, current is v{SCHEMA_VERSION}; run `devrel migrate`",
+            )
+        )
+
+    # LLM key: at least one of Anthropic direct or OpenRouter must be set.
+    # Pull keys out of .devrel/.env (or root .env) first so a user who set
+    # them via `devrel auth` and hasn't restarted their shell still passes.
+    from devrel_origin.cli._common import _load_project_env
+
+    _load_project_env(paths)
+    set_keys = [n for n in LLM_KEY_OPTIONS if os.environ.get(n)]
+    if set_keys:
+        results.append(CheckResult("llm_api_key", "pass", f"set: {', '.join(set_keys)}"))
+    else:
+        results.append(
+            CheckResult(
+                "llm_api_key",
+                "fail",
+                "no LLM key set; run `devrel auth` (Anthropic or OpenRouter)",
+            )
+        )
+
+    # Optional env.
+    for name in OPTIONAL_ENV:
+        val = os.environ.get(name)
+        results.append(
+            CheckResult(name, "pass" if val else "warn", "set" if val else "not set (optional)")
+        )
+
+    # KB freshness.
+    if paths.kb_dir.is_dir():
+        n = sum(1 for _ in paths.kb_dir.rglob("*.md"))
+        results.append(CheckResult("kb_files", "pass" if n > 0 else "warn", f"{n} markdown files"))
+    else:
+        results.append(CheckResult("kb_files", "warn", "kb/ missing"))
+
+    return results
+
+
+def _overall(results: list[CheckResult]) -> str:
+    if any(r.status == "fail" for r in results):
+        return "fail"
+    if any(r.status == "warn" for r in results):
+        return "warn"
+    return "ok"
+
+
+def _emit_pretty(results: list[CheckResult], overall: str) -> None:
+    icons = {"pass": "[green]✓[/green]", "warn": "[yellow]![/yellow]", "fail": "[red]✗[/red]"}
+    for r in results:
+        console.print(f"  {icons[r.status]} {r.name:<24} {r.detail}")
+    console.print()
+    label = {
+        "ok": "[bold green]All checks passed.[/bold green]",
+        "warn": "[bold yellow]Some warnings; nothing blocking.[/bold yellow]",
+        "fail": "[bold red]One or more checks failed.[/bold red]",
+    }[overall]
+    console.print(label)
+
+
+def _emit_json(results: list[CheckResult], overall: str) -> None:
+    typer.echo(
+        json.dumps(
+            {"status": overall, "checks": [asdict(r) for r in results]},
+            indent=2,
+        )
+    )
+
+
+def doctor_command(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit machine-readable JSON instead of pretty output.",
+    ),
+) -> None:
+    """Run health checks on the current project."""
+    try:
+        root = find_devrel_root()
+    except ProjectNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=1) from None
+
+    paths = ProjectPaths.from_root(root)
+    results = _run_checks(paths)
+    overall = _overall(results)
+
+    if json_output:
+        _emit_json(results, overall)
+    else:
+        _emit_pretty(results, overall)
+
+    if overall == "fail":
+        raise typer.Exit(code=1)

devrel_origin/cli/experiment.py

@@ -0,0 +1,29 @@
+"""`devrel experiment` — A/B experiment design via Nova."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+from rich.console import Console
+
+from devrel_origin.cli._common import build_atlas_or_exit, find_paths_or_exit, render_result
+
+console = Console()
+
+
+def experiment_command(
+    hypothesis: str = typer.Argument(..., help="The hypothesis to test."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Design an A/B experiment with power analysis via Nova."""
+    paths = find_paths_or_exit(console)
+    atlas = build_atlas_or_exit(paths, console)
+
+    async def _do() -> None:
+        result = await atlas.run_single_task(
+            "nova", f"Design experiment for hypothesis: {hypothesis}"
+        )
+        render_result(result, console, json_output=json_output)
+
+    asyncio.run(_do())