pmkit 0.1.1__py3-none-any.whl

pmkit/launch/collateral.py

@@ -0,0 +1,159 @@
+"""Tier-A collateral capture — record the real product working.
+
+The most credible, least-slop dev collateral is the tool itself in action. This module
+captures that authentically by reusing the pm-dogfood drivers: Playwright screenshots/video
+of a running app, asciinema CLI casts, and SVG/HTML rendered to PNG via the same browser. No
+AI-generated media (that's deferred v2).
+
+``plan_capture`` (pure) validates a capture spec; ``run_capture`` (live, gated) performs it.
+Each capture kind is gated on its tool's availability — a missing tool degrades that step to a
+clean skip, never a crash. Pure validation is unit-tested; the live pass is exercised by the
+scenario/integration run and on a real machine.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from typing import Optional
+
+CAPTURE_KINDS = ("screenshot", "video", "cli_cast", "diagram")
+
+
+def plan_capture(requests: list[dict]) -> list[dict]:
+    """Validate + normalize capture requests into a plan. Pure (no browser, no shell)."""
+    plan: list[dict] = []
+    for i, r in enumerate(requests):
+        kind = r.get("kind")
+        if kind not in CAPTURE_KINDS:
+            raise ValueError(f"request {i}: unknown kind {kind!r} (expected {CAPTURE_KINDS})")
+        name = r.get("name") or f"{kind}-{i}"
+        if kind in ("screenshot", "video"):
+            if not r.get("url"):
+                raise ValueError(f"request {i} ({kind}): missing 'url'")
+            plan.append({"kind": kind, "name": name, "url": r["url"],
+                         "steps": r.get("steps") or []})
+        elif kind == "cli_cast":
+            if not r.get("command"):
+                raise ValueError(f"request {i} (cli_cast): missing 'command'")
+            plan.append({"kind": kind, "name": name, "command": r["command"]})
+        else:  # diagram
+            if not r.get("html") and not r.get("html_path"):
+                raise ValueError(f"request {i} (diagram): needs 'html' or 'html_path'")
+            plan.append({"kind": kind, "name": name,
+                         "html": r.get("html"), "html_path": r.get("html_path")})
+    return plan
+
+
+def _tool_for(kind: str) -> str:
+    return "asciinema" if kind == "cli_cast" else "playwright/chromium"
+
+
+def capture_available(kind: str) -> bool:
+    """Is the tool needed for this capture kind installed and launchable?"""
+    if kind == "cli_cast":
+        return shutil.which("asciinema") is not None
+    # screenshot / video / diagram all need a launchable browser (reuse the dogfood gate).
+    from ..dogfood.ui import playwright_available
+    return playwright_available()
+
+
+def run_capture(plan: list[dict], outdir: str, *, url_timeout_ms: int = 15000) -> list[dict]:
+    """Perform the capture plan. Each step's tool is gated; unavailable -> clean skip.
+
+    Returns per-step results: ``{kind, name, ok, [path], [skipped], [reason]}``. Never raises
+    for a single step's failure — the run continues so independent captures still land.
+    """
+    os.makedirs(outdir, exist_ok=True)
+    results: list[dict] = []
+    for step in plan:
+        kind = step["kind"]
+        if not capture_available(kind):
+            results.append({"kind": kind, "name": step["name"], "ok": False,
+                            "skipped": True, "reason": f"{_tool_for(kind)} unavailable"})
+            continue
+        try:
+            path = _capture_one(step, outdir, url_timeout_ms)
+            results.append({"kind": kind, "name": step["name"], "ok": True, "path": path})
+        except Exception as e:
+            results.append({"kind": kind, "name": step["name"], "ok": False,
+                            "skipped": False, "reason": f"{type(e).__name__}: {e}"})
+    return results
+
+
+def _capture_one(step: dict, outdir: str, url_timeout_ms: int) -> Optional[str]:
+    kind = step["kind"]
+    if kind == "cli_cast":
+        return _capture_cli_cast(step, outdir)
+    if kind == "diagram":
+        return _capture_diagram(step, outdir)
+    return _capture_browser(step, outdir, url_timeout_ms)
+
+
+def _apply_steps(page, steps: list[dict]) -> None:
+    # Reuse the pm-dogfood Streamlit-aware UI stepping (fill+Enter+settle).
+    from ..dogfood.ui import _run_step, translate_steps
+    for s in translate_steps(steps):
+        _run_step(page, s)
+
+
+def _capture_browser(step: dict, outdir: str, url_timeout_ms: int) -> Optional[str]:
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            if step["kind"] == "video":
+                ctx = browser.new_context(record_video_dir=outdir)
+                page = ctx.new_page()
+                page.goto(step["url"], timeout=url_timeout_ms)
+                _apply_steps(page, step["steps"])
+                vid = page.video.path() if page.video else None
+                ctx.close()
+                return vid
+            page = browser.new_page()
+            page.goto(step["url"], timeout=url_timeout_ms)
+            _apply_steps(page, step["steps"])
+            out = os.path.join(outdir, f"{step['name']}.png")
+            page.screenshot(path=out, full_page=True)
+            return out
+        finally:
+            browser.close()
+
+
+def _capture_diagram(step: dict, outdir: str) -> Optional[str]:
+    from playwright.sync_api import sync_playwright
+
+    html_path = step.get("html_path")
+    tmp = None
+    if not html_path:
+        fd, tmp = tempfile.mkstemp(suffix=".html", prefix="pmkit-diagram-")
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(step["html"])
+        html_path = tmp
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch()
+            try:
+                page = browser.new_page()
+                page.goto(f"file://{os.path.abspath(html_path)}")
+                out = os.path.join(outdir, f"{step['name']}.png")
+                page.screenshot(path=out, full_page=True)
+                return out
+            finally:
+                browser.close()
+    finally:
+        if tmp:
+            os.unlink(tmp)
+
+
+def _capture_cli_cast(step: dict, outdir: str) -> Optional[str]:
+    import subprocess
+
+    out = os.path.join(outdir, f"{step['name']}.cast")
+    subprocess.run(
+        ["asciinema", "rec", "--overwrite", "--command", step["command"], out],
+        check=True, capture_output=True, text=True, timeout=120,
+    )
+    return out

pmkit/launch/drafts.py

@@ -0,0 +1,53 @@
+"""Draft starting-points + slop-critic verdicts — with a structural never-final guardrail.
+
+The drafting agent produces *starting-points* and the independent slop-critic judges them.
+This module stores and emits them. The guardrail is structural, not cosmetic: there is no
+"final"/"postable" state anywhere in the data model or this API, so nothing here can be
+mistaken for a ready post. Every emitted draft is labeled a starting-point the operator must
+rewrite in their own voice. The operator writes the final post and posts it.
+"""
+
+from __future__ import annotations
+
+DRAFT_KIND = "starting_point"  # the only kind — there is deliberately no 'final'/'postable'
+
+_PREAMBLE = (
+    "STARTING-POINTS — raw material, NOT posts. Rewrite each in your own voice; "
+    "never paste as-is. You write the final post and you post it."
+)
+
+
+def record_draft(
+    store,
+    product: str,
+    platform: str,
+    text: str,
+    *,
+    community: str | None = None,
+    critic: dict | None = None,
+) -> int:
+    """Store one draft starting-point (optionally with its slop-critic verdict)."""
+    return store.add_draft(product, platform, text, community=community, critic=critic)
+
+
+def emit(drafts: list[dict]) -> str:
+    """Render stored drafts, ALWAYS labeled starting-points; flag any the critic flagged."""
+    lines = [_PREAMBLE, ""]
+    if not drafts:
+        lines.append("_(no drafts)_")
+        return "\n".join(lines) + "\n"
+    for d in drafts:
+        loc = f"{d['platform']}" + (f" · {d['community']}" if d.get("community") else "")
+        lines.append(f"## [{d['id']}] {loc} — STARTING-POINT (rewrite before posting)")
+        if d.get("critic_flagged"):
+            critic = d.get("critic") or {}
+            tells = ", ".join(critic.get("tells", [])) or "reads as AI slop"
+            lines.append(f"> ⚠ slop-critic FLAGGED (score {critic.get('score', '?')}): {tells}")
+            if critic.get("suggestion"):
+                lines.append(f"> fix: {critic['suggestion']}")
+        elif d.get("critic_flagged") is False:
+            lines.append("> slop-critic: clear")
+        lines.append("")
+        lines.append(d["text"])
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

pmkit/launch/listen.py

@@ -0,0 +1,88 @@
+"""The listen loop — fold post-launch reactions back into the discovery backlog.
+
+This is what closes the funnel into a loop: after a launch, the reactions (comments,
+mentions, threads) are ingested as ``launch-feedback`` candidates through the *same*
+dedup/attach path discovery already uses (``backlog.find_existing`` → ``attach_evidence``
+or ``add_candidate``), reusing ``Config.min_engagement`` and ``dedup.find_near_duplicate``.
+Feedback that echoes a known opportunity accrues as evidence; a genuinely new pain becomes a
+new ``new`` candidate the funnel can pick up. Read-only — listening never engages or posts.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..backlog import Backlog, make_dedup_key
+from ..connectors import get_connectors
+from ..connectors.base import Config, ConnectorError
+from ..dedup import DEFAULT_THRESHOLD, find_near_duplicate
+
+SOURCE_TAG = "launch-feedback"
+
+
+def run_listen(
+    backlog: Backlog,
+    target: str,
+    connectors: Optional[list] = None,
+    cfg: Optional[Config] = None,
+    limit: int = 25,
+    near_threshold: float = DEFAULT_THRESHOLD,
+) -> dict:
+    """Ingest reactions for ``target`` as launch-feedback. Mirrors discovery's ingestion
+    flow but tags provenance ``launch-feedback`` (origin connector preserved)."""
+    cfg = cfg or Config.from_env()
+    connectors = connectors if connectors is not None else get_connectors()
+
+    summary = {
+        "target": target,
+        "fetched": 0,
+        "new": 0,
+        "merged": 0,
+        "low_confidence": 0,
+        "by_source": {},
+        "skipped": [],
+    }
+
+    current = [it for it in backlog.list() if it["target"] == target]
+
+    for conn in connectors:
+        ok, reason = conn.available(cfg)
+        if not ok:
+            summary["skipped"].append({"source": conn.name, "reason": reason})
+            continue
+        try:
+            cands = conn.fetch(target, cfg, limit)
+        except ConnectorError as e:
+            summary["skipped"].append({"source": conn.name, "reason": str(e)})
+            continue
+        except Exception as e:  # a connector bug must not abort the listen pass
+            summary["skipped"].append({"source": conn.name, "reason": f"unexpected: {e}"})
+            continue
+
+        summary["by_source"][conn.name] = len(cands)
+        for cand in cands:
+            summary["fetched"] += 1
+            low_conf = cand["engagement"] < cfg.min_engagement or not cand["source"].get("url")
+            # Retag provenance as launch-feedback, preserving the origin connector.
+            source = {**cand["source"], "type": SOURCE_TAG,
+                      "origin": cand["source"].get("type")}
+            key = make_dedup_key(target, cand["problem"])
+            dup = (backlog.find_existing(target, key)
+                   or find_near_duplicate(cand, current, near_threshold))
+            if dup is not None:
+                backlog.attach_evidence(dup["id"], [source])
+                summary["merged"] += 1
+                continue
+            opp_id = backlog.add_candidate(
+                target=target,
+                title=f"[launch-feedback] {cand['title']}",
+                problem=cand["problem"],
+                sources=[source],
+                low_confidence=low_conf,
+            )
+            summary["new"] += 1
+            if low_conf:
+                summary["low_confidence"] += 1
+            current.append({"id": opp_id, "title": cand["title"], "problem": cand["problem"]})
+
+    return summary

pmkit/launch/plan.py

@@ -0,0 +1,82 @@
+"""The emit-only launch plan renderer.
+
+Turns structured targets (produced by the ``pm-launch-targeter`` agent, each carrying its
+mod-policy verdict from ``policy.py``) into a dated checklist the operator follows. Pure and
+deterministic. **Emit-only**: this renders an artifact and creates no cron entries and posts
+nothing — the human owns timing and the act of posting.
+"""
+
+from __future__ import annotations
+
+# Human-readable verdict markers (ASCII — renders safely on any terminal).
+_MARK = {
+    "block": "BLOCK — DO NOT POST HERE",
+    "warn": "WARN — check the cited rule",
+    "ok": "OK",
+    "unavailable": "RULES UNAVAILABLE — check manually",
+    "unknown": "UNKNOWN — research policy first",
+}
+
+
+def build_plan(product: str, targets: list[dict]) -> dict:
+    """Validate + normalize targets into an ordered plan. Pure.
+
+    Each target: ``{platform, community|channel, [thread], [angle], [day], [policy]}`` where
+    ``policy`` is the dict from ``policy.resolve_policy`` (``{verdict, cited_rules, [note]}``).
+    """
+    norm: list[dict] = []
+    for i, t in enumerate(targets):
+        platform = t.get("platform")
+        community = t.get("community") or t.get("channel")
+        if not platform:
+            raise ValueError(f"target {i}: missing 'platform'")
+        if not community:
+            raise ValueError(f"target {i}: missing 'community'/'channel'")
+        policy = t.get("policy") or {}
+        norm.append({
+            "platform": platform,
+            "community": community,
+            "thread": t.get("thread"),
+            "angle": t.get("angle"),
+            "day": int(t.get("day", 0)),
+            "verdict": policy.get("verdict") or "unknown",
+            "cited_rules": policy.get("cited_rules") or [],
+            "note": policy.get("note"),
+        })
+    norm.sort(key=lambda x: (x["day"], x["platform"], x["community"]))
+    return {"product": product, "targets": norm}
+
+
+def render_markdown(plan: dict) -> str:
+    """Render the plan as a dated, emit-only checklist."""
+    lines = [
+        f"# Launch plan: {plan['product']}",
+        "",
+        "> Emit-only. pm-launch prepared this; **you** write the final post in your voice "
+        "and post it — the system never posts.",
+        "",
+    ]
+    targets = plan.get("targets", [])
+    if not targets:
+        lines.append("_(no targets)_")
+        return "\n".join(lines) + "\n"
+
+    by_day: dict[int, list[dict]] = {}
+    for t in targets:
+        by_day.setdefault(t["day"], []).append(t)
+
+    for day in sorted(by_day):
+        lines.append(f"## Day {day}")
+        for t in by_day[day]:
+            mark = _MARK.get(t["verdict"], t["verdict"])
+            lines.append(f"- [ ] **{t['platform']} · {t['community']}** — {mark}")
+            for r in t["cited_rules"]:
+                lines.append(f"    - rule: {r.get('text', '')}")
+            if t.get("note"):
+                lines.append(f"    - note: {t['note']}")
+            if t.get("thread"):
+                lines.append(f"    - thread: {t['thread']}")
+            if t.get("angle"):
+                lines.append(f"    - angle: {t['angle']}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

pmkit/launch/policy.py

@@ -0,0 +1,153 @@
+"""Moderator-policy research — the killer feature of the launch stage.
+
+For a community, produce a ``block`` / ``warn`` / ``ok`` verdict with the *cited rule(s)* so
+the operator never gets a post pulled by a moderator again. The verdict logic is a **pure
+function** (``decide_policy``) over structured rules, so it is reproducible and unit-testable.
+Reading a community's prose rules into that structure is judgment that belongs to the
+``pm-launch-policy`` agent; the live Reddit fetch here is a convenience for the deterministic
+path and is gated — a fetch failure degrades to a clean ``unavailable`` verdict, never a crash.
+
+Caching (``resolve_policy``) reuses ``LaunchStore``'s ``mod_policy_cache`` with a 30-day TTL.
+Non-Reddit platforms have no machine-readable rules; they return ``ok`` plus a norm note.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Optional
+
+from ..connectors.base import http_get_json
+
+# Keyword heuristics over rule text. BLOCK takes precedence over WARN; conservative by design
+# (advisory — the verdict cites the rule so the human makes the final call).
+_BLOCK_SIGNALS = (
+    "no self-promotion", "no self promotion", "no selfpromo", "no advertising",
+    "no promotion", "no marketing", "no blogspam", "no blog spam", "not allowed",
+    "prohibited", "banned", "zero tolerance", "no spam", "no soliciting",
+    "do not post your own", "no links to your own",
+)
+_WARN_SIGNALS = (
+    "ratio", "1:10", "9:1", "10%", "10 percent", "once per", "once a week",
+    "limit", "flair", "approval required", "must be approved", "account age",
+    "karma", "weekly thread", "megathread", "self-promotion saturday", "only on",
+    "must include", "no more than",
+)
+
+# Best-effort norm notes for platforms without machine-readable rules (R1 / Scope: others).
+NORM_NOTES = {
+    "hackernews": "No machine-readable rules. Use 'Show HN:' for your own work; one post; "
+                  "no reposting; engage genuinely in comments.",
+    "x": "No hard self-promo gate; norms favor a narrative thread over a bare link, and "
+         "replying in relevant conversations over broadcasting.",
+    "linkedin": "No hard self-promo gate; norms favor a story/lesson framing over a raw "
+                "announcement; external links can suppress reach.",
+}
+
+DEFAULT_TTL_DAYS = 30
+
+
+def decide_policy(rules: list[dict]) -> tuple[str, list[dict]]:
+    """Pure verdict over structured rules. Each rule is ``{"text": str, "url": str}``.
+
+    Returns ``(verdict, cited_rules)`` where verdict is ``block`` | ``warn`` | ``ok`` and
+    cited_rules is the subset that triggered a non-ok verdict (empty for ``ok``).
+    """
+    blockers = [r for r in rules if _matches(r, _BLOCK_SIGNALS)]
+    if blockers:
+        return "block", blockers
+    warners = [r for r in rules if _matches(r, _WARN_SIGNALS)]
+    if warners:
+        return "warn", warners
+    return "ok", []
+
+
+def _matches(rule: dict, signals: tuple[str, ...]) -> bool:
+    text = (rule.get("text") or "").lower()
+    return any(sig in text for sig in signals)
+
+
+def is_stale(fetched_at: str, ttl_days: int, now: Optional[datetime] = None) -> bool:
+    """Pure: is a cache row older than its TTL? Unparseable timestamps count as stale."""
+    now = now or datetime.now(timezone.utc)
+    try:
+        ts = datetime.fromisoformat(fetched_at)
+    except (ValueError, TypeError):
+        return True
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    return now - ts > timedelta(days=int(ttl_days))
+
+
+def parse_subreddit_rules(data: dict) -> list[dict]:
+    """Pure: turn Reddit's ``about/rules.json`` payload into structured rules."""
+    out: list[dict] = []
+    for r in (data or {}).get("rules", []):
+        name = (r.get("short_name") or "").strip()
+        desc = (r.get("description") or "").strip()
+        text = f"{name}: {desc}".strip(": ").strip()
+        if text:
+            out.append({"text": text, "url": ""})
+    return out
+
+
+def fetch_subreddit_rules(community: str, timeout: float = 15.0) -> list[dict]:
+    """Live fetch of a subreddit's rules (keyless public JSON). Raises on network failure;
+    the resolver catches that and degrades to an ``unavailable`` verdict."""
+    sub = community.strip().lstrip("/")
+    if sub.lower().startswith("r/"):
+        sub = sub[2:]
+    url = f"https://www.reddit.com/r/{sub}/about/rules.json"
+    data = http_get_json(url, {}, timeout)
+    return parse_subreddit_rules(data)
+
+
+def _default_fetcher(platform: str) -> Optional[Callable[[str], list[dict]]]:
+    if platform == "reddit":
+        return fetch_subreddit_rules
+    return None  # non-reddit: no machine-readable rules
+
+
+def resolve_policy(
+    store,
+    community: str,
+    *,
+    platform: str = "reddit",
+    fetcher: Optional[Callable[[str], list[dict]]] = None,
+    ttl_days: int = DEFAULT_TTL_DAYS,
+    now: Optional[datetime] = None,
+    use_cache: bool = True,
+) -> dict:
+    """Resolve a policy verdict, reading/refreshing the cache. Never raises on fetch failure.
+
+    Returns a dict: ``{platform, community, verdict, cited_rules, cached, [note], [error]}``.
+    """
+    if use_cache:
+        cached = store.get_policy(platform, community)
+        if cached and not is_stale(cached["fetched_at"], cached["ttl_days"], now):
+            return {
+                "platform": platform, "community": community,
+                "verdict": cached["verdict"], "cited_rules": cached["cited_rules"],
+                "cached": True,
+            }
+
+    fetcher = fetcher if fetcher is not None else _default_fetcher(platform)
+    if fetcher is None:
+        # Non-reddit platform with no machine-readable rules: ok + a norm note.
+        return {
+            "platform": platform, "community": community, "verdict": "ok",
+            "cited_rules": [], "cached": False,
+            "note": NORM_NOTES.get(platform, "No machine-readable rules; follow community norms."),
+        }
+    try:
+        rules = fetcher(community)
+    except Exception as e:  # network / parse failure -> clean unavailable, not a crash
+        return {
+            "platform": platform, "community": community, "verdict": "unavailable",
+            "cited_rules": [], "cached": False, "error": f"{type(e).__name__}: {e}",
+        }
+    verdict, cited = decide_policy(rules)
+    store.put_policy(platform, community, verdict, cited, ttl_days=ttl_days)
+    return {
+        "platform": platform, "community": community, "verdict": verdict,
+        "cited_rules": cited, "cached": False,
+    }