pmkit 0.1.1__py3-none-any.whl

pmkit/launch/store.py

@@ -0,0 +1,260 @@
+"""Launch-stage persistence: the state ledger + the mod-policy cache.
+
+Shares the backlog SQLite DB (one file for the whole funnel) but owns two tables it creates
+idempotently on open, mirroring ``backlog.py``'s bootstrap. Deterministic and unit-testable;
+no network, no posting.
+
+- ``launch_state`` — per (product, channel) ledger row: planned vs announced, where, when.
+- ``mod_policy_cache`` — per (platform, community) cached verdict + cited rules + freshness.
+  This module only stores/reads the cache; the *staleness* decision (re-fetch past TTL) lives
+  in ``policy.py`` so the verdict logic stays in one place.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from ..backlog import default_db_path
+
+# The four launch channels (Reddit gets full mod-policy research; others get norm notes).
+CHANNELS = ("reddit", "hackernews", "x", "linkedin")
+LAUNCH_STATUSES = ("planned", "announced")
+POLICY_VERDICTS = ("block", "warn", "ok", "unavailable")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class LaunchStore:
+    """Connection wrapper over the launch tables in the shared backlog DB."""
+
+    def __init__(self, db_path: Optional[str | Path] = None) -> None:
+        self.db_path = Path(db_path) if db_path is not None else default_db_path()
+        if str(self.db_path) != ":memory:":
+            self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn = sqlite3.connect(str(self.db_path))
+        self.conn.row_factory = sqlite3.Row
+        self._ensure_schema()
+
+    # ------------------------------------------------------------------ schema
+    def _ensure_schema(self) -> None:
+        self.conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS launch_state (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                product         TEXT NOT NULL,
+                channel         TEXT NOT NULL,
+                status          TEXT NOT NULL DEFAULT 'planned',
+                url             TEXT,
+                artifact_version TEXT,
+                opportunity_id  INTEGER,
+                announced_at    TEXT,
+                created_at      TEXT NOT NULL,
+                updated_at      TEXT NOT NULL
+            );
+            CREATE UNIQUE INDEX IF NOT EXISTS idx_launch_state_pc
+                ON launch_state(product, channel);
+
+            CREATE TABLE IF NOT EXISTS mod_policy_cache (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                platform    TEXT NOT NULL,
+                community   TEXT NOT NULL,
+                verdict     TEXT NOT NULL,
+                cited_rules TEXT NOT NULL DEFAULT '[]',
+                fetched_at  TEXT NOT NULL,
+                ttl_days    INTEGER NOT NULL DEFAULT 30
+            );
+            CREATE UNIQUE INDEX IF NOT EXISTS idx_mod_policy_pc
+                ON mod_policy_cache(platform, community);
+
+            -- Draft STARTING-POINTS only. There is deliberately no 'status'/'final'/
+            -- 'postable' column: the data model itself cannot represent a finished post,
+            -- so nothing here can ever be mistaken for one. The human writes the final.
+            CREATE TABLE IF NOT EXISTS launch_drafts (
+                id             INTEGER PRIMARY KEY AUTOINCREMENT,
+                product        TEXT NOT NULL,
+                platform       TEXT NOT NULL,
+                community      TEXT,
+                kind           TEXT NOT NULL DEFAULT 'starting_point',
+                text           TEXT NOT NULL,
+                critic_flagged INTEGER,
+                critic_score   REAL,
+                critic         TEXT,
+                created_at     TEXT NOT NULL
+            );
+            """
+        )
+        self.conn.commit()
+
+    def close(self) -> None:
+        self.conn.close()
+
+    def __enter__(self) -> "LaunchStore":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------ state ledger
+    def record_state(
+        self,
+        product: str,
+        channel: str,
+        *,
+        status: str = "planned",
+        url: Optional[str] = None,
+        artifact_version: Optional[str] = None,
+        opportunity_id: Optional[int] = None,
+    ) -> int:
+        """Upsert a (product, channel) ledger row. Returns its id."""
+        if status not in LAUNCH_STATUSES:
+            raise ValueError(f"status must be one of {LAUNCH_STATUSES}, got {status!r}")
+        now = _now()
+        existing = self.conn.execute(
+            "SELECT id FROM launch_state WHERE product = ? AND channel = ?",
+            (product, channel),
+        ).fetchone()
+        announced_at = now if status == "announced" else None
+        if existing is not None:
+            self.conn.execute(
+                """
+                UPDATE launch_state
+                   SET status = ?, url = COALESCE(?, url),
+                       artifact_version = COALESCE(?, artifact_version),
+                       opportunity_id = COALESCE(?, opportunity_id),
+                       announced_at = COALESCE(?, announced_at),
+                       updated_at = ?
+                 WHERE id = ?
+                """,
+                (status, url, artifact_version, opportunity_id, announced_at, now,
+                 int(existing["id"])),
+            )
+            self.conn.commit()
+            return int(existing["id"])
+        cur = self.conn.execute(
+            """
+            INSERT INTO launch_state
+                (product, channel, status, url, artifact_version, opportunity_id,
+                 announced_at, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (product, channel, status, url, artifact_version, opportunity_id,
+             announced_at, now, now),
+        )
+        self.conn.commit()
+        return int(cur.lastrowid)
+
+    def announce(self, product: str, channel: str, url: Optional[str] = None) -> int:
+        """Mark a (product, channel) as announced (status='announced', stamps time)."""
+        return self.record_state(product, channel, status="announced", url=url)
+
+    def list_state(self, product: Optional[str] = None) -> list[dict]:
+        if product:
+            rows = self.conn.execute(
+                "SELECT * FROM launch_state WHERE product = ? ORDER BY channel",
+                (product,),
+            ).fetchall()
+        else:
+            rows = self.conn.execute(
+                "SELECT * FROM launch_state ORDER BY product, channel"
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def status_counts(self, product: Optional[str] = None) -> dict[str, int]:
+        out = {s: 0 for s in LAUNCH_STATUSES}
+        for row in self.list_state(product):
+            out[row["status"]] = out.get(row["status"], 0) + 1
+        return out
+
+    # ------------------------------------------------------------ policy cache
+    def put_policy(
+        self,
+        platform: str,
+        community: str,
+        verdict: str,
+        cited_rules: list[dict],
+        ttl_days: int = 30,
+    ) -> None:
+        """Upsert a cached policy verdict for (platform, community)."""
+        if verdict not in POLICY_VERDICTS:
+            raise ValueError(f"verdict must be one of {POLICY_VERDICTS}, got {verdict!r}")
+        now = _now()
+        self.conn.execute(
+            """
+            INSERT INTO mod_policy_cache (platform, community, verdict, cited_rules,
+                                          fetched_at, ttl_days)
+            VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(platform, community) DO UPDATE SET
+                verdict = excluded.verdict,
+                cited_rules = excluded.cited_rules,
+                fetched_at = excluded.fetched_at,
+                ttl_days = excluded.ttl_days
+            """,
+            (platform, community, verdict, json.dumps(cited_rules), now, int(ttl_days)),
+        )
+        self.conn.commit()
+
+    def get_policy(self, platform: str, community: str) -> Optional[dict]:
+        """Return the cached verdict row (cited_rules decoded), or None. Freshness is the
+        caller's call — the row carries ``fetched_at`` and ``ttl_days``."""
+        row = self.conn.execute(
+            "SELECT * FROM mod_policy_cache WHERE platform = ? AND community = ?",
+            (platform, community),
+        ).fetchone()
+        if row is None:
+            return None
+        d: dict[str, Any] = dict(row)
+        d["cited_rules"] = json.loads(d.get("cited_rules") or "[]")
+        return d
+
+    # ----------------------------------------------------------- draft storage
+    # NOTE: ``kind`` is hardcoded to 'starting_point' on insert and there is no setter to
+    # change it — the never-final guardrail is structural, not a convention.
+    def add_draft(
+        self,
+        product: str,
+        platform: str,
+        text: str,
+        *,
+        community: Optional[str] = None,
+        critic: Optional[dict] = None,
+    ) -> int:
+        cur = self.conn.execute(
+            """
+            INSERT INTO launch_drafts
+                (product, platform, community, kind, text,
+                 critic_flagged, critic_score, critic, created_at)
+            VALUES (?, ?, ?, 'starting_point', ?, ?, ?, ?, ?)
+            """,
+            (
+                product, platform, community, text,
+                (1 if critic and critic.get("flagged") else 0) if critic else None,
+                (critic.get("score") if critic else None),
+                (json.dumps(critic) if critic else None),
+                _now(),
+            ),
+        )
+        self.conn.commit()
+        return int(cur.lastrowid)
+
+    def list_drafts(self, product: Optional[str] = None) -> list[dict]:
+        if product:
+            rows = self.conn.execute(
+                "SELECT * FROM launch_drafts WHERE product = ? ORDER BY id", (product,)
+            ).fetchall()
+        else:
+            rows = self.conn.execute(
+                "SELECT * FROM launch_drafts ORDER BY id"
+            ).fetchall()
+        out = []
+        for r in rows:
+            d = dict(r)
+            d["critic"] = json.loads(d["critic"]) if d.get("critic") else None
+            d["critic_flagged"] = bool(d["critic_flagged"]) if d["critic_flagged"] is not None else None
+            out.append(d)
+        return out

pmkit/rice.py

@@ -0,0 +1,54 @@
+"""RICE value-per-effort scoring.
+
+The composite is the classic RICE form: (reach * impact * confidence) / effort.
+
+- reach:       how many users/instances feel this (>= 0)
+- impact:      per-instance value when addressed (>= 0)
+- confidence:  0..1 multiplier on how trustworthy the estimate is
+- effort:      cost to build, in arbitrary effort units (> 0)
+
+Sub-scores are stored separately on the backlog item so the weighting can become
+tunable later (a deferred goal); this module is the single source of truth for the
+composite so the CLI and the reranker agree.
+"""
+
+from __future__ import annotations
+
+
+class RiceError(ValueError):
+    """Raised when RICE inputs are invalid (e.g., non-positive effort)."""
+
+
+def compute_rice(reach: float, impact: float, confidence: float, effort: float) -> float:
+    """Return the RICE composite. Effort must be > 0; confidence is clamped to 0..1.
+
+    Raises RiceError on non-positive effort (division would be undefined) or
+    negative reach/impact.
+    """
+    if effort is None or effort <= 0:
+        raise RiceError(f"effort must be > 0, got {effort!r}")
+    if reach is None or reach < 0:
+        raise RiceError(f"reach must be >= 0, got {reach!r}")
+    if impact is None or impact < 0:
+        raise RiceError(f"impact must be >= 0, got {impact!r}")
+    conf = _clamp01(confidence)
+    return (float(reach) * float(impact) * conf) / float(effort)
+
+
+def _clamp01(value: float) -> float:
+    if value is None:
+        return 0.0
+    return max(0.0, min(1.0, float(value)))
+
+
+def rank(items: list[dict]) -> list[dict]:
+    """Return items ordered by their ``rice`` value, highest first, None last.
+
+    Pure mirror of the backlog's ``list(sort="score")`` ordering — handy for the
+    reranker and for tests, and stable on ties by id.
+    """
+    def key(it: dict):
+        rice = it.get("rice")
+        return (rice is None, -(rice or 0.0), it.get("id", 0))
+
+    return sorted(items, key=key)

pmkit-0.1.1.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: pmkit
+Version: 0.1.1
+Summary: Human-first CLI for the pm-system opportunity funnel: discovery + backlog.
+Author: Kedar Dabhadkar
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: dogfood
+Requires-Dist: fastmcp<4,>=3; extra == 'dogfood'
+Requires-Dist: playwright>=1.40; extra == 'dogfood'
+Description-Content-Type: text/markdown
+
+# pmkit
+
+The human-first CLI for [pm-system](../README.md). Deterministic work — fetching signals,
+backlog CRUD, dedup, and RICE math — lives here so a person can run it directly and an agent
+can call the exact same surface.
+
+```bash
+uv tool install .        # or: pip install .
+pmkit --help
+```
+
+Core is stdlib-only (no third-party dependencies), so install is trivial and offline-friendly.
+
+The backlog database defaults to `~/.pmkit/backlog.db`; override with `PMKIT_DB_PATH`.
+Every command accepts `--json` for machine-readable output (agent parity).

pmkit-0.1.1.dist-info/RECORD

@@ -0,0 +1,33 @@
+pmkit/__init__.py,sha256=x0ZH-89458e4x58sbXW13EmuOxwWlRwN-xEaKwhcFtE,317
+pmkit/backlog.py,sha256=CuLzqC_Uanx-6DMCQUbHEQz2riAJJ7qt2VAov0lhHog,15306
+pmkit/cli.py,sha256=x-V6U2Xvv1nDMPs13P_JqJOeJf_ri4vON_zNlVdhwQE,29205
+pmkit/dedup.py,sha256=bOZygM9mXBrANBLQJxbX91EpIC2r4uuzzcBAkWFG7bM,2029
+pmkit/discover.py,sha256=NhcNjnPSiJZa7Mu-_zCnsAYA1qVSRgQ20gCieVLooS8,3294
+pmkit/killtest.py,sha256=jVWn3afILKdIULcKDY-ovJaOyyR1PwNR9i-NO60fqgE,1596
+pmkit/rice.py,sha256=xECtKswHwtWNJp1Dc0cdRhE0-2Url8NbcijvGDc1efU,1944
+pmkit/connectors/__init__.py,sha256=KIazn0T1kctsuBn0R_vhxZ8iVXZz4-erdYsL_ER8f88,1026
+pmkit/connectors/base.py,sha256=yTkSUSHubs_zk9IpUMdq2tLdWzsQVXNDBOmcZvrvZsI,2613
+pmkit/connectors/changelog.py,sha256=7rbDPK413hQRL9d2MzjhNBRBFVJG5-eII5CKJ3MX0h8,1369
+pmkit/connectors/github.py,sha256=45rmem-VXcrDIORC_qQQQMbm-b19yzU-Kf09sBItuB8,1977
+pmkit/connectors/hn.py,sha256=EmtSJtRvlowng4LISYNeaYowHhkcIDjW9I8CBHUN7c8,1412
+pmkit/connectors/reddit.py,sha256=i7A9c9L6c7Mk-E9FB-bzjZvbEMN5UpMoycldxOHoiWY,1483
+pmkit/connectors/web.py,sha256=qoA4jNABvJ9ol46GgJKUz-3rwn_WkWO3AHMNlRiJ1dE,1519
+pmkit/connectors/x.py,sha256=CZrpovieaT1ieogv-p6Edt0RmeI8UdK5Kqa6Jx5xuvA,1743
+pmkit/dogfood/__init__.py,sha256=L-VZm5_Iqo22U9q9HtBKLzWWkQrNcSm0DtGA-x8Dt90,386
+pmkit/dogfood/file_gaps.py,sha256=h9GwiskGFvEa5Ib4wJ3oMyVhmyL7Fm0dTKgp6zaIYgM,1924
+pmkit/dogfood/install.py,sha256=ugyso_NnqjOGmTMaDHsEfj-xaFtl8FBO7r2sfL0ajHo,4017
+pmkit/dogfood/mcp.py,sha256=2__gRhxYZ5qeTdO88F2uozl6i9z5qDr8vPwpoakrFKQ,3021
+pmkit/dogfood/report.py,sha256=QG-eGibQDihyRrPEr-5GaqmbYkvmLupSXQIWPbh5lcQ,5230
+pmkit/dogfood/sample.py,sha256=iUFQMj3TOkTtnyzeWxl7V43Kv7y226NiHrwc5FR7j18,954
+pmkit/dogfood/ui.py,sha256=PmC7eg0xMGjNVj7prW_NaNNAifCdXLtYvbRejChjotU,4605
+pmkit/launch/__init__.py,sha256=CBIRbHlBivy6e4W-DcIjFYQQVED8xt82Scbm7rveDhI,912
+pmkit/launch/collateral.py,sha256=zkacS6f32k7F34RrCnVZp7wOEugyYR1eP4p01RGjtN8,6393
+pmkit/launch/drafts.py,sha256=ZR-9OsyqnamOX2tgPNfmIaJRl8ihIkmg-6rA1j15ncQ,2214
+pmkit/launch/listen.py,sha256=aXNVrqbK26FRisO09vNB48IPpptTNoThZqmRqX61zf4,3500
+pmkit/launch/plan.py,sha256=XNXHhBqB2djpgrPDGEjA7qgKwlVd7e3FnYdOeWvZPNM,3195
+pmkit/launch/policy.py,sha256=_dsIXNzAh9NA6BmT0vfEbqFGURx6obVxx7NxOUsjW3Y,6545
+pmkit/launch/store.py,sha256=m0X_BgAO4vZwfugE8PA3IECSPK9VYvP6vR6n_M2IGHk,10458
+pmkit-0.1.1.dist-info/METADATA,sha256=RITi7Tx0VLYG1e1oYUB4Hk7MXscb2Fx0A_2bN_7bJ4w,980
+pmkit-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pmkit-0.1.1.dist-info/entry_points.txt,sha256=NjlrCvIRbg8e0Kl4SQ_NsnFPuQXAmxh-ih5IzPNdfDw,41
+pmkit-0.1.1.dist-info/RECORD,,

pmkit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pmkit-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pmkit = pmkit.cli:main