zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/onboard.py

@@ -0,0 +1,206 @@
+"""`zeno onboard`: one command that wires a fresh dogfooder up end-to-end.
+
+Orchestrates the three setup steps a new adopter would otherwise run by hand:
+
+  1. **Capture hook** - install the cc-bridge hook into Claude Code's settings so
+     every session is captured to ``~/.zeno/zeno.db`` (``zeno hook install``).
+  2. **HUD line** - wire the cognition statusLine. On a fresh machine the hook
+     step sets the full ``zeno-hud`` line; on a machine already running a popular
+     HUD (ccstatusline / claude-hud) that set is SKIPPED to avoid a clobber, so
+     this step stacks just the differentiated zeno line UNDER it (``zeno hud
+     install --target auto``). Auto-detect, laptop-safe (writes to
+     ``settings.local.json`` when ``settings.json`` is a symlinked dotfile).
+  3. **Doctor** - run the diagnostic suite and fold its verdict into the summary.
+
+This module owns NO install logic of its own: it composes ``hook_install``,
+``hud.hud_install``, and ``doctor`` so the behavior (idempotency, backups, the
+symlink redirect, off-tailnet local-only PASS) is inherited, never duplicated.
+
+The whole flow is idempotent (safe to re-run), honors ``--dry-run`` (prints the
+plan, writes nothing), and degrades gracefully off the tailnet: the API/identity
+doctor rows WARN but never FAIL, so a local-only adopt still finishes green.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class OnboardStep:
+    """One line of the onboard summary: a named setup step plus its outcome.
+
+    ``status`` is a short human verdict (e.g. "installed", "already wired",
+    "stacked under ccstatusline", "skipped"). ``notes`` are extra lines shown
+    indented under the step.
+    """
+
+    name: str
+    status: str = ""
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class OnboardResult:
+    """Structured result of an onboard run, rendered by the CLI layer.
+
+    Keeping the orchestration pure (returns data, prints nothing) is the same
+    shape ``doctor.run_doctor`` uses, so it unit-tests without capturing stdout.
+    """
+
+    dry_run: bool
+    settings_path: Path
+    steps: list[OnboardStep] = field(default_factory=list)
+    # doctor verdict, folded in so the summary names the next action
+    doctor_pass: int = 0
+    doctor_warn: int = 0
+    doctor_fail: int = 0
+    doctor_ran: bool = False
+
+
+def _resolve_settings_path(explicit: str | None) -> Path:
+    """The settings.json onboard writes the capture hook into.
+
+    Reuses the HUD installer's laptop-safe resolver so the hook AND the HUD line
+    land in the SAME file: ``~/.claude/settings.json`` normally, but the sibling
+    ``settings.local.json`` when ``settings.json`` is a symlink into a shared
+    dotfiles checkout (Mar's own setup). The doctor's ``check_capture_hook``
+    reads both files, so capture is still detected wherever it landed.
+    """
+    from .hud import hud_install as H  # noqa: PLC0415
+
+    return H.resolve_settings_path(explicit)
+
+
+def run_onboard(
+    *,
+    base_url: str,
+    settings_path: str | None = None,
+    ccstatusline_path: str | None = None,
+    dry_run: bool = False,
+    force: bool = False,
+    stamp: str | None = None,
+) -> OnboardResult:
+    """Run the end-to-end onboard and return a structured result (no printing).
+
+    Sequence is hook -> HUD -> doctor. The hook step installs the capture hook
+    and, when no existing statusLine is present, the full ``zeno-hud`` line. The
+    HUD step then auto-detects ccstatusline / claude-hud and stacks the cognition
+    line under an existing HUD (a friendly no-op when neither is present and the
+    hook already set ``zeno-hud``). Doctor runs last so its rows reflect the
+    just-installed hook.
+    """
+    from . import hook_install as HI  # noqa: PLC0415
+    from .doctor import (  # noqa: PLC0415
+        STATUS_FAIL,
+        STATUS_PASS,
+        STATUS_WARN,
+        run_doctor,
+    )
+    from .hud import hud_install as H  # noqa: PLC0415
+
+    resolved = _resolve_settings_path(settings_path)
+    result = OnboardResult(dry_run=dry_run, settings_path=resolved)
+
+    # ----- Step 1: capture hook (+ zeno-hud statusLine when slot is free) -----
+    hook_step = OnboardStep(name="Capture hook")
+    if dry_run:
+        st = HI.status(resolved)
+        if st["all_events_installed"]:
+            hook_step.status = "already installed"
+        elif st["events_installed"]:
+            hook_step.status = "partial -> would re-install all events"
+        else:
+            hook_step.status = "would install"
+        hook_step.notes.append(f"settings: {resolved}")
+        sl = "zeno-hud" if not st["statusline_zeno"] else "zeno-hud (already set)"
+        hook_step.notes.append(f"statusLine: would set {sl} unless one already exists")
+    else:
+        res = HI.install(resolved, statusline_command="zeno-hud", force=force, stamp=stamp)
+        hook_step.status = "installed"
+        hook_step.notes.append(f"events: {', '.join(res['events'])}")
+        if res["statusline"] == "set":
+            hook_step.notes.append("statusLine: zeno-hud")
+        elif res["statusline"] == "skipped-existing":
+            hook_step.notes.append(
+                "statusLine: kept your existing HUD (the cognition line stacks under it next)"
+            )
+        if res["backup"]:
+            hook_step.notes.append(f"backup: {res['backup']}")
+    result.steps.append(hook_step)
+
+    # ----- Step 2: HUD cognition line (auto-detect, laptop-safe) -----
+    hud_step = OnboardStep(name="HUD cognition line")
+    hud_res = H.install(
+        "auto",
+        settings_path=settings_path,
+        ccstatusline_path=Path(ccstatusline_path).expanduser() if ccstatusline_path else None,
+        dry_run=dry_run,
+        force=force,
+        stamp=stamp,
+    )
+    target = hud_res["target"]
+    tag = "would " if dry_run else ""
+    if target == "ccstatusline":
+        action = hud_res.get("action")
+        if action == "not-found":
+            hud_step.status = "ccstatusline config not found (skipped)"
+        elif action == "unchanged":
+            hud_step.status = "already stacked under ccstatusline"
+        else:
+            hud_step.status = f"{tag}stack under ccstatusline".strip()
+        hud_step.notes.append(f"config: {hud_res.get('config')}")
+    elif target == "claude-hud":
+        if hud_res.get("statusline") == "skipped-existing":
+            hud_step.status = "kept your existing statusLine (pass --force to replace)"
+        else:
+            hud_step.status = f"{tag}stack under claude-hud".strip()
+        hud_step.notes.append(f"settings: {hud_res.get('settings_resolved', resolved)}")
+    else:  # none
+        hud_step.status = "no separate HUD detected (zeno-hud line is your statusLine)"
+        hud_step.notes.append(
+            "install ccstatusline or claude-hud later, then re-run 'zeno onboard'"
+        )
+    result.steps.append(hud_step)
+
+    # ----- Step 3: doctor (skipped on dry-run; it only reads, but a dry-run
+    # promises zero side effects and a fresh hook isn't written yet anyway) -----
+    if not dry_run:
+        checks = run_doctor(
+            base_url=base_url,
+            db_path=_default_db_path(),
+            cache_path=_default_cache_path(),
+            settings_path=None,  # consult both settings.json + settings.local.json
+        )
+        result.doctor_ran = True
+        result.doctor_pass = sum(1 for c in checks if c.status == STATUS_PASS)
+        result.doctor_warn = sum(1 for c in checks if c.status == STATUS_WARN)
+        result.doctor_fail = sum(1 for c in checks if c.status == STATUS_FAIL)
+
+    return result
+
+
+def _zeno_home() -> Path:
+    import os  # noqa: PLC0415
+
+    return Path(os.environ.get("ZENO_HOME", str(Path.home() / ".zeno"))).expanduser()
+
+
+def _default_db_path() -> Path:
+    """``$ZENO_DB_PATH`` / ``$ZENO_HOME/zeno.db`` / ``~/.zeno/zeno.db``.
+
+    Resolved at call time (not import) so a test's ``ZENO_HOME`` / ``ZENO_DB_PATH``
+    env override is honored, matching how the rest of the CLI resolves the DB.
+    """
+    import os  # noqa: PLC0415
+
+    return Path(os.environ.get("ZENO_DB_PATH", str(_zeno_home() / "zeno.db"))).expanduser()
+
+
+def _default_cache_path() -> Path:
+    """``$ZENO_HOME/cognitive-state.json`` (the API-written DPSC-CP cache mirror).
+
+    Mirrors ``main.DEFAULT_COGNITIVE_STATE_CACHE`` but resolved at call time so a
+    test's ``ZENO_HOME`` override is honored (the live ``~/.zeno`` shield)."""
+    return _zeno_home() / "cognitive-state.json"

zeno_cli/outreach.py

@@ -0,0 +1,456 @@
+"""Rolodex-driven outreach via bunmail. Dry-run by default.
+
+Loads a rolodex canonical_contacts_*.csv, filters by tag + recency +
+suppression list, renders a personal hook per contact, and either
+prints a dry-run plan or (with explicit confirmation) sends through
+bunmail one mail at a time with a polite 2-second pace.
+
+Architectural notes:
+
+* Stdlib-only on the HTTP side (urllib.request) so the CLI doesn't grow
+  an httpx dep. The bunmail wire shape is the same one zeno_api.email
+  speaks, but we re-implement it here rather than importing zeno_api
+  because the CLI must not depend on the API server package.
+
+* Templates live under apps/api/.../email_templates and we import the
+  registry directly. The API package is on PYTHONPATH via conftest in
+  the test suite and via uv workspace in dev, so this is a flat import
+  with no runtime coupling to the FastAPI app itself.
+
+* "Dry-run by default" is the safety contract. Every code path that
+  could land an email in someone's inbox goes through send_one(), and
+  send_one() requires `confirmed=True`. The CLI sets `confirmed=True`
+  only after an interactive y/N prompt.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import re
+import urllib.error
+import urllib.request
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+# Hard ceiling, enforced server-side in the CLI. The CLI's own --max-sends
+# default is much lower (10); this is a backstop against the "I typed an
+# extra zero" mistake, not the normal control surface.
+HARD_MAX_SENDS = 100
+
+# Pause between sends. Aggressive enough that 100 sends finish in ~3.5 min,
+# slow enough that bunmail + downstream MX servers don't see a burst that
+# looks like spam.
+DEFAULT_SEND_PAUSE_SECS = 2.0
+
+
+@dataclass(frozen=True)
+class Contact:
+    """One row of the rolodex CSV, narrowed to fields outreach uses.
+
+    `tags` is the parsed semicolon-separated list. `last_contact_date` is
+    a parsed date when available; missing/unparseable falls back to None
+    and the recency filter treats those as "no recent contact" (eligible).
+    """
+
+    person_id: str
+    full_name: str
+    primary_email: str
+    organization: str
+    role: str
+    tags: tuple[str, ...]
+    city: str
+    tier: str
+    relationship_score: int
+    last_contact_date: date | None
+    notes: str
+
+
+# ---------------------------------------------------------------------------
+# CSV ingestion
+# ---------------------------------------------------------------------------
+
+
+def load_contacts_csv(path: str | Path) -> list[Contact]:
+    """Load + normalize a rolodex canonical_contacts_*.csv file.
+
+    Skips rows that have no primary_email (the rolodex carries some
+    contacts without one - we cannot mail them, so they're filtered out
+    at ingest, not at filter time). Everything else is preserved as-is;
+    cleanup is the rolodex repo's job.
+    """
+    path = Path(path)
+    rows: list[Contact] = []
+    with path.open("r", encoding="utf-8", newline="") as fh:
+        reader = csv.DictReader(fh)
+        for row in reader:
+            email = (row.get("primary_email") or "").strip()
+            if not email:
+                continue
+            tags_raw = (row.get("tags") or "").strip()
+            tags = tuple(t.strip() for t in tags_raw.split(";") if t.strip())
+            last_contact = _parse_date(row.get("last_contact_date"))
+            score_raw = (row.get("relationship_score") or "").strip()
+            try:
+                score = int(score_raw) if score_raw else 0
+            except ValueError:
+                score = 0
+            rows.append(
+                Contact(
+                    person_id=(row.get("person_id") or "").strip(),
+                    full_name=(row.get("full_name") or "").strip(),
+                    primary_email=email,
+                    organization=(row.get("organization") or "").strip(),
+                    role=(row.get("role_or_relationship") or "").strip(),
+                    tags=tags,
+                    city=(row.get("city") or "").strip(),
+                    tier=(row.get("tier") or "").strip(),
+                    relationship_score=score,
+                    last_contact_date=last_contact,
+                    notes=(row.get("notes") or "").strip(),
+                )
+            )
+    return rows
+
+
+def _parse_date(raw: str | None) -> date | None:
+    """Parse a YYYY-MM-DD date. Return None on missing/malformed."""
+    if not raw:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return None
+    try:
+        return datetime.strptime(raw, "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Suppression list
+# ---------------------------------------------------------------------------
+
+
+def load_suppression_list(path: str | Path) -> set[str]:
+    """Load apps/cli/data/outreach_suppression.txt into a set of lowercase emails.
+
+    File format: one email per line, "#" comments allowed, blank lines
+    ignored. Missing file is fine - returns an empty set. Comparing
+    case-insensitive because email local-parts are case-insensitive in
+    practice and we don't want a typo bypassing suppression.
+    """
+    path = Path(path)
+    if not path.exists():
+        return set()
+    out: set[str] = set()
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        out.add(line.lower())
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Filtering
+# ---------------------------------------------------------------------------
+
+
+def filter_contacts(
+    contacts: Iterable[Contact],
+    *,
+    filter_tag: str | None = None,
+    exclude_recent_days: int = 30,
+    suppression: set[str] | None = None,
+    today: date | None = None,
+) -> list[Contact]:
+    """Filter contacts down to "ok to mail today" list.
+
+    Filters applied (in order):
+
+      1. Tag match: if `filter_tag` is set, the contact must have that
+         tag (case-insensitive) in its tags tuple.
+      2. Recency: if last_contact_date is within `exclude_recent_days`
+         of today, drop it. We don't want to spam someone we already
+         talked to last week.
+      3. Suppression: if the email is in the suppression set
+         (case-insensitive), drop it. This is the hard opt-out list.
+
+    Sort order: relationship_score DESC then person_id ASC. Highest-
+    affinity contacts come first so a small --max-sends takes the best
+    candidates, not whoever's alphabetically first.
+    """
+    today = today or date.today()
+    cutoff = today - timedelta(days=exclude_recent_days)
+    suppression = suppression or set()
+    tag_lower = filter_tag.lower() if filter_tag else None
+
+    out: list[Contact] = []
+    for c in contacts:
+        if tag_lower is not None:
+            if not any(t.lower() == tag_lower for t in c.tags):
+                continue
+        if c.last_contact_date is not None and c.last_contact_date >= cutoff:
+            continue
+        if c.primary_email.lower() in suppression:
+            continue
+        out.append(c)
+
+    out.sort(key=lambda c: (-c.relationship_score, c.person_id))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Personal-hook rendering
+# ---------------------------------------------------------------------------
+
+
+def first_name(contact: Contact) -> str:
+    """First whitespace-token of full_name, stripped. Fallback: "there"."""
+    name = contact.full_name.strip()
+    if not name:
+        return "there"
+    return name.split()[0]
+
+
+def render_personal_hook(contact: Contact) -> str:
+    """Rule-based one-sentence "why I'm mailing you" line.
+
+    Priority order:
+      1. Engineering / Core Team tag -> a direct "you ship code, this is for you"
+      2. Founder / Executive tag at a small org -> "you'll know if this
+         pattern shows up in your team"
+      3. Investor / VC tag -> "thought you might want a look at what
+         we're building"
+      4. Tier-1 or high score (>= 500) -> "you've been in the
+         orbit since the early days"
+      5. Fallback: generic "given your background in {org}".
+
+    Hooks intentionally avoid emoji, exclamation marks, and any phrase
+    that could read as boilerplate. If we cannot make a personal
+    statement, we cut the message instead of pretending.
+    """
+    tag_set = {t.lower() for t in contact.tags}
+
+    if "engineering" in tag_set or "core team" in tag_set:
+        return (
+            "You spend your day in code and around agents, so the "
+            "babysitting-tax curve might either match what you feel or "
+            "tell you something you don't."
+        )
+
+    if ("founder" in tag_set or "executive" in tag_set) and contact.organization:
+        return (
+            f"Given your seat at {contact.organization}, this might show up "
+            "in your team's velocity before it shows up in any dashboard "
+            "you have today."
+        )
+
+    if "investor" in tag_set or "vc" in tag_set:
+        return (
+            "Sharing because you've seen a lot of dev-tools come through. "
+            "Curious whether this one reads like a real wedge or a "
+            "vitamin from your side."
+        )
+
+    if contact.tier.lower().startswith("tier-1") or contact.relationship_score >= 500:
+        return (
+            "You've been in the orbit since early on, so you get the "
+            "first look at what I've actually been building."
+        )
+
+    if contact.organization:
+        return f"Given your background in {contact.organization}, I thought " "this one might land."
+
+    return (
+        "Sharing because we've crossed paths before and I'd rather you "
+        "see it from me than from a launch tweet."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Bunmail sending (stdlib HTTP)
+# ---------------------------------------------------------------------------
+
+
+class OutreachError(RuntimeError):
+    """Raised on bunmail 4xx (stops the run) or transport failure."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+@dataclass(frozen=True)
+class SendOutcome:
+    """One row of the outreach-runs/ CSV."""
+
+    email: str
+    person_id: str
+    full_name: str
+    status: str  # "queued", "skipped", "error"
+    email_id: str
+    detail: str
+    sent_at: str  # ISO timestamp
+
+
+def send_one(
+    *,
+    bunmail_base_url: str,
+    bunmail_api_key: str,
+    sender: str,
+    contact: Contact,
+    subject: str,
+    text: str,
+    html: str | None,
+    confirmed: bool,
+) -> SendOutcome:
+    """Send one mail through bunmail. Returns a SendOutcome row.
+
+    SAFETY: refuses to send unless `confirmed=True`. A False or unset
+    `confirmed` flag returns a "skipped" outcome so dry-run prints can
+    use the same code path. This is a belt-and-braces guard - the CLI
+    won't even call this unless the user typed y/yes - but it means
+    nothing accidentally mails on a wrong call site.
+    """
+    sent_at = datetime.now().isoformat(timespec="seconds")
+    if not confirmed:
+        return SendOutcome(
+            email=contact.primary_email,
+            person_id=contact.person_id,
+            full_name=contact.full_name,
+            status="skipped",
+            email_id="",
+            detail="dry-run",
+            sent_at=sent_at,
+        )
+
+    body = {
+        "from": sender,
+        "to": contact.primary_email,
+        "subject": subject,
+        "text": text,
+    }
+    if html:
+        body["html"] = html
+
+    url = bunmail_base_url.rstrip("/") + "/api/v1/emails/send"
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {bunmail_api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            raw = response.read().decode("utf-8")
+            payload = _parse_json(raw)
+            email_id = str(payload.get("id") or payload.get("email_id") or "")
+            status = str(payload.get("status") or "queued")
+            return SendOutcome(
+                email=contact.primary_email,
+                person_id=contact.person_id,
+                full_name=contact.full_name,
+                status=status,
+                email_id=email_id,
+                detail="",
+                sent_at=sent_at,
+            )
+    except urllib.error.HTTPError as exc:
+        body_text = ""
+        try:
+            body_text = exc.read().decode("utf-8", errors="replace")
+        except Exception:
+            pass
+        if 400 <= exc.code < 500:
+            raise OutreachError(
+                f"bunmail {exc.code} on {contact.primary_email}: {body_text}",
+                status_code=exc.code,
+            ) from exc
+        return SendOutcome(
+            email=contact.primary_email,
+            person_id=contact.person_id,
+            full_name=contact.full_name,
+            status="error",
+            email_id="",
+            detail=f"http {exc.code}: {body_text[:120]}",
+            sent_at=sent_at,
+        )
+    except urllib.error.URLError as exc:
+        return SendOutcome(
+            email=contact.primary_email,
+            person_id=contact.person_id,
+            full_name=contact.full_name,
+            status="error",
+            email_id="",
+            detail=f"transport: {exc.reason}",
+            sent_at=sent_at,
+        )
+
+
+def _parse_json(raw: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        return {}
+    if not isinstance(parsed, dict):
+        return {}
+    return parsed
+
+
+# ---------------------------------------------------------------------------
+# Run-log writer
+# ---------------------------------------------------------------------------
+
+
+_TIMESTAMP_RE = re.compile(r"[^0-9-]+")
+
+
+def write_run_log(out_dir: str | Path, outcomes: list[SendOutcome]) -> Path:
+    """Write one CSV row per send under outreach-runs/YYYY-MM-DD-HHMM.csv.
+
+    Returns the absolute path of the file written. Always writes a file
+    (even if outcomes is empty) so the run leaves an audit trail. The
+    filename timestamp is the run start - if two runs happen the same
+    minute, the second overwrites; outreach is paced + interactive, so
+    that's not a realistic case.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+    # Defensive: strip anything weird the strftime locale might inject.
+    stamp = _TIMESTAMP_RE.sub("", stamp)
+    path = out_dir / f"{stamp}.csv"
+    with path.open("w", encoding="utf-8", newline="") as fh:
+        writer = csv.writer(fh)
+        writer.writerow(
+            [
+                "sent_at",
+                "person_id",
+                "full_name",
+                "email",
+                "status",
+                "email_id",
+                "detail",
+            ]
+        )
+        for o in outcomes:
+            writer.writerow(
+                [
+                    o.sent_at,
+                    o.person_id,
+                    o.full_name,
+                    o.email,
+                    o.status,
+                    o.email_id,
+                    o.detail,
+                ]
+            )
+    return path